Merge pull request #329 from OfficeDev/main

[admin] merge to live

Author: lindalu-MSFT

.gitignore

@@ -287,4 +287,6 @@ __pycache__/
 *.odx.cs
 *.xsd.cs
 
-docs/open-xml-docs/
+docs/open-xml-docs/
+samples/**/Properties/**/*
+samples/**/My\ Project/**/*

.openpublishing.publish.config.json

@@ -6,13 +6,42 @@
       "build_output_subfolder": "open-xml-docs",
       "locale": "en-us",
       "monikers": [],
-      "moniker_ranges": [],
+      "moniker_ranges": [
+        "openxml-2.7.1",
+        "openxml-2.7.2",
+        "openxml-2.8.0",
+        "openxml-2.8.1",
+        "openxml-2.9.0",
+        "openxml-2.9.1",
+        "openxml-2.10.0",
+        "openxml-2.10.1",
+        "openxml-2.11.0",
+        "openxml-2.11.1",
+        "openxml-2.11.2",
+        "openxml-2.11.3",
+        "openxml-2.12.0",
+        "openxml-2.12.1",
+        "openxml-2.12.2",
+        "openxml-2.12.3",
+        "openxml-2.13.0",
+        "openxml-2.13.1",
+        "openxml-2.14.0",
+        "openxml-2.15.0",
+        "openxml-2.16.0",
+        "openxml-2.17.1",
+        "openxml-2.18.0",
+        "openxml-2.19.0",
+        "openxml-2.20.0",
+        "openxml-3.0.0",
+        "openxml-3.0.1"
+      ],
       "open_to_public_contributors": true,
       "customized_tasks": {
         "docset_prebuild": [
           "_dependentPackages/CommonPlugins/tools/JoinTOC.ps1"
         ]
       },
