Migration vers v3.0.0

Il existe un certain nombre de changements cassants entre la version 2.20.0 et la version 3.0.0 qui peuvent nécessiter des modifications au niveau de la source. Pour rappel, il existe deux types de changements cassants :

1. Binaire : quand un fichier binaire ne peut plus être utilisé comme drop dans le remplacement
2. Source : lorsque la source ne se compile plus

Les modifications apportées dans la version 3.0.0 étaient soit la suppression des obsoletions présentes dans le Kit de développement logiciel (SDK) pendant un certain temps, soit des modifications nécessaires pour des raisons architecturales (notamment pour une meilleure prise en charge et un meilleur découpage AOT). La majorité de ces modifications doivent être du côté des changements cassants binaires , tout en prenant en charge la compilation et le comportement attendu avec votre code précédent. Toutefois, il y a quelques cassages de rupture de source à connaître.

Changements cassants

La prise en charge de .NET Standard 1.3 a été supprimée

Aucune cible encore prise en charge ne nécessite .NET Standard 1.3 et peut utiliser .NET Standard 2.0 à la place. Le projet prend toujours en charge .NET Framework 3.5+ et toute plateforme .NET Standard 2.0 prise en charge.

Action nécessaire : Si vous utilisez .NET Standard 1.3, effectuez une mise à niveau vers une version prise en charge de .NET

Les infrastructures cibles ont changé

Afin de simplifier la création de packages, les TTF générés ont été modifiés pour certains packages. Toutefois, il ne doit y avoir aucun changement apparent pour les utilisateurs, car l’ensemble des plateformes prises en charge (en plus de .NET Standard 1.3 indiqué ci-dessus) reste le même.

Action nécessaire : Aucune

OpenXmlPart/OpenXmlContainer/OpenXmlPackage n’a plus de constructeurs publics

Ceux-ci n’ont jamais initialisé un comportement correct et n’auraient jamais dû être exposés.

Action nécessaire : utilisez des .Create(...) méthodes plutôt que des constructeurs.

L’infrastructure de prise en charge pour les types OpenXML est désormais dans le package DocumentFormat.OpenXml.Framework

À compter de la version 3.0.0, l’infrastructure de prise en charge du Kit de développement logiciel (SDK) Open XML se trouve désormais dans un package autonome, DocumentFormat.OpenXml.Framework.

Action nécessaire : si vous souhaitez utiliser uniquement OpenXmlPackage des types, vous n’avez plus besoin d’importer toutes les classes statiques et vous pouvez simplement référencer la bibliothèque de framework.

System.IO.Packaging n’est plus utilisé directement

Il y a eu des problèmes avec le comportement d’obtention dont nous avons besoin à partir de l’espace de noms System.IO.Packaging. À compter de la version 3.0, un nouvel ensemble d’interfaces dans l’espace DocumentFormat.OpenXml.Packaging de noms sera utilisé pour accéder aux propriétés du package.

Remarque

Ces types sont actuellement marqués comme obsolètes, mais uniquement dans le sens où nous nous réservons le droit de modifier leur forme par commentaire. Soyez prudent en utilisant ces types, car ils peuvent changer à l’avenir. À un moment donné, nous allons supprimer les obsoletions et elles seront considérées comme des API stables. Pour plus d’informations , voir ici .

Action nécessaire : Si vous utilisez OpenXmlPackage.Package, le package retourné n’est plus de type System.IO.Packaging.Package, mais de DocumentFormat.OpenXml.Packaging.IPackage.

Les méthodes sur les parties pour ajouter des parties enfants sont désormais des méthodes d’extension

Il existait un certain nombre de méthodes dupliquées qui ajoutaient des parties de manière bien définie. Pour consolider cela, si un composant prend en charge ISupportedRelationship<T>, les méthodes d’extension peuvent être écrites pour prendre en charge le comportement spécifique que ce composant peut fournir. Les méthodes existantes pour cela doivent être redirigées de manière transparente vers les nouvelles méthodes d’extension lors de la compilation.

Action nécessaire : Aucune

OpenXmlAttribute est désormais un struct en lecture seule

Ce type avait des getters et des setters mutables. En tant que struct, cela était facile à utiliser, et aurait dû être fait en lecture seule dès le début.

Action nécessaire : Si vous prévoyez de muter un OpenXmlAttribute sur place, créez-en un à la place.

