Upgrading DocumentFormat.OpenXml 2 to 3
Breaking2.20.0 → 3.5.1Breaking25New22Changed7Fixed18Other4
BreakingUpgrade verdict
25 breaking changes.
In plain terms
- Removes `OpenXmlSettings.RelationshipErrorHandlerFactory` and associated types, replaced with a built-in mechanism.
- Renames `PartExtensionProvider` to `IPartExtensionFeature` with two methods; access it via `Features.Get<IPartExtensionFeature>()`.
- Each document type now has its own part reader, and the old shared typed reader is gone.
- This class is no longer available, so code referencing it will not compile.
Must act Top 3 of 25 that need code or config changes
Target frameworks requirement changed in 3.4.1: .NETFramework3.5, .NETFramework4.0, .NETFramework4.6, .NETStandard1.3, .NETStandard2.0, net6.0 → .NETFramework3.5, .NETFramework4.0, .NETFramework4.6, .NETStandard2.0, net10.0, net8.0.
What you must change
Breaking25
Removes
OpenXmlSettings.RelationshipErrorHandlerFactory and associated types, replaced with a built-in mechanism.OpenXmlSettings.RelationshipErrorHandlerFactoryRenames
PartExtensionProvider to IPartExtensionFeature with two methods; access it via Features.Get<IPartExtensionFeature>().PartExtensionProviderIPartExtensionFeatureOpenXmlPackageFeatures.Get<IPartExtensionFeature>()Adds per-package OpenXmlPartReader implementations and removes TypedOpenXmlPartReader.
OpenXmlPartReaderWordprocessingDocumentPartReaderSpreadsheetDocumentPartReaderPresentationDocumentPartReaderTypedOpenXmlPartReaderRemoves PivotCacheHasRichValuePivotCacheRichInfo from the SpreadSheetML Y2022 PivotRichData namespace.
DocumentFormat.OpenXml.Office.SpreadSheetML.Y2022.PivotRichData.PivotCacheHasRichValuePivotCacheRichInfoRemoves RichDataPivotCacheGuid from the SpreadSheetML Y2022 PivotRichData namespace.
DocumentFormat.OpenXml.Office.SpreadSheetML.Y2022.PivotRichData.RichDataPivotCacheGuidRemoves the unused SchemaAttrAttribute.
SchemaAttrAttributeRemoves the unused ChildElementInfoAttribute.
ChildElementInfoAttributeRemoves OpenXmlSimpleType.TextValue, which was never meant for external use.
OpenXmlSimpleType.TextValueRemoves obsolete validation logic from v1 of the SDK.
Removes methods obsoleted in 2.x.
Removes mutable properties on OpenXmlAttribute and marks it readonly.
OpenXmlAttributeRemoves OpenXmlPackage.Close in favor of Dispose.
OpenXmlPackage.CloseOpenXmlPackage.DisposeRemoves OpenXmlPackage.SaveAs in favor of Clone.
OpenXmlPackage.SaveAsOpenXmlPackage.CloneCore infrastructure moves to the new DocumentFormat.OpenXml.Framework package; typed classes remain in DocumentFormat.OpenXml.
DocumentFormat.OpenXml.FrameworkDocumentFormat.OpenXmlChanges
OpenXmlPackage.Package type to DocumentFormat.OpenXml.Packaging.IPackage instead of System.IO.Packaging.Package.OpenXmlPackage.PackageDocumentFormat.OpenXml.Packaging.IPackageSystem.IO.Packaging.PackageEnumValue<T> now boxes a struct rather than a System.Enum, enabling behavior without reflection.EnumValue<T>System.EnumPart methods to add child parts (such as
AddImagePart) are now extension methods off the new ISupportedRelationship<T> marker interface.AddImagePartISupportedRelationship<T>Part type info enums such as
ImagePartType become static classes exposing well-known part types as structs using the new PartTypeInfo struct.ImagePartTypePartTypeInfoOpenXmlPackage.CanSave is now an instance property.OpenXmlPackage.CanSaveIdPartPair is now a readonly struct rather than a class.IdPartPairChanges OpenXmlElementList from a class to a struct implementing IEnumerable<OpenXmlElement> and IReadOnlyList<OpenXmlElement>.
OpenXmlElementListIEnumerable<OpenXmlElement>IReadOnlyList<OpenXmlElement>Reduces unnecessary target frameworks for packages other than DocumentFormat.OpenXml.Framework.
DocumentFormat.OpenXml.FrameworkFixes spelling issues in some property names.
Changes Model3D to represent the XML element tag name am3d.model3d instead of am3d.model3D.
Model3Dam3d.model3dMakes constructors of OpenXmlPart, OpenXmlContainer, OpenXmlPackage and derived types internal.
OpenXmlPartOpenXmlContainerOpenXmlPackage