+      "xref_query_tags": [ "/dotnet" ],
       "type_mapping": {
         "Conceptual": "Content",
         "ManagedReference": "Content",

docs/about-the-open-xml-sdk.md

@@ -62,11 +62,11 @@ The SDK supports the following common tasks/scenarios:
 
 ## Open XML SDK for Office
 
-The Open XML SDK provides the namespaces and members to support the Microsoft Office 2013. The Open XML SDK can also read ISO/IEC 29500 Strict Format files. The Strict format is a subset of the Transitional format that does not include legacy features - this makes it theoretically easier for a new implementer to support since it has a smaller technical footprint.
+The Open XML SDK provides the namespaces and members to support the Microsoft Office. The Open XML SDK can also read ISO/IEC 29500 Strict Format files. The Strict format is a subset of the Transitional format that does not include legacy features - this makes it theoretically easier for a new implementer to support since it has a smaller technical footprint.
 
 The SDK supports the following common tasks/scenarios:
 
-- **Support of Office 2013 Preview file format**  In addition to the Open XML SDK for Microsoft Office classes, Open XML SDK provides new classes that enable you to write and build applications to manipulate Open XML file extensions of the new Office 2013 features.
+- **Support of Office Preview file format**  In addition to the Open XML SDK for Microsoft Office classes, Open XML SDK provides new classes that enable you to write and build applications to manipulate Open XML file extensions of the new Office features.
 - **Reads ISO Strict Document File**  Open XML SDK can read ISO/IEC 29500 Strict Format files. When the Open XML SDK API opens a Strict Format file, each Open XML part in the file is loaded to an **OpenXmlPart**  class of the Open XML SDK by mapping `https://purl.oclc.org/ooxml/` namespaces to the corresponding `https://schemas.openxmlformats.org/` namespaces.
 - **Fixes to the Open XML SDK for Microsoft Office**  Open XML SDK includes fixes to known issues in the Open XML SDK for Microsoft Office. These include lost whitespaces in PowerPoint presentations and an issue with the Custom UI in Word documents where a specified argument was reported as being out of the range of valid values.
 

docs/general/diagnosticids.md

@@ -5,21 +5,21 @@ ms.suite: office
 ms.author: o365devx
 author: o365devx
 ms.topic: conceptual
-ms.date: 11/01/2017
+ms.date: 01/08/2025
 ms.localizationpriority: high
 ---
 
 # Diagnostic IDs
 
-Diagnostic IDs are used to identify APIs or patterns that can raise compiler warnings or errors. This can be done via [ObsoleteAttribute](/dotnet/api/system.obsoleteattribute.diagnosticid) or [ExperimentalAttribute](/dotnet/api/system.diagnostics.codeanalysis.experimentalattribute). These can be suppressed at the consumer level for each diagnostic id.
+Diagnostic IDs are used to identify APIs or patterns that can raise compiler warnings or errors. This can be done via <xref:System.ObsoleteAttribute.DiagnosticId*> or <xref:System.Diagnostics.CodeAnalysis.ExperimentalAttribute>. These can be suppressed at the consumer level for each diagnostic id.
 
 ## Experimental APIs
 
 ### OOXML0001
 
 **Title**: IPackage related APIs are currently experimental
 
-As of v3.0, a new abstraction layer was added in between `System.IO.Packaging` and `DocumentFormat.OpenXml.Packaging.OpenXmlPackage`. This is currently experimental, but can be used if needed. This will be stabalized in a future release, and may or may not require code changes.
+As of v3.0, a new abstraction layer was added in between `System.IO.Packaging` and `DocumentFormat.OpenXml.Packaging.OpenXmlPackage`. This is currently experimental, but can be used if needed. This will be stabilized in a future release, and may or may not require code changes.
 
 ## Suppress warnings
 

docs/general/features.md

@@ -38,20 +38,21 @@ private sealed class PrivateFeature
 {
 }
 ```
+
 > [!NOTE]
 > The feature collection on elements is readonly. This is due to memory issues if it is made writeable. If this is needed, please engage on https://github.com/dotnet/open-xml-sdk to let us know your scenario.
 
 ## Visualizing Registered Features
 
-The in-box implementations of the `IFeatureCollection` provide a helpful debug view so you can see what features are available and what their properties/fields are:
+The in-box implementations of the <xref:DocumentFormat.OpenXml.Features.IFeatureCollection> provide a helpful debug view so you can see what features are available and what their properties/fields are:
 
 ![Features Debug View](../media/feature-debug-view.png)
 
 ## Available Features
 
 The features that are currently available are described below and at what scope they are available:
 
-### IDisposableFeature
+### <xref:DocumentFormat.OpenXml.Features.IDisposableFeature>
 
 This feature allows for registering actions that need to run when a package or a part is destroyed or disposed:
 
@@ -65,7 +66,7 @@ part.Features.Get<IDisposableFeature>().Register(() => /* Some action that is ca
 
 Packages and parts will have their own implementations of this feature. Elements will retrieve the feature for their containing part if available.
 
-### IPackageEventsFeature
+### <xref:DocumentFormat.OpenXml.Features.IPackageEventsFeature>
 
 This feature allows getting event notifications of when a package is changed:
 
@@ -79,7 +80,7 @@ var feature = package.Features.GetRequired<IPackageEventsFeature>();
 > [!NOTE]
 > There may be times when the package is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one.
 
-### IPartEventsFeature
+### <xref:DocumentFormat.OpenXml.Features.IPartEventsFeature>
 
 This feature allows getting event notifications of when an event is being created. This is a feature that is added to the part or package:
 
@@ -95,7 +96,7 @@ Generally, assume that there may be a singleton implementation for the events an
 > [!NOTE]
 > There may be times when the part is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one.
 
-### IPartRootEventsFeature
+### <xref:DocumentFormat.OpenXml.Features.IPartRootEventsFeature>
 
 This feature allows getting event notifications of when a part root is being modified/loaded/created/etc. This is a feature that is added to the part level feature:
 
@@ -111,11 +112,11 @@ Generally, assume that there may be a singleton implementation for the events an
 > [!NOTE]
 > There may be times when the part root is changed but an event is not fired. Not all areas have been identified where it would make sense to raise an event. Please file an issue if you find one.
 
-### IRandomNumberGeneratorFeature
+### <xref:DocumentFormat.OpenXml.Features.IRandomNumberGeneratorFeature>
 
 This feature allows for a shared service to generate random numbers and fill an array.
 
-### IParagraphIdGeneratorFeature
+### <xref:DocumentFormat.OpenXml.Features.IParagraphIdGeneratorFeature>
 
 This feature allows for population and tracking of elements that contain paragraph ids. By default, this will ensure uniqueness of values and ensure that values that do exist are valid per the constraints of the standard. To use this feature:
 
@@ -159,21 +160,3 @@ body2.AddChild(p2);
 Assert.NotEqual(p1.ParagraphId, p2.ParagraphId);
 Assert.Equal(2, shared.Count);
 ```
-
-### IPartRootXElementFeature
-
-This feature allows operating on an `OpenXmlPart` by using XLinq features and directly manipulating `XElement` nodes.
-
-```csharp
-OpenXmlPart part = GetSomePart();
-
-var node = new(W.document, new XAttribute(XNamespace.Xmlns + "w", W.w),
-    new XElement(W.body,
-        new XElement(W.p,
-            new XElement(W.r,
-                new XElement(W.t, "Hello World!")))));
-
-part.SetXElement(node);
-```
-
-This `XElement` is cached but will be kept in sync with the underlying part if it were to change.

docs/general/how-to-add-a-new-document-part-that-receives-a-relationship-id-to-a-package.md

@@ -11,14 +11,14 @@ ms.suite: office
 ms.author: o365devx
 author: o365devx
 ms.topic: conceptual
-ms.date: 11/01/2017
+ms.date: 01/08/2025
 ms.localizationpriority: medium
 ---
 
 # Add a new document part that receives a relationship ID to a package
 
 This topic shows how to use the classes in the Open XML SDK for
-Office to add a document part (file) that receives a relationship **Id** parameter for a word
+Office to add a document part (file) that receives a relationship `Id` parameter for a word
 processing document.
 
 
@@ -32,39 +32,51 @@ processing document.
 [!include[Structure](../includes/word/structure.md)]
 
 -----------------------------------------------------------------------------
-## Sample Code 
-The following code, adds a new document part that contains custom XML
-from an external file and then populates the document part. You can call
-the method **AddNewPart** by using a call like
-the following code example.
-
-### [C#](#tab/cs-0)
-```csharp
-    string document = @"C:\Users\Public\Documents\MyPkg1.docx";
-    AddNewPart(document);
-```
-
-### [Visual Basic](#tab/vb-0)
-```vb
-    Dim document As String = "C:\Users\Public\Documents\MyPkg1.docx"
-    AddNewPart(document)
-```
+
+## How the Sample Code Works
+
+The sample code, in this how-to, starts by passing in a parameter that represents the path to the Word document. It then creates
+a new WordprocessingDocument object within a using statement.
+
+### [C#](#tab/cs-1)
+[!code-csharp[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/cs/Program.cs#snippet1)]
+
+### [Visual Basic](#tab/vb-1)
+[!code-vb[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/vb/Program.vb#snippet1)]
+***
+
+It then adds the MainDocumentPart part in the new word processing document, with the relationship ID, rId1. It also adds the `CustomFilePropertiesPart` part and a `CoreFilePropertiesPart` in the new word processing document.
+
+### [C#](#tab/cs-2)
+[!code-csharp[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/cs/Program.cs#snippet2)]
+
+### [Visual Basic](#tab/vb-2)
+[!code-vb[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/vb/Program.vb#snippet2)]
 ***
 
+The code then adds the `DigitalSignatureOriginPart` part, the `ExtendedFilePropertiesPart` part, and the `ThumbnailPart` part in the new word processing document with realtionship IDs rId4, rId5, and rId6.
 
-The following is the complete code example in both C\# and Visual Basic.
+> [!NOTE]
+> The <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.AddNewPart*> method creates a relationship from the current document part to the new document part. This method returns the new document part. Also, you can use the <a href="xref:DocumentFormat.OpenXml.Packaging.DataPart.FeedData*?displayProperty=nameWithType"/> method to fill the document part.
+
+## Sample Code
+
+The following code, adds a new document part that contains custom XML
+from an external file and then populates the document part. Below is the
+complete code example in both C\# and Visual Basic.
 
 ### [C#](#tab/cs)
-[!code-csharp[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/cs/Program.cs)]
+[!code-csharp[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/cs/Program.cs#snippet0)]
 
 ### [Visual Basic](#tab/vb)
-[!code-vb[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/vb/Program.vb)]
+[!code-vb[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/vb/Program.vb#snippet0)]
+***
 
 -----------------------------------------------------------------------------
-## See also 
+## See also
 
 
 - [Open XML SDK class library reference](/office/open-xml/open-xml-sdk)
-  
+
 
 

docs/general/how-to-add-a-new-document-part-to-a-package.md

@@ -9,7 +9,7 @@ ms.suite: office
 ms.author: o365devx
 author: o365devx
 ms.topic: conceptual
-ms.date: 03/22/2022
+ms.date: 01/08/2025
 ms.localizationpriority: medium
 ---
 
@@ -21,79 +21,45 @@ This topic shows how to use the classes in the Open XML SDK for Office to add a
 
 ## Get a WordprocessingDocument object
 
-The code starts with opening a package file by passing a file name to one of the overloaded **[Open()](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.open.aspx)** methods of the **[DocumentFormat.OpenXml.Packaging.WordprocessingDocument](https://msdn.microsoft.com/library/office/documentformat.openxml.packaging.wordprocessingdocument.aspx)** that takes a string and a Boolean value that specifies whether the file should be opened for editing or for read-only access. In this case, the Boolean value is **true** specifying that the file should be opened in read/write mode.
-
-### [C#](#tab/cs-0)
-```csharp
-    using (WordprocessingDocument wordDoc = WordprocessingDocument.Open(document, true))
-    {
-        // Insert other code here.
-    }
-```
-
-### [Visual Basic](#tab/vb-0)
-```vb
-    Using wordDoc As WordprocessingDocument = WordprocessingDocument.Open(document, True)
-        ' Insert other code here.
-    End Using
-```
+The code starts with opening a package file by passing a file name to one of the overloaded <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument.Open%2A> methods of the <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> that takes a string and a Boolean value that specifies whether the file should be opened for editing or for read-only access. In this case, the Boolean value is `true` specifying that the file should be opened in read/write mode.
+
+### [C#](#tab/cs-1)
+[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs#snippet1)]
+
+### [Visual Basic](#tab/vb-1)
+[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb#snippet1)]
 ***
 
 
-The **using** statement provides a recommended alternative to the typical .Create, .Save, .Close sequence. It ensures that the **Dispose** method (internal method used by the Open XML SDK to clean up resources) is automatically called when the closing brace is reached. The block that follows the **using** statement establishes a scope for the object that is created or named in the **using** statement, in this case **wordDoc**. Because the **WordprocessingDocument** class in the Open XML SDK
-automatically saves and closes the object as part of its **System.IDisposable** implementation, and because the **Dispose** method is automatically called when you exit the block; you do not have to explicitly call **Save** and **Close**, as long as you use **using**.
+[!include[Using Statement](../includes/word/using-statement.md)]
 
 [!include[Structure](../includes/word/structure.md)]
 
 ## How the sample code works
 
-After opening the document for editing, in the **using** statement, as a **WordprocessingDocument** object, the code creates a reference to the **MainDocumentPart** part and adds a new custom XML part. It then reads the contents of the external
-file that contains the custom XML and writes it to the **CustomXmlPart** part.
+After opening the document for editing, in the `using` statement, as a <xref:DocumentFormat.OpenXml.Packaging.WordprocessingDocument> object, the code creates a reference to the `MainDocumentPart` part and adds a new custom XML part. It then reads the contents of the external
+file that contains the custom XML and writes it to the `CustomXmlPart` part.
 
 > [!NOTE]
 > To use the new document part in the document, add a link to the document part in the relationship part for the new part.
 
-### [C#](#tab/cs-1)
-```csharp
-    MainDocumentPart mainPart = wordDoc.MainDocumentPart;
-    CustomXmlPart myXmlPart = mainPart.AddCustomXmlPart(CustomXmlPartType.CustomXml);
-
-    using (FileStream stream = new FileStream(fileName, FileMode.Open))
-    {
-        myXmlPart.FeedData(stream);
-    }
-```
-
-### [Visual Basic](#tab/vb-1)
-```vb
-    Dim mainPart As MainDocumentPart = wordDoc.MainDocumentPart
-
-    Dim myXmlPart As CustomXmlPart = mainPart.AddCustomXmlPart(CustomXmlPartType.CustomXml)
+### [C#](#tab/cs-2)
+[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs#snippet2)]
 
-    Using stream As New FileStream(fileName, FileMode.Open)
-        myXmlPart.FeedData(stream)
-    End Using
-```
+### [Visual Basic](#tab/vb-2)
+[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb#snippet2)]
 ***
 
 
 ## Sample code
 
-The following code adds a new document part that contains custom XML from an external file and then populates the part. To call the AddCustomXmlPart method in your program, use the following example that modifies the file "myPkg2.docx" by adding a new document part to it.
+The following code adds a new document part that contains custom XML from an external file and then populates the part. To call the `AddCustomXmlPart` method in your program, use the following example that modifies a file by adding a new document part to it.
 
-### [C#](#tab/cs-2)
-```csharp
-    string document = @"C:\Users\Public\Documents\myPkg2.docx";
-    string fileName = @"C:\Users\Public\Documents\myXML.xml";
-    AddNewPart(document, fileName);
-```
+### [C#](#tab/cs-3)
+[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs#snippet3)]
 
-### [Visual Basic](#tab/vb-2)
-```vb
-    Dim document As String = "C:\Users\Public\Documents\myPkg2.docx"
-    Dim fileName As String = "C:\Users\Public\Documents\myXML.xml"
-    AddNewPart(document, fileName)
-```
+### [Visual Basic](#tab/vb-3)
+[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb#snippet3)]
 ***
 
 
@@ -103,10 +69,11 @@ The following code adds a new document part that contains custom XML from an ext
 Following is the complete code example in both C\# and Visual Basic.
 
 ### [C#](#tab/cs)
-[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs)]
+[!code-csharp[](../../samples/word/add_a_new_part_to_a_package/cs/Program.cs#snippet0)]
 
 ### [Visual Basic](#tab/vb)
-[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb)]
+[!code-vb[](../../samples/word/add_a_new_part_to_a_package/vb/Program.vb#snippet0)]
+***
 
 ## See also