You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
## Where to get the NuGet packages of the latest builds?
26
47
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.
27
48
28
-
## Support platforms
49
+
Support platforms
50
+
-----------------
51
+
29
52
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:
30
53
31
54
| Platform | Minimum Version |
@@ -38,8 +61,10 @@ This library supports many platforms. There are builds for .NET 3.5, .NET 4.0, .
38
61
| Xamarin.Mac | 3.0 |
39
62
| Xamarin.Android | 7.0 |
40
63
41
-
## WindowsBase or System.IO.Packaging
42
-
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 this when possible. The targets (which are determined by NuGet at installation and build time) are:
64
+
WindowsBase or System.IO.Packaging
65
+
----------------------------------
66
+
67
+
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.
43
68
44
69
| Platform | System.IO.Packing Source | Tested by |
@@ -48,119 +73,129 @@ There is a known issue in WindowsBase that causes crashes when handling large da
48
73
| .NET 4.6 | NuGet | .NET 4.6 |
49
74
| .NET Standard | NuGet | .NET Core 1.0 |
50
75
51
-
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.
76
+
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.
52
77
53
-
## How to install the NuGet package?
54
-
The package you want to install is DocumentFormat.OpenXml.
78
+
How to install the NuGet package
79
+
---------------------------------
80
+
81
+
The package you want to install is DocumentFormat.OpenXml.
55
82
56
83
NuGet packages are available for [release builds](https://www.nuget.org/packages/DocumentFormat.OpenXml) or [CI Builds](https://dotnet.myget.org/gallery/open-xml-sdk) and follow [semantic versioning](http://www.semver.org/).
57
84
58
-
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.
85
+
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.
59
86
60
-
Table 1: The latest builds are available via a MyGet feed
87
+
**Table 1:** The latest builds are available via a MyGet feed.
61
88
62
89
| Client | Feed URL |
63
90
| ------ | -------- |
64
-
| NuGet V3 (Visual Studio 2015+) |https://dotnet.myget.org/F/open-xml-sdk/api/v3/index.json|
65
-
| NuGet V2 (Visual Studio 2012+) |https://dotnet.myget.org/F/open-xml-sdk/api/v2|
91
+
| NuGet V3 (Visual Studio 2015+) |[https://dotnet.myget.org/F/open-xml-sdk/api/v3/index.json](https://dotnet.myget.org/F/open-xml-sdk/api/v3/index.json)|
92
+
| NuGet V2 (Visual Studio 2012+) |[https://dotnet.myget.org/F/open-xml-sdk/api/v2](https://dotnet.myget.org/F/open-xml-sdk/api/v2)|
66
93
67
-
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 https://dotnet.myget.org/feed/open-xml-sdk/package/nuget/DocumentFormat.OpenXml
94
+
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](https://dotnet.myget.org/feed/open-xml-sdk/package/nuget/DocumentFormat.OpenXml).
68
95
69
-
- To specify the package source via a configuration option, see https://docs.microsoft.com/en-us/nuget/consume-packages/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.
96
+
- To specify the package source via a configuration option, see [Configuring NuGet behavior](https://docs.microsoft.com/en-us/nuget/consume-packages/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.
70
97
71
-
```
72
-
PM> Install-Package DocumentFormat.OpenXml -Version <version retrieved from the web>
73
-
```
98
+
```shell
99
+
PM> Install-Package DocumentFormat.OpenXml -Version <version retrieved from the web>
100
+
```
74
101
75
-
- To pass the feed URL as an argument, here is an example for Visual Studio 2015 and later.
102
+
- To pass the feed URL as an argument, here is an example for Visual Studio 2015 and later.
76
103
77
-
```
78
-
PM> Install-Package DocumentFormat.OpenXml -Version <version retrieved from the web> -Source https://dotnet.myget.org/F/open-xml-sdk/api/v3/index.json
79
-
```
104
+
```shell
105
+
PM> Install-Package DocumentFormat.OpenXml -Version <version retrieved from the web> -Source https://dotnet.myget.org/F/open-xml-sdk/api/v3/index.json
106
+
```
80
107
81
-
**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.
108
+
**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.
82
109
83
-
Having Problems?
84
-
================
110
+
If You Have Problems
111
+
--------------------
85
112
86
-
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 the someone will try to help out.
113
+
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.
87
114
88
-
If you have "how-to" questions please post to one of the following resources:
115
+
If you have "how-to" questions please post to one of the following resources:
-http://stackoverflow.com (tags: "openxml" or "openxml-sdk")
117
+
-[Open XML SDK forum](https://social.msdn.microsoft.com/Forums/office/en-US/home?forum=oxmlsdk)
118
+
-[Stack Overflow](http://stackoverflow.com) (tags: **openxml** or **openxml-sdk**)
92
119
93
120
Known Issues
94
-
==========
95
-
- On Mono platforms that use the System.IO.Package NuGet package (ie Xamarin), opening some documents will fail due to an [issue](https://github.com/dotnet/corefx/issues/24822) in System.IO.Packaging. For now, you must manually set the environment variable as described at the [Mono description](http://www.mono-project.com/docs/faq/known-issues/urikind-relativeorabsolute/)
96
-
- 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](https://github.com/dotnet/corefx/issues/24457)
97
-
- On .NET Framework, an IsolatedStorageException may be thrown under certain circumstances, generally when manipulating a large document in an environment with an AppDomain that does not have enough evidence.
98
-
- Out of the box, the library will not compile on .NET Native. This [issue](https://github.com/OfficeDev/Open-XML-SDK/issues/181) is tracking this
121
+
------------
122
+
123
+
- On Mono platforms that use the `System.IO.Package` NuGet package (i.e. Xamarin), opening some documents will fail due to an [issue](https://github.com/dotnet/corefx/issues/24822) in `System.IO.Packaging`. For now, you must manually set the environment variable as described in [UriKind.RelativeOrAbsolute workaround](http://www.mono-project.com/docs/faq/known-issues/urikind-relativeorabsolute/).
124
+
- 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](https://github.com/dotnet/corefx/issues/24457).
125
+
- 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.
126
+
- Out of the box, the library will not compile on .NET Native. [Issue 181](https://github.com/OfficeDev/Open-XML-SDK/issues/181) is open to track this.
99
127
100
-
Once System.IO.Packaging on .NET Core has feature parity with WindowsBase (ie streaming support), we can investigate using the new .NET Core on .NET Framework
128
+
**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.
101
129
102
130
Change Log
103
-
==========
131
+
-----------
132
+
133
+
**Version 2.8.0**: December 28, 2017
104
134
105
-
Version 2.8.0 : December 28, 2017
106
135
- Added default runtime directive for better .NET Native support
107
136
- Fixed exceptions thrown when errors are encountered while opening packages to be consistent across platforms
108
137
- Fixed issue on Mono platforms using System.IO.Packaging NuGet package (Xamarin, etc) when creating a document
109
138
- Fixed manual saving of a package when autosave is false
110
139
- Fixed schema constraint data and standardized serialization across platforms
111
140
- Upgraded to System.IO.Packaging 4.4.0 which fixes some consistency with .NET Framework in opening packages
112
-
113
-
Version 2.7.2 : June 6, 2017
114
-
- Fixed issue where assembly version wasn't set in assembly
115
-
- Added support for .NET 3.5 and .NET 4.0
116
141
117
-
Version 2.7.1 : January 31, 2017
118
-
- Fixed crash when validation is invoked on .NET Framework with strong-naming enforced
142
+
**Version 2.7.2**: June 6, 2017
119
143
120
-
Version 2.7.0 : January 24, 2017
121
-
- Added support for .NET Standard 1.3
122
-
- Moved to using System.IO.Packaging from dotnet/corefx for .NET Standard 1.3 and WindowsBase for .NET 4.5
123
-
- Cleaned up project build system to use .NET CLI
144
+
- Fixed issue where assembly version wasn't set in assembly.
145
+
- Added support for .NET 3.5 and .NET 4.0.
124
146
125
-
Version 2.6.1 : January 15, 2016
147
+
**Version 2.7.1**: January 31, 2017
148
+
149
+
- Fixed crash when validation is invoked on .NET Framework with strong-naming enforced.
150
+
151
+
**Version 2.7.0**: January 24, 2017
152
+
153
+
- Added support for .NET Standard 1.3.
154
+
- Moved to using System.IO.Packaging from dotnet/corefx for .NET Standard 1.3 and WindowsBase for .NET 4.5.
155
+
- Cleaned up project build system to use .NET CLI.
156
+
157
+
**Version 2.6.1**: January 15, 2016
126
158
- Added hundreds of XUnit tests. There are now a total of 1333 tests. They take about 20 minutes to run, so be patient.
127
159
128
-
Version 2.6.0 : June 29, 2015
129
-
- The big feature in 2.6 is the inclusion of a replacement for System.IO.Packaging, which has a serious bug that causes it (albeit rarely and in specific circumstances) to throw exceptions (ObjectDisposedException and NullReferenceException). You can find out more about this bug and whether it affects you in [the blog post that announces the release of the new System.IO.Packaging] (http://openxmldeveloper.org/blog/b/openxmldeveloper/archive/2015/06/29/announcing-the-release-of-a-new-system-io-packaging-implementation.aspx).
160
+
**Version 2.6.0**: June 29, 2015
130
161
162
+
- The big feature in 2.6 is the inclusion of a replacement for `System.IO.Packaging`, which has a serious bug that causes it (albeit rarely and in specific circumstances) to throw exceptions (`ObjectDisposedException` and `NullReferenceException`). You can find out more about this bug and whether it affects you in [the blog post that announces the release of the new `System.IO.Packaging`](http://openxmldeveloper.org/blog/b/openxmldeveloper/archive/2015/06/29/announcing-the-release-of-a-new-system-io-packaging-implementation.aspx).
131
163
132
164
Documentation
133
-
=============
165
+
-------------
134
166
135
-
The functionality of the specific classes in Open XML SDK Version 2.7.0 is similar to version 2.5, therefore the documentation available on MSDN is still accurate.
167
+
The functionality of the specific classes in Open XML SDK Version 2.8.0 is similar to version 2.5, therefore the[Open XML SDK 2.5 for Office](http://msdn.microsoft.com/en-us/library/office/bb448854.aspx) documentation available on MSDN is still accurate.
136
168
137
-
[Open XML SDK 2.5 for Office](http://msdn.microsoft.com/en-us/library/office/bb448854.aspx)
138
-
139
-
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 [now in GitHub](https://github.com/OfficeDev/office-content) for you to edit and review.
169
+
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](https://github.com/OfficeDev/office-content).
140
170
141
171
Build Instructions
142
-
==================
172
+
------------------
173
+
174
+
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](https://www.visualstudio.com/en-us/news/releasenotes/vs2017-relnotes#dotnetcore). Other editors that support the latest .NET project files include Visual Studio Code, Visual Studio for Mac, or .NET CLI. See [.NET Downloads](https://www.microsoft.com/net/download/core) for details.
143
175
144
-
This project uses the new 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: https://www.visualstudio.com/en-us/news/releasenotes/vs2017-relnotes#dotnetcore. Other editors that support the latest .NET project files include VS Code, VS for Mac, or .NET CLI. See https://www.microsoft.com/net/download/core for details.
176
+
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.
145
177
146
-
The project will often require 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.
178
+
To build the Open XML SDK
179
+
-------------------------
147
180
148
-
To build the Open XML SDK:
149
-
- Clone the repo at https://github.com/OfficeDev/Open-XML-SDK
150
-
- Open the solution with an editor that supports the latest .NET project files
151
-
- Build the solution (using either Debug or Release configuration)
152
-
- Run the Xunit tests to verify the installation
181
+
1. Clone the [Open-XML-SDK](https://github.com/OfficeDev/Open-XML-SDK) repository.
182
+
1. Open the solution with an editor that supports the latest .NET project files.
183
+
1. Build the solution (using either Debug or Release configuration).
184
+
1. Run the Xunit tests to verify the installation.
153
185
154
186
If you want to use a command line approach:
155
-
- Go to the directory the solution is in
156
-
- Run `dotnet restore` in the directory
157
-
- Run `dotnet test DocumentFormat.OpenXml.Tests` to run the tests
158
-
- Run `dotnet pack DocumentFormat.OpenXml` to generate a nupkg
187
+
188
+
1. Go to the directory that contains the solution.
189
+
1. Run `dotnet restore` in the directory.
190
+
1. Run `dotnet test DocumentFormat.OpenXml.Tests` to run the tests.
191
+
1. Run `dotnet pack DocumentFormat.OpenXml` to generate a nupkg.
159
192
160
193
Related tools
161
-
====
194
+
-------------
162
195
163
-
-**Open XML Powertools**: This is available on [Github](https://github.com/OfficeDev/Open-Xml-PowerTools) and provides example code and guidance for implementing a wide range of Open XML scenarios.
196
+
-**Open XML Powertools**: This is available on in the [Open-Xml-PowerTools](https://github.com/OfficeDev/Open-Xml-PowerTools) repository on GitHub and provides example code and guidance for implementing a wide range of Open XML scenarios.
164
197
198
+
Code of Conduct
199
+
---------------
165
200
166
201
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information, see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
0 commit comments