Merge pull request #174 from OfficeDev/main

[admin] merge to live

Author: lindalu-MSFT

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

@@ -27,7 +27,7 @@ The document parts in an Open XML package are created as XML markup. Because XML
 
 Structurally, an Open XML document is an Open Packaging Conventions (OPC) package. As stated previously, a package is composed of a collection of document parts. Each part has a part name that consists of a sequence of segments or a pathname such as "/word/theme/theme1.xml." The package contains a [Content\_Types].xml part that allows you to determine the content type of all document parts in the package. A set of explicit relationships for a source package or part is contained in a relationships part that ends with the .rels extension.
 
-Word processing documents are described by using WordprocessingML markup. For more information, see [Working with WordprocessingML documents (Open XML SDK)](working-with-wordprocessingml-documents.md). A WordprocessingML document is composed of a collection of stories where each story is one of the following:
+Word processing documents are described by using WordprocessingML markup. For more information, see [Working with WordprocessingML documents](word/overview.md). A WordprocessingML document is composed of a collection of stories where each story is one of the following:
 
 - Main document (the only required story)
 - Glossary document
@@ -36,32 +36,22 @@ Word processing documents are described by using WordprocessingML markup. For mo
 - Text box
 - Footnote and endnote
 
-Presentations are described by using PresentationML markup. For more information, see [Working with PresentationML documents (Open XML SDK)](working-with-presentationml-documents.md). Presentation packages can contain the following document parts:
+Presentations are described by using PresentationML markup. For more information, see [Working with PresentationML documents](presentation/overview.md). Presentation packages can contain the following document parts:
 
 - Slide master
 - Notes master
 - Handout master
 - Slide layout
 - Notes
 
-Spreadsheet workbooks are described by using SpreadsheetML markup. For more information, see [Working with SpreadsheetML documents (Open XML SDK)](working-with-spreadsheetml-documents.md). Workbook packages can contain:
+Spreadsheet workbooks are described by using SpreadsheetML markup. For more information, see [Working with SpreadsheetML documents](spreadsheet/overview.md). Workbook packages can contain:
 
 - Workbook part (required part)
 - One or more worksheets
 - Charts
 - Tables
 - Custom XML
 
-## Open XML SDK 1.0
-
-Version 1 of the Open XML SDK simplified the manipulation of Open XML packages. The Open XML SDK Application Programming Interface (API) encapsulates many of the common tasks that you typically perform on Open XML packages, so you can perform complex operations with just a few lines of code. Some common tasks:
-
-- **Search**  With a few lines of code, you can search a collection of Excel 2007 worksheets for some arbitrary data.
-- **Document assembly**  You can create documents by combining the document parts of existing documents programmatically. For example, you can pull slides from various PowerPoint 2007 presentations to create a single presentation.
-- **Validation**  With a few lines of code, you can validate the document parts in a package or validate an entire package against a schema.
-- **Data update**  With the Open XML object model, you can easily modify the data in multiple packages.
-- **Privacy**  With a few lines of code, you can remove comments and other personal information from a document before it is distributed.
-
 ## Open XML SDK for Microsoft Office
 
 The SDK supports the following common tasks/scenarios:

docs/general/diagnosticids.md