EnumValue<TEnum> contient désormais des structs

À compter de la version 3.0.0, EnumValue<T> encapsule un type personnalisé qui contient les informations sur la valeur d’énumération. Auparavant, ces types étaient stockés dans des valeurs enum dans le système de type C#, mais nécessitaient une réflexion pour y accéder, ce qui provoquait de très grandes applications compilées AOT.

Action nécessaire : Une surface d’API similaire est disponible, mais les valeurs d’énumération exposées ne sont plus des constantes et ne seront pas disponibles dans certains scénarios (c’est-à-dire les valeurs d’attribut).

Une modification courante requise est que les instructions switch ne fonctionnent plus :

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

Devient:

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

OpenXmlElementList est maintenant un struct

OpenXmlElementList est désormais un struct. Il implémente IEnumerable<OpenXmlElement> toujours en plus de là où il est IReadOnlyList<OpenXmlElement> disponible.

Action nécessaire : Étant donné qu’il s’agit d’un struct, les modèles de code qui peuvent avoir un null résultat seront désormais un OpenXmlElementList? à la place. Les vérifications Null sont signalées par le compilateur et la valeur elle-même doit être décompressée, par exemple :

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

ou

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

IdPartPair est maintenant un struct en lecture seule

Ce type est utilisé pour énumérer des paires au sein d’un composant et a provoqué de nombreuses allocations inutiles. Cette modification doit être transparente lors de la recompilation.

Action nécessaire : Étant donné qu’il s’agit désormais d’un struct, le code de gestion null doit être mis à jour.

OpenXmlPartReader ne connaît plus toutes les parties

Dans les versions précédentes, OpenXmlPartReader connaissait tous les composants fortement typés. Afin de réduire le couplage requis pour de meilleurs scénarios AOT, nous avons maintenant des lecteurs typés pour les packages connus : WordprocessingDocumentPartReader, SpreadsheetDocumentPartReaderet PresentationDocumentPartReader.

Action nécessaire : remplacez l’utilisation de OpenXmlPartReader par des lecteurs spécifiques au document si nécessaire. Si vous créez un lecteur de composant à partir d’un package connu, utilisez les constructeurs qui prennent un existant OpenXmlPart , ce qui crée ensuite les parties fortement typées attendues.

Les attributs des informations de schéma ont été supprimés

SchemaAttrAttribute et ChildElementInfoAttribute ont été supprimés des types et les types eux-mêmes ne sont plus présents.

Action nécessaire : Si ces types étaient nécessaires, contactez-nous sur GitHub afin d’identifier la meilleure façon d’aller de l’avant pour vous.

OpenXmlPackage.Close a été supprimé

Cela n’a rien d’utile en plus d’appeler .Dispose(), mais a provoqué une confusion quant à ce qui doit être appelé. Cela est maintenant supprimé avec l’attente d’appeler .Dispose(), de préférence avec le modèle d’utilisation.

Action nécessaire : Supprimer l’appel et vérifier que le package est supprimé correctement

OpenXmlPackage.CanSave est désormais une propriété instance

Cette propriété était auparavant une propriété statique qui dépendait de l’infrastructure. Désormais, il peut changer de instance par package en fonction des paramètres et du magasin de stockage.

Action nécessaire : Remplacez l’utilisation de la propriété statique par instance.

OpenXmlPackage.PartExtensionProvider a été modifié

Cette propriété fournissait un dictionnaire qui permettait d’accéder à la modification des extensions utilisées. Cela est maintenant soutenu par le IPartExtensionFeature.

Action nécessaire : Remplacez l’utilisation par OpenXmlPackage.Features.GetRequired<IPartExtensionFeature>().

Les packages avec MarkupCompatibilityProcessMode.ProcessAllParts traitent désormais toutes les parties

Auparavant, il existait une heuristique pour réduire potentiellement le traitement si aucune partie n’avait été chargée. Toutefois, cela a provoqué des scénarios tels que ceux où une personne a modifié manuellement le xml pour ne pas réellement traiter lors de l’enregistrement. La version 3.0.0 corrige ce comportement et traite toutes les parties si cette option a été activée.

Action nécessaire : Si vous souhaitez que seules les parties chargées soient traitées, remplacez par MarkupCompatibilityProcessMode.ProcessLoadedPartsOnly