|
| 1 | +--- |
| 2 | +title: 'Migrate from v2.x to v3.0' |
| 3 | +ms.suite: office |
| 4 | + |
| 5 | +ms.author: o365devx |
| 6 | +author: o365devx |
| 7 | +ms.topic: conceptual |
| 8 | +ms.date: 11/01/2017 |
| 9 | +ms.localizationpriority: medium |
| 10 | +--- |
| 11 | + |
| 12 | +# Migration to v3.0.0 |
| 13 | + |
| 14 | +There are a number of breaking changes between v2.20.0 and v3.0.0 that may require source level changes. As a reminder, there are two kinds of breaking changes: |
| 15 | + |
| 16 | +1. **Binary**: When a binary can no longer be used as drop in replacement |
| 17 | +2. **Source**: When the source no longer compiles |
| 18 | + |
| 19 | +The changes made in v3.0.0 were either a removal of obsoletions present in the SDK for a while or changes required for architectural reasons (most notably for better AOT support and trimming). Majority of these changes should be on the *binary* breaking change side, while still supporting compilation and expected behavior with your previous code. However, there are a few source breaking chnages to be made aware of. |
| 20 | + |
| 21 | +## Breaking Changes |
| 22 | + |
| 23 | +### .NET Standard 1.3 support has been dropped |
| 24 | + |
| 25 | +No targets still in support require .NET Standard 1.3 and can use .NET Standard 2.0 instead. The project still supports .NET Framework 3.5+ and any [.NET Standard 2.0 supported platform](/dotnet/standard/net-standard?tabs=net-standard-2-0). |
| 26 | + |
| 27 | +**Action needed**: If using .NET Standard 1.3, please upgrade to a supported version of .NET |
| 28 | + |
| 29 | +### Target frameworks have changed |
| 30 | + |
| 31 | +In order to simplify package creation, the TFMs built have been changed for some of the packages. However, there should be no apparent change to users as the overall supported platforms (besides .NET Standard 1.3 stated above) remains the same. |
| 32 | + |
| 33 | +**Action needed**: None |
| 34 | + |
| 35 | +### OpenXmlPart/OpenXmlContainer/OpenXmlPackage no longer have public constructors |
| 36 | + |
| 37 | +These never initialized correct behavior and should never have been exposed. |
| 38 | + |
| 39 | +**Action needed**: Use `.Create(...)` methods rather than constructor. |
| 40 | + |
| 41 | +### Supporting framework for OpenXML types is now in the DocumentFormat.OpenXml.Framework package |
| 42 | + |
| 43 | +Starting with v3.0.0, the supporting framework for the Open XML SDK is now within a standalone package, [DocumentFormat.OpenXml.Framework](https://www.nuget.org/packages/DocumentFormat.OpenXml.Framework). |
| 44 | + |
| 45 | +**Action needed**: If you would like to operate on just `OpenXmlPackage` types, you no longer need to bring in all the static classes and can just reference the framework library. |
| 46 | + |
| 47 | +### System.IO.Packaging is not directly used anymore |
| 48 | + |
| 49 | +There have been issues with getting behavior we need from the System.IO.Packaging namespace. Starting with v3.0, a new set of interfaces in the `DocumentFormat.OpenXml.Packaging` namespace will be used to access package properties. |
| 50 | + |
| 51 | +> [!NOTE] |
| 52 | +> These types are currently marked as obsolete, but only in the sense that we reserve the right to change their shape per feedback. Please be careful using these types as they may change in the future. At some point, we will remove the obsoletions and they will be considered stable APIs. See [here](../general/diagnosticids.md) for details. |
| 53 | +
|
| 54 | +**Action needed**: If using `OpenXmlPackage.Package`, the package returned is no longer of type `System.IO.Packaging.Package`, but of `DocumentFormat.OpenXml.Packaging.IPackage`. |
| 55 | + |
| 56 | +### Methods on parts to add child parts are now extension methods |
| 57 | + |
| 58 | +There was a number of duplicated methods that would add parts in well defined ways. In order to consolidate this, if a part supports `ISupportedRelationship<T>`, extension methods can be written to support specific behavior that part can provide. Existing methods for this should transparently be retargeted to the new extension methods upon compilation. |
| 59 | + |
| 60 | +**Action needed**: None |
| 61 | + |
| 62 | +### OpenXmlAttribute is now a readonly struct |
| 63 | + |
| 64 | +This type used to have mutable getters and setters. As a struct, this was easy to misuse, and should have been made readonly from the start. |
| 65 | + |
| 66 | +**Action needed**: If expecting to mutate an OpenXmlAttribute in place, please create a new one instead. |
| 67 | + |
| 68 | +### EnumValue<TEnum> now contains structs |
| 69 | + |
| 70 | +Starting with v3.0.0, `EnumValue<T>` wraps a custom type that contains the information about the enum value. Previously, these types were stored in enum values in the C# type system, but required reflection to access, causing very large AOT compiled applications. |
| 71 | + |
| 72 | +**Action needed**: Similar API surface is available, however the exposed enum values for this are no longer constants and will not be available in a few scenarios they had been (i.e. attribute values). |
| 73 | + |
| 74 | +A common change that is required is switch statements no longer work: |
| 75 | + |
| 76 | +```csharp |
| 77 | +switch (theCell.DataType.Value) |
| 78 | +{ |
| 79 | + case CellValues.SharedString: |
| 80 | + // Handle the case |
| 81 | + break; |
| 82 | +} |
| 83 | +``` |
| 84 | + |
| 85 | +becomes: |
| 86 | + |
| 87 | +```csharp |
| 88 | +if (theCell.DataType.Value == CellValues.SharedString) |
| 89 | +{ |
| 90 | + // Handle the case |
| 91 | +} |
| 92 | +``` |
| 93 | + |
| 94 | +### OpenXmlElementList is now a struct |
| 95 | + |
| 96 | +[OpenXmlElementList](/dotnet/api/documentformat.openxml.openxmlelementlist) is now a struct. It still implements `IEnumerable<OpenXmlElement>` in addition to `IReadOnlyList<OpenXmlElement>` where available. |
| 97 | + |
| 98 | +**Action needed**: Because this is a struct, code patterns that may have a `null` result will now be a `OpenXmlElementList?` instead. Null checks will be flagged by the compiler and the value itself will need to be unwrapped, such as: |
| 99 | + |
| 100 | +```diff |
| 101 | +- OpenXmlElementList? slideIds = part?.Presentation?.SlideIdList?.ChildElements; |
| 102 | ++ OpenXmlElementList slideIds = part?.Presentation?.SlideIdList?.ChildElements ?? default; |
| 103 | +``` |
| 104 | + |
| 105 | +or |
| 106 | + |
| 107 | +```diff |
| 108 | +- OpenXmlElementList? slideIds = part?.Presentation?.SlideIdList?.ChildElements; |
| 109 | ++ OpenXmlElementList slideIds = (part?.Presentation?.SlideIdList?.ChildElements).GetValueOrDefault(); |
| 110 | +``` |
| 111 | + |
| 112 | +### IdPartPair is now a readonly struct |
| 113 | + |
| 114 | +This type is used to enumerate pairs within a part and caused many unnecessary allocations. This change should be transparent upon recompilation. |
| 115 | + |
| 116 | +**Action needed**: Because this is now a struct, null handling code will need to be updated. |
| 117 | + |
| 118 | +### OpenXmlPartReader no longer knows about all parts |
| 119 | + |
| 120 | +In previous versions, [OpenXmlPartReader](/dotnet/api/documentformat.openxml.openxmlpartreader) knew about about all strongly typed part. In order to reduce coupling required for better AOT scenarios, we now have typed readers for known packages: `WordprocessingDocumentPartReader`, `SpreadsheetDocumentPartReader`, and `PresentationDocumentPartReader`. |
| 121 | + |
| 122 | +**Action needed**: Replace usage of `OpenXmlPartReader` with document specific readers if needed. If creating a part reader from a known package, please use the constructors that take an existing `OpenXmlPart` which will then create the expected strongly typed parts. |
| 123 | + |
| 124 | +### Attributes for schema information have been removed |
| 125 | + |
| 126 | +`SchemaAttrAttribute` and `ChildElementInfoAttribute` have been removed from types and the types themselves are no longer present. |
| 127 | + |
| 128 | +**Action needed**: If these types were required, please engage us on [GitHub](https://github.com/dotnet/open-xml-sdk) to identify the best way forward for you. |
| 129 | + |
| 130 | +### OpenXmlPackage.Close has been removed |
| 131 | + |
| 132 | +This did nothing useful besides call `.Dispose()`, but caused confusion about which should be called. This is now removed with the expectation of calling `.Dispose()`, preferably with the [using pattern](/dotnet/api/system.idisposable#using-an-object-that-implements-idisposable). |
| 133 | + |
| 134 | +**Action needed**: Remove call and ensure package is disposed properly |
| 135 | + |
| 136 | +### OpenXmlPackage.CanSave is now an instance property |
| 137 | + |
| 138 | +This property used to be a static property that was dependent on the framework. Now, it may change per-package instance depending on settings and backing store. |
| 139 | + |
| 140 | +**Action needed**: Replace usage of static property with instance. |
| 141 | + |
| 142 | +### OpenXmlPackage.PartExtensionProvider has been changed |
| 143 | + |
| 144 | +This property provided a dictionary that allowed access to change the extensions used. This is now backed by the `IPartExtensionFeature`. |
| 145 | + |
| 146 | +**Action needed**: Replace usage with `OpenXmlPackage.Features.GetRequired<IPartExtensionFeature>()`. |
| 147 | + |
| 148 | +### Packages with MarkupCompatibilityProcessMode.ProcessAllParts now actually process all parts |
| 149 | + |
| 150 | +Previously, there was a heuristic to potentially minimize processing if no parts had been loaded. However, this caused scenarios such as ones where someone manually edited the XML to not actually process upon saving. v3.0.0 fixes this behavior and processes all part if this has been opted in. |
| 151 | + |
| 152 | +**Action needed**: If you only want loaded parts to be processed, change to `MarkupCompatibilityProcessMode.ProcessLoadedPartsOnly` |
0 commit comments