Open XML SDK by Microsoft
Clone or download
twsouthwick Simplify schema attributes and consolidate definitions (#496)
This creates a readonly struct that abstracts the attribute definitions
and management to help with readability and cleaner code.
Latest commit bd8cda8 Aug 20, 2018
Permalink
Failed to load latest commit information.
build Update SignClient (#508) Jun 8, 2018
src/DocumentFormat.OpenXml Simplify schema attributes and consolidate definitions (#496) Aug 20, 2018
test Simplify schema attributes and consolidate definitions (#496) Aug 20, 2018
.gitattributes Re-add Makefile-Linux-Mono so that it is in the object repo as text p… Jul 16, 2015
.gitignore Update SignClient (#508) Jun 8, 2018
CHANGELOG.md Updated the date for 2.9.0 Jun 8, 2018
Directory.Build.props Rename internal System.* interfaces to be in DocumentFormat.OpenXml (#… Mar 8, 2018
Directory.Build.targets Add names to DataMembers to simplify restriction serialization (#483) Apr 15, 2018
DocumentFormat.OpenXml.Package.props Updated the copyright per nuget package requirements Jun 15, 2018
DocumentFormat.OpenXml.snk Update projects to VS 2017 Mar 15, 2017
GitVersion.yml Bump version to 2.9.0 as there are some minor API changes since the l… Mar 6, 2018
ISSUE_TEMPLATE.md Update README with known issues and fixes for changelog (#296) Nov 18, 2017
LICENSE Convert project to MIT license (#333) Dec 19, 2017
Open-XML-SDK.sln Add initial benchmark class (#474) Apr 8, 2018
README.md Remove fixed known issue (#399) Feb 5, 2018
Tests.targets Add code coverage to test runs (#308) Dec 13, 2017
appveyor.yml Update SignClient (#508) Jun 8, 2018
compat.yml Add initial compat configuration (#376) Jan 18, 2018
icon.png adding new package icon (#377) Jan 6, 2018
icon.svg adding new package icon (#377) Jan 6, 2018
rules.ruleset Enable SA1136 enum on separate lines (#472) Apr 6, 2018
run_perf_benchmarks.ps1 Reorganize benchmarks and add script to run them (#495) May 7, 2018
stylecop.json Convert project to MIT license (#333) Dec 19, 2017

README.md

Open XML SDK

NuGet Downloads master MyGet

The Open XML SDK provides tools for working with Office Word, Excel, and PowerPoint documents. It supports scenarios such as:

  • High-performance generation of word-processing documents, spreadsheets, and presentations.
  • Populating content in Word files from an XML data source.
  • Splitting up (shredding) a Word or PowerPoint file into multiple files, and combining multiple Word/PowerPoint files into a single file.
  • Extraction of data from Excel documents.
  • Searching and replacing content in Word/PowerPoint using regular expressions.
  • Updating cached data and embedded spreadsheets for charts in Word/PowerPoint.
  • Document modification, such as adding, updating, and removing content and metadata.

Table of Contents

Releases

The official release NuGet packages for Open XML SDK are available on Nuget.org.

The NuGet package for the latest builds of the Open XML SDK is available as a custom feed on MyGet. You can trust this package source, since the custom feed is locked and only this project feeds into the source. Stable releases here will be mirrored onto NuGet and will be identical.

For latests changes, please see the changelog

Supported platforms

This library supports many platforms. There are builds for .NET 3.5, .NET 4.0, .NET 4.6, and .NET Standard 1.3. The following platforms are currently supported:

Platform Minimum Version
.NET Framework 3.5
.NET Core 1.0
UWP 10.0
Mono 3.5
Xamarin.iOS 10.0
Xamarin.Mac 3.0
Xamarin.Android 7.0

WindowsBase or System.IO.Packaging

There is a known issue in WindowsBase that causes crashes when handling large data sources. This is fixed in later versions of the library, based on the platform availability of the System.IO.Packaging package. When possible, we use this package instead of WindowsBase. This not only fixes the crash seen by some users, but is available cross platform. However, it is only available on .NET Standard 1.3+ and .NET Framework 4.6+. For this reason, the NuGet package has multiple targets to bring in, when possible. The targets are determined by NuGet at installation and build time and are listed in the table below.

Platform System.IO.Packing Source Tested by
.NET 3.5 WindowsBase N/A
.NET 4.0 WindowsBase .NET 4.5.2
.NET 4.6 NuGet .NET 4.6
.NET Standard NuGet .NET Core 1.0

Keep in mind, though, that the System.IO.Packaging on .NET 4.6+ is simply a facade over WindowsBase, and thus everything running on .NET 4.6 will use WindowsBase instead of the newer implementation.

How to install the NuGet package

The package you want to install is DocumentFormat.OpenXml.

NuGet packages are available for release builds or CI Builds and follow semantic versioning.

The package feed or the package source is specified by the feed URL. Depending on your version of Visual Studio, choose the appropriate feed URL from the table below.

Table 1: The latest builds are available via a MyGet feed.

Client Feed URL
NuGet V3 (Visual Studio 2015+) https://dotnet.myget.org/F/open-xml-sdk/api/v3/index.json
NuGet V2 (Visual Studio 2012+) https://dotnet.myget.org/F/open-xml-sdk/api/v2

The Install-Package command considers the package source either via configuration or argument. Also, the package version can vary. For the latest version info, see the feed for the DocumentFormat.OpenXml package.

  • To specify the package source via a configuration option, see Configuring NuGet behavior. Note that usually a NuGet.config file is placed in the directory and the configuration options are added there to ensure the sources are persisted in the version control.

    PM> Install-Package DocumentFormat.OpenXml -Version <version retrieved from the web>
  • To pass the feed URL as an argument, here is an example for Visual Studio 2015 and later.

    PM> Install-Package DocumentFormat.OpenXml -Version <version retrieved from the web> -Source https://dotnet.myget.org/F/open-xml-sdk/api/v3/index.json

Note: If you have trouble installing the package, try restarting Visual Studio. Package sources could be cached and changes you've made to any NuGet.config files may not be detected.

If You Have Problems

If you want to report a problem (bug, behavior, build, distribution, feature request, etc...) with the SDK built by this repository, please feel free to post a new issue and someone will try to help.

If you have "how-to" questions please post to one of the following resources:

Known Issues

  • On Mono platforms that use the System.IO.Package NuGet package (i.e. Xamarin), opening some documents will fail due to an issue in System.IO.Packaging. For now, you must manually set the environment variable as described in UriKind.RelativeOrAbsolute workaround.

  • On .NET Core, zip packages do not have a way to stream data. Thus, the working set can explode in certain situations. This is a known issue.

  • On .NET Framework, an IsolatedStorageException may be thrown under certain circumstances. This generally occurs when manipulating a large document in an environment with an AppDomain that does not have enough evidence.

    Note: Once System.IO.Packaging on .NET Core has feature parity with WindowsBase (i.e. streaming support), we can investigate using the new .NET Core on .NET Framework.

Documentation

The functionality of the specific classes in this version of the Open XML SDK is similar to version 2.5, therefore the Open XML SDK 2.5 for Office documentation available on MSDN is still accurate.

In addition to open sourcing of the SDK, Microsoft has opened up the conceptual documentation for public review / contributions. A copy of the documentation is available for you to edit and review in GitHub.

Build Instructions

This project uses the csproj format and the release versions of the tooling in Visual Studio 2017. For more information on how to use this project type to build your project, see the release notes for Visual Studio 2017. Other editors that support the latest .NET project files include Visual Studio Code, Visual Studio for Mac, or .NET CLI. See .NET Downloads for details.

The project often requires the latest release of the C# compiler as many new features come on-line that greatly aid in ease of development. As of now, the C# 7.2 compiler is required (which was released in December 2017) and comes standard in Visual Studio 2017 Update 5, with other IDEs providing updates to the compiler, as well.

To build the Open XML SDK

  1. Clone the Open-XML-SDK repository.
  2. Open the solution with an editor that supports the latest .NET project files.
  3. Build the solution (using either Debug or Release configuration).
  4. Run the Xunit tests to verify the installation.

If you want to use a command line approach:

  1. Go to the directory that contains the solution.
  2. Run dotnet restore in the directory.
  3. Run dotnet test DocumentFormat.OpenXml.Tests to run the tests.
  4. Run dotnet pack DocumentFormat.OpenXml to generate a nupkg.

Related tools

  • Open XML Powertools: This is available on in the Open-Xml-PowerTools repository on GitHub and provides example code and guidance for implementing a wide range of Open XML scenarios.

Code of Conduct

This project has adopted the Microsoft Open Source Code of Conduct. For more information, see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.