@@ -0,0 +1,59 @@
+---
+title: Diagnostic IDs
+ms.suite: office
+
+ms.author: o365devx
+author: o365devx
+ms.topic: conceptual
+ms.date: 11/01/2017
+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.
+
+## 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.
+
+## Suppress warnings
+
+It's recommended that you use an available workaround whenever possible. However, if you cannot change your code, you can suppress warnings through a `#pragma` directive or a `<NoWarn>` project setting. If you must use the obsolete or experimental APIs and the `OOXMLXXXX` diagnostic does not surface as an error, you can suppress the warning in code or in your project file.
+
+To suppress the warnings in code:
+
+```csharp
+// Disable the warning.
+#pragma warning disable OOXML0001
+
+// Code that uses obsolete or experimental API.
+//...
+
+// Re-enable the warning.
+#pragma warning restore OOXML0001
+```
+
+To suppress the warnings in a project file:
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+   <TargetFramework>net6.0</TargetFramework>
+   <!-- NoWarn below suppresses SYSLIB0001 project-wide -->
+   <NoWarn>$(NoWarn);OOXML0001</NoWarn>
+   <!-- To suppress multiple warnings, you can use multiple NoWarn elements -->
+   <NoWarn>$(NoWarn);OOXML0001</NoWarn>
+   <NoWarn>$(NoWarn);OTHER_WARNING</NoWarn>
+   <!-- Alternatively, you can suppress multiple warnings by using a semicolon-delimited list -->
+   <NoWarn>$(NoWarn);OOXML0001;OTHER_WARNING</NoWarn>
+  </PropertyGroup>
+</Project>
+```
+
+> [!NOTE]
+> Suppressing warnings in this way only disables the obsoletion warnings you specify. It doesn't disable any other warnings, including obsoletion warnings with different diagnostic IDs.

docs/general/features.md

@@ -0,0 +1,179 @@
+---
+title: Custom SDK Features
+ms.suite: office
+
+ms.author: o365devx
+author: o365devx
+ms.topic: conceptual
+ms.date: 11/13/2023
+ms.localizationpriority: medium
+---
+
+# Custom SDK Features
+
+Features in the Open XML SDK are available starting in v2.14.0 that allows for behavior and state to be contained within the document or part and customized without reimplementing the containing package or part. This is accessed via `Features` property  on packages, parts, and elements.
+
+This is an implementation of the [strategy pattern](https://refactoring.guru/design-patterns/strategy) that makes it easy to replace behavior on the fly. It is modeled after the [request features](/aspnet/core/fundamentals/request-features) in ASP.NET Core.
+
+## Feature inheritance
+
+Packages, parts, and elements all have their own feature collection. However, they will also inherit the containing part and package if it is available.
+
+To highlight this, see the test case below:
+
+```csharp
+OpenXmlPackage package = /* Create a package */;
+
+var packageFeature = new PrivateFeature();
+package.Features.Set<PrivateFeature>(packageFeature);
+
+var part = package.GetPartById("existingPart");
+Assert.Same(part.Features.GetRequired<PrivateFeature>(), package.Features.GetRequired<PrivateFeature>());
+
+part.Features.Set<PrivateFeature>(new());
+Assert.NotSame(part.Features.GetRequired<PrivateFeature>(), package.Features.GetRequired<PrivateFeature>());
+
+
+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:
+
+![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
+
+This feature allows for registering actions that need to run when a package or a part is destroyed or disposed:
+
+```csharp
+OpenXmlPackage package = GetSomePackage();
+package.Features.Get<IDisposableFeature>().Register(() => /* Some action that is called when the package is disposed */);
+
+OpenXmlPart part = GetSomePart();
+part.Features.Get<IDisposableFeature>().Register(() => /* Some action that is called when the part is removed or closed */);
+```
+
+Packages and parts will have their own implementations of this feature. Elements will retrieve the feature for their containing part if available.
+
+### IPackageEventsFeature
+
+This feature allows getting event notifications of when a package is changed:
+
+```csharp
+OpenXmlPackage package = GetSomePackage();
+package.TryAddPackageEventsFeature();
+
+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
+
+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:
+
+```csharp
+OpenXmlPart part = GetSomePackage();
+package.AddPartEventsFeature();
+
+var feature = part.Features.GetRequired<IPartEventsFeature>();
+```
+
+Generally, assume that there may be a singleton implementation for the events and verify that the part is the correct part.
+
+> [!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
+
+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:
+
+```csharp
+OpenXmlPart part = GetSomePart();
+part.AddPartRootEventsFeature();
+
+var feature = part.Features.GetRequired<IPartRootEventsFeature>();
+```
+
+Generally, assume that there may be a singleton implementation for the events and verify that the part is the correct part.
+
+> [!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
+
+This feature allows for a shared service to generate random numbers and fill an array.
+
+### 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:
+
+```csharp
+WordprocessingDocument document = CreateWordDocument();
+document.TryAddParagraphIdFeature();
+
+var part = doc.AddMainDocumentPart();
+var body = new Body();
+part.Document = new Document(body);
+
+var p = new Paragraph();
+body.AddChild(p); // After adding p.ParagraphId will be set to a unique, valid value
+```
+
+This feature can also be used to ensure uniqueness among multiple documents with a slight change:
+
+```csharp
+using var doc1 = CreateDocument1();
+using var doc2 = CreateDocument2();
+
+var shared = doc1
+    .AddSharedParagraphIdFeature()
+    .Add(doc2);
+
+// Add item to doc1
+var part1 = doc1.AddMainDocumentPart();
+var body1 = new Body();
+var p1 = new Paragraph();
+part1.Document = new Document(body1);
+body1.AddChild(p1);
+
+// Add item with same ID to doc2
+var part2 = doc2.AddMainDocumentPart();
+var body2 = new Body();
+var p2 = new Paragraph { ParagraphId = p1.ParagraphId };
+part2.Document = new Document(body2);
+body2.AddChild(p2);
+
+// Assert
+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

@@ -0,0 +1,81 @@
+---
+
+api_name:
+- Microsoft.Office.DocumentFormat.OpenXML.Packaging
+api_type:
+- schema
+ms.assetid: c9b2ce55-548c-4443-8d2e-08fe1f06b7d7
+title: 'How to: Add a new document part that receives a relationship ID to a package'
+ms.suite: office
+
+ms.author: o365devx
+author: o365devx
+ms.topic: conceptual
+ms.date: 11/01/2017
+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
+processing document.
+
+
+
+-----------------------------------------------------------------------------
+## Packages and Document Parts 
+An Open XML document is stored as a package, whose format is defined by
+[ISO/IEC 29500-2](https://www.iso.org/standard/71691.html). The
+package can have multiple parts with relationships between them. The
+relationship between parts controls the category of the document. A
+document can be defined as a word-processing document if its
+package-relationship item contains a relationship to a main document
+part. If its package-relationship item contains a relationship to a
+presentation part it can be defined as a presentation document. If its
+package-relationship item contains a relationship to a workbook part, it
+is defined as a spreadsheet document. In this how-to topic, you will use
+a word-processing document package.
+
+
+-----------------------------------------------------------------------------
+
+[!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)
+```
+***
+
+
+The following 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)]
+
+### [Visual Basic](#tab/vb)
+[!code-vb[](../../samples/word/add_a_new_part_that_receives_a_relationship_id_to_a_package/vb/Program.vb)]
+
+-----------------------------------------------------------------------------
+## See also 
+
+
+- [Open XML SDK class library reference](/office/open-xml/open-xml-sdk)
+  
+
+