Open XML SDK

The Open XML SDK is a framework for working with Microsoft Office Word, Excel, and PowerPoint documents. It provides low-level APIs for OPC packages, Flat OPC files, and Open XML markup using both strongly-typed classes and LINQ to XML.

Common use cases include:

• High-performance generation of Word, Excel, and PowerPoint documents.
• Document modification (adding, updating, or removing content and metadata).
• Searching and replacing content using regular expressions.
• Shredding files into multiple parts or combining multiple files.
• Updating cached data and embedded spreadsheets for charts.

The data/ directory contains auto-generated files used by the Open XML SDK to manage namespaces, schemas, and strongly typed class generation. These files are produced by a back-end processor and should not be modified manually.

Key components include:

• namespaces.json: A mapping of known namespaces and their associated prefixes.
• schematrons.json: Contains Schematron constraint information used for validation.
• parts/: A directory containing metadata and information for each Open XML part.
• schemas/: A directory containing schema element information, organized by namespace.
• typed/: A directory containing information used to generate strongly typed classes, organized by namespace.

For detailed API references, guides, and practical examples, use the following resources:

• Official SDK documentation: https://learn.microsoft.com/en-us/office/open-xml/open-xml-sdk
• Code Samples: https://github.com/dotnet/Open-XML-SDK/tree/main/samples
• Source Code: https://github.com/dotnet/Open-XML-SDK
• Issue Reporting: https://github.com/dotnet/Open-XML-SDK/issues

Particle compilation is a mechanism used by the Open XML SDK to determine the effective position where a new element should be inserted within a sequence of existing elements. Because OpenXML elements follow complex XSD (XML Schema Definition) patterns, the SDK maps child element relationships into ParticlePath collections.

These paths allow the SDK to compare different element types to decide if a new element should be inserted before or after existing ones. The logic is encapsulated in CompiledParticle and is exposed via the IComparer<OpenXmlElement> interface.

For most development tasks, you should use the DocumentFormat.OpenXml package (and optionally DocumentFormat.OpenXml.Linq) rather than the DocumentFormat.OpenXml.Framework package.

DocumentFormat.OpenXml.Framework provides low-level infrastructure and shared primitives. It is intended primarily for advanced scenarios and library authors who are extending the SDK. Typical usage of the framework is indirect, through types like OpenXmlElement and OpenXmlPart provided by the main SDK.

You can create a basic Word document by using the WordprocessingDocument.Create method. This involves creating a document part, adding a main document part, and then constructing the document hierarchy (Document -> Body -> Paragraph -> Run -> Text) using strongly-typed APIs.

using (var doc = WordprocessingDocument.Create("example.docx", WordprocessingDocumentType.Document))
{
    var mainPart = doc.AddMainDocumentPart();
    mainPart.Document = new Document(new Body(new Paragraph(new Run(new Text("Hello, Open XML!")))));
}

The Open XML SDK is available as several NuGet packages on NuGet.org. Depending on your needs, you can install the core library, the LINQ to XML extensions, or the framework package.

Official stable packages:

• DocumentFormat.OpenXml (Core library)
• DocumentFormat.OpenXml.Linq (LINQ to XML support)
• DocumentFormat.OpenXml.Framework (Framework package)
• DocumentFormat.OpenXml.Features (Feature support)

To use the latest daily builds of the Open XML SDK, you must configure a custom NuGet feed in your NuGet.config file pointing to the Azure blob storage feed.

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="OpenXmlCI" value="https://ooxml.blob.core.windows.net/feed/index.json" />
  </packageSources>
</configuration>

If you have questions or need assistance using the Open XML SDK, use the following community resources:

• Microsoft Q&A Forums: Post your questions and use the tag office-addins-dev.
• Stack Overflow: Post your questions using the tags openxml or openxml-sdk.

To add Rich Data (such as geographic data) to an Excel document using the Open XML SDK, you must include several specific parts and elements within the document structure. This sample demonstrates adding geographic Rich Data for 'Seattle' to cell A1 of a target spreadsheet.

Required Parts

Implementing Rich Data requires the following parts to be added to the document:

• RdRichValueWebImagePart
• RdRichValuePart
• RdRichValueStructurePart
• RdArrayPart
• RichStylesPart
• RdSupportingPropertyBagStructurePart
• RdSupportingPropertyBagPart
• RdRichValueTypesPart
• CellMetadataPart

To add an SVG to a document using the Open XML SDK, you must also include a .png copy of the SVG file, as Office requires the image format for display.

This sample demonstrates how to use the AddSvg method to perform this task. The sample implementation utilizes the Aspose.Svg NuGet package to convert the .svg file into a .png copy before adding it to the document.