Fonctionnalités du KIT de développement logiciel (SDK) personnalisées

Les fonctionnalités du Kit de développement logiciel (SDK) Open XML sont disponibles à partir de la version 2.14.0, ce qui permet de contenir le comportement et l’état dans le document ou le composant et de les personnaliser sans ré-implémenter le package ou le composant contenant. Cette propriété est accessible via Features la propriété sur les packages, les parties et les éléments.

Il s’agit d’une implémentation du modèle de stratégie qui facilite le remplacement du comportement à la volée. Il est modélisé d’après les fonctionnalités de requête dans ASP.NET Core.

Héritage des fonctionnalités

Les packages, les composants et les éléments ont tous leur propre collection de caractéristiques. Toutefois, ils héritent également du composant contenant et du package s’il est disponible.

Pour le mettre en évidence, consultez le cas de test ci-dessous :

OpenXmlPackage package = /* Create a package */;

var packageFeature = new PrivateFeature();
package.Features.Set<PrivateFeature>(packageFeature);

var part = package.GetPartById("existingPart");
Assert.Same(part.Features.GetRequired<PrivateFeature>(), package.Features.GetRequired<PrivateFeature>());

part.Features.Set<PrivateFeature>(new());
Assert.NotSame(part.Features.GetRequired<PrivateFeature>(), package.Features.GetRequired<PrivateFeature>());


private sealed class PrivateFeature
{
}

Remarque

La collection de caractéristiques sur les éléments est en lecture seule. Cela est dû à des problèmes de mémoire s’il est rendu accessible en écriture. Si nécessaire, contactez-nous https://github.com/dotnet/open-xml-sdk pour nous faire part de votre scénario.

Visualisation des fonctionnalités inscrites

Les implémentations intégrées de fournissent IFeatureCollection une vue de débogage utile pour vous permettre de voir les fonctionnalités disponibles et leurs propriétés/champs :

Fonctionnalités disponibles

Les fonctionnalités actuellement disponibles sont décrites ci-dessous et dans quelle étendue elles sont disponibles :

IDisposableFeature

Cette fonctionnalité permet d’inscrire des actions qui doivent s’exécuter lorsqu’un package ou une partie est détruit ou supprimé :

OpenXmlPackage package = GetSomePackage();
package.Features.Get<IDisposableFeature>().Register(() => /* Some action that is called when the package is disposed */);

OpenXmlPart part = GetSomePart();
part.Features.Get<IDisposableFeature>().Register(() => /* Some action that is called when the part is removed or closed */);

Les packages et les composants auront leurs propres implémentations de cette fonctionnalité. Les éléments récupèrent la fonctionnalité pour leur partie contenante, le cas échéant.

IPackageEventsFeature

Cette fonctionnalité permet d’obtenir des notifications d’événement en cas de modification d’un package :

OpenXmlPackage package = GetSomePackage();
package.TryAddPackageEventsFeature();

var feature = package.Features.GetRequired<IPackageEventsFeature>();

Remarque

Il peut arriver que le package soit modifié, mais qu’aucun événement n’est déclenché. On n’a pas identifié tous les domaines où il serait judicieux de déclencher un événement. S’il vous plaît un problème si vous en trouvez un.

IPartEventsFeature

Cette fonctionnalité permet d’obtenir des notifications d’événement lors de la création d’un événement. Il s’agit d’une fonctionnalité qui est ajoutée au composant ou au package :

OpenXmlPart part = GetSomePackage();
package.AddPartEventsFeature();

var feature = part.Features.GetRequired<IPartEventsFeature>();

En règle générale, supposons qu’il peut y avoir une implémentation singleton pour les événements et vérifiez que la partie est correcte.

Remarque

Il peut arriver que le composant soit modifié, mais qu’un événement ne soit pas déclenché. On n’a pas identifié tous les domaines où il serait judicieux de déclencher un événement. S’il vous plaît un problème si vous en trouvez un.

IPartRootEventsFeature

Cette fonctionnalité permet d’obtenir des notifications d’événement quand une racine de composant est modifiée/chargée/créée/etc. Il s’agit d’une fonctionnalité qui est ajoutée à la fonctionnalité de niveau partie :

OpenXmlPart part = GetSomePart();
part.AddPartRootEventsFeature();

var feature = part.Features.GetRequired<IPartRootEventsFeature>();

En règle générale, supposons qu’il peut y avoir une implémentation singleton pour les événements et vérifiez que la partie est correcte.

Remarque

Il peut arriver que la racine du composant soit modifiée, mais qu’aucun événement n’est déclenché. On n’a pas identifié tous les domaines où il serait judicieux de déclencher un événement. S’il vous plaît un problème si vous en trouvez un.

IRandomNumberGeneratorFeature

Cette fonctionnalité permet à un service partagé de générer des nombres aléatoires et de remplir un tableau.

IParagraphIdGeneratorFeature

Cette fonctionnalité permet le remplissage et le suivi des éléments qui contiennent des ID de paragraphe. Par défaut, cela garantit l’unicité des valeurs et garantit que les valeurs qui existent sont valides selon les contraintes de la norme. Pour utiliser cette fonctionnalité :

WordprocessingDocument document = CreateWordDocument();
document.TryAddParagraphIdFeature();

var part = doc.AddMainDocumentPart();
var body = new Body();
part.Document = new Document(body);

var p = new Paragraph();
body.AddChild(p); // After adding p.ParagraphId will be set to a unique, valid value

Cette fonctionnalité peut également être utilisée pour garantir l’unicité entre plusieurs documents avec une légère modification :

using var doc1 = CreateDocument1();
using var doc2 = CreateDocument2();

var shared = doc1
    .AddSharedParagraphIdFeature()
    .Add(doc2);

// Add item to doc1
var part1 = doc1.AddMainDocumentPart();
var body1 = new Body();
var p1 = new Paragraph();
part1.Document = new Document(body1);
body1.AddChild(p1);

// Add item with same ID to doc2
var part2 = doc2.AddMainDocumentPart();
var body2 = new Body();
var p2 = new Paragraph { ParagraphId = p1.ParagraphId };
part2.Document = new Document(body2);
body2.AddChild(p2);

// Assert
Assert.NotEqual(p1.ParagraphId, p2.ParagraphId);
Assert.Equal(2, shared.Count);

IPartRootXElementFeature

Cette fonctionnalité permet de fonctionner sur un OpenXmlPart en utilisant des fonctionnalités XLinq et en manipulant directement des XElement nœuds.

OpenXmlPart part = GetSomePart();

var node = new(W.document, new XAttribute(XNamespace.Xmlns + "w", W.w),
    new XElement(W.body,
        new XElement(W.p,
            new XElement(W.r,
                new XElement(W.t, "Hello World!")))));

part.SetXElement(node);

Il XElement est mis en cache, mais sera synchronisé avec le composant sous-jacent s’il devait changer.