Merge pull request #328 from mikeebowen/general-snippets

Extract code snippets and update documentation for v3

Author: lindalu-MSFT

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/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
 ---
 
@@ -23,77 +23,43 @@ This topic shows how to use the classes in the Open XML SDK for Office to add a
 
 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-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
-```
+### [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 <xref:DocumentFormat.OpenXml.Packaging.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 <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.
+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