Migration zu v3.0.0

Es gibt eine Reihe von Breaking Changes zwischen v2.20.0 und v3.0.0, die möglicherweise Änderungen auf Quellebene erfordern. Zur Erinnerung: Es gibt zwei Arten von Breaking Changes:

1. Binärdatei: Wenn eine Binärdatei nicht mehr als Ersatz verwendet werden kann
2. Quelle: Wenn die Quelle nicht mehr kompiliert wird

Die in v3.0.0 vorgenommenen Änderungen waren entweder eine Entfernung von Veraltetkeiten, die im SDK für eine Weile vorhanden waren, oder Änderungen, die aus Architektonischen Gründen erforderlich waren (vor allem für eine bessere AOT-Unterstützung und -Kürzung). Die meisten dieser Änderungen sollten auf der Seite des binären Breaking Changes erfolgen, während die Kompilierung und das erwartete Verhalten mit Ihrem vorherigen Code weiterhin unterstützt werden. Es gibt jedoch einige quellenbrecherische Punkte, auf die sie aufmerksam gemacht werden müssen.

Breaking Changes

.NET Standard 1.3-Unterstützung wurde eingestellt

Keine Ziele, die noch unterstützt werden, erfordern .NET Standard 1.3 und können stattdessen .NET Standard 2.0 verwenden. Das Projekt unterstützt weiterhin .NET Framework Version 3.5 und höher und jede von .NET Standard 2.0 unterstützte Plattform.

Aktion erforderlich: Wenn Sie .NET Standard 1.3 verwenden, führen Sie ein Upgrade auf eine unterstützte Version von .NET durch.

Zielframeworks haben sich geändert

Um die Paketerstellung zu vereinfachen, wurden die erstellten TFMs für einige der Pakete geändert. Es sollte jedoch keine offensichtliche Änderung für Benutzer geben, da die insgesamt unterstützten Plattformen (abgesehen von .NET Standard 1.3 oben) unverändert bleiben.

Aktion erforderlich: Keine

OpenXmlPart/OpenXmlContainer/OpenXmlPackage verfügen nicht mehr über öffentliche Konstruktoren

Diese haben nie das richtige Verhalten initialisiert und sollten nie verfügbar gemacht werden.

Aktion erforderlich: Verwenden Sie .Create(...) Methoden anstelle des Konstruktors.

Das unterstützende Framework für OpenXML-Typen befindet sich jetzt im DocumentFormat.OpenXml.Framework-Paket.

Ab v3.0.0 befindet sich das unterstützende Framework für das Open XML SDK jetzt in einem eigenständigen Paket , DocumentFormat.OpenXml.Framework.

Aktion erforderlich: Wenn Sie nur OpenXmlPackage mit Typen arbeiten möchten, müssen Sie nicht mehr alle statischen Klassen einbinden und können einfach auf die Frameworkbibliothek verweisen.

System.IO.Packaging wird nicht mehr direkt verwendet

Es gab Probleme beim Abrufen von Verhalten, das wir aus dem System.IO.Packaging-Namespace benötigen. Ab Version 3.0 wird ein neuer Satz von Schnittstellen im -Namespace für den DocumentFormat.OpenXml.Packaging Zugriff auf Paketeigenschaften verwendet.

Aktion erforderlich: Bei Verwendung von OpenXmlPackage.Packageist das zurückgegebene Paket nicht mehr vom Typ System.IO.Packaging.Package, sondern von DocumentFormat.OpenXml.Packaging.IPackage.

Methoden für Teile zum Hinzufügen untergeordneter Teile sind jetzt Erweiterungsmethoden

Es gab eine Reihe doppelter Methoden, mit denen Teile auf klar definierte Weise hinzugefügt wurden. Um dies zu konsolidieren, können Erweiterungsmethoden geschrieben werden, wenn ein Teil unterstützt ISupportedRelationship<T>, um ein bestimmtes Verhalten zu unterstützen, das von einem Teil bereitgestellt werden kann. Vorhandene Methoden hierfür sollten bei der Kompilierung transparent auf die neuen Erweiterungsmethoden umgeleitet werden.

Aktion erforderlich: Keine

OpenXmlAttribute ist jetzt eine schreibgeschützte Struktur.

Dieser Typ verfügte früher über änderbare Getter und Setter. Als Struktur war dies leicht zu missbrauchen und hätte von Anfang an schreibgeschützt gemacht werden müssen.

Aktion erforderlich: Wenn Sie erwarten, dass ein OpenXmlAttribute an Ort und Stelle mutiert wird, erstellen Sie stattdessen ein neues.

EnumValue<TEnum> enthält jetzt Strukturen

Ab v3.0.0 umschließt einen benutzerdefinierten Typ, EnumValue<T> der die Informationen zum Enumerationswert enthält. Bisher wurden diese Typen in Enumerationswerten im C#-Typsystem gespeichert, erforderten jedoch Reflektion für den Zugriff, was zu sehr großen AOT-kompilierten Anwendungen führte.

Aktion erforderlich: Eine ähnliche API-Oberfläche ist verfügbar, aber die verfügbar gemachten Enumerationswerte dafür sind keine Konstanten mehr und sind in einigen Szenarien nicht verfügbar (d. h. Attributwerte).

Eine häufige Änderung, die erforderlich ist, ist, dass switch-Anweisungen nicht mehr funktionieren:

switch (theCell.DataType.Value)
{
  case CellValues.SharedString:
    // Handle the case
    break;
}

Wird:

if (theCell.DataType.Value == CellValues.SharedString)
{
  // Handle the case
}

OpenXmlElementList ist jetzt eine Struktur

OpenXmlElementList ist jetzt eine Struktur. Es wird weiterhin zusätzlich zu implementiert IEnumerable<OpenXmlElement> , IReadOnlyList<OpenXmlElement> sofern verfügbar.

Erforderliche Aktion: Da es sich um eine Struktur handelt, werden Codemuster, die möglicherweise ein null Ergebnis haben, jetzt stattdessen eine OpenXmlElementList? sein. NULL-Überprüfungen werden vom Compiler gekennzeichnet, und der Wert selbst muss entwrappt werden, z. B.:

- OpenXmlElementList? slideIds = part?.Presentation?.SlideIdList?.ChildElements;
+ OpenXmlElementList slideIds = part?.Presentation?.SlideIdList?.ChildElements ?? default;

oder

- OpenXmlElementList? slideIds = part?.Presentation?.SlideIdList?.ChildElements;
+ OpenXmlElementList slideIds = (part?.Presentation?.SlideIdList?.ChildElements).GetValueOrDefault();

IdPartPair ist jetzt eine schreibgeschützte Struktur.

Dieser Typ wird zum Aufzählen von Paaren innerhalb eines Teils verwendet und hat viele unnötige Zuordnungen verursacht. Diese Änderung sollte bei der Neukompilierung transparent sein.

Aktion erforderlich: Da es sich jetzt um eine Struktur handelt, muss code zur Behandlung von NULL aktualisiert werden.

OpenXmlPartReader kennt nicht mehr alle Teile

In früheren Versionen wusste OpenXmlPartReader von allen stark typisierten Teilen. Um die für bessere AOT-Szenarien erforderliche Kopplung zu reduzieren, verfügen wir jetzt über typisierte Reader für bekannte Pakete: WordprocessingDocumentPartReader, SpreadsheetDocumentPartReaderund PresentationDocumentPartReader.

Aktion erforderlich: Ersetzen Sie bei Bedarf die Verwendung von OpenXmlPartReader durch dokumentspezifische Leser. Wenn Sie einen Teileleser aus einem bekannten Paket erstellen, verwenden Sie die Konstruktoren, die einen vorhandenen OpenXmlPart verwenden, der dann die erwarteten stark typisierten Teile erstellt.

Attribute für Schemainformationen wurden entfernt

SchemaAttrAttribute und ChildElementInfoAttribute wurden aus Typen entfernt, und die Typen selbst sind nicht mehr vorhanden.

Aktion erforderlich: Wenn diese Typen erforderlich waren, wenden Sie sich bitte an uns auf GitHub , um den besten Weg für Sie zu ermitteln.

OpenXmlPackage.Close wurde entfernt

Dies hat nichts anderes als den Aufruf .Dispose()von nützlich, sondern führte zu Verwirrung darüber, welche aufgerufen werden sollte. Dies wird jetzt mit der Erwartung entfernt, dass aufgerufen .Dispose()wird, vorzugsweise mit dem using-Muster.

Aktion erforderlich: Entfernen sie den Aufruf, und stellen Sie sicher, dass das Paket ordnungsgemäß verworfen wurde.

OpenXmlPackage.CanSave ist jetzt eine instance-Eigenschaft.

Diese Eigenschaft war früher eine statische Eigenschaft, die vom Framework abhängig war. Jetzt kann es sich je nach Einstellungen und Sicherungsspeicher paketabhängig instance ändern.

Aktion erforderlich: Ersetzen Sie die Verwendung der statischen Eigenschaft durch instance.

OpenXmlPackage.PartExtensionProvider wurde geändert

Diese Eigenschaft hat ein Wörterbuch bereitgestellt, das den Zugriff zum Ändern der verwendeten Erweiterungen ermöglichte. Dies wird jetzt durch die IPartExtensionFeatureunterstützt.

Aktion erforderlich: Ersetzen Sie die Verwendung durch OpenXmlPackage.Features.GetRequired<IPartExtensionFeature>().

Pakete mit MarkupCompatibilityProcessMode.ProcessAllParts verarbeiten jetzt tatsächlich alle Teile

Zuvor gab es eine Heuristik, um die Verarbeitung potenziell zu minimieren, wenn keine Teile geladen wurden. Dies führte jedoch zu Szenarien, in denen jemand den XML-Code manuell bearbeitete, sodass er beim Speichern nicht wirklich verarbeitet wurde. v3.0.0 behebt dieses Verhalten und verarbeitet alle Teile, wenn dies aktiviert wurde.

Aktion erforderlich: Wenn nur geladene Teile verarbeitet werden sollen, wechseln Sie zu MarkupCompatibilityProcessMode.ProcessLoadedPartsOnly