カスタム SDK 機能

[アーティクル]
01/21/2025

Open XML SDK の機能は、v2.14.0 以降で使用できます。これにより、動作と状態をドキュメントまたはパーツに含め、含まれているパッケージまたはパーツを再実装せずにカスタマイズできます。これは、パッケージ、パーツ、および要素の Features プロパティを使用してアクセスされます。

これは、その場で動作を簡単に置き換えることができる戦略パターンの実装です。これは、ASP.NET Coreの要求機能の後にモデル化されます。

機能の継承

パッケージ、パーツ、要素はすべて、独自の機能コレクションを持っています。ただし、使用可能な場合は、含まれているパーツとパッケージも継承されます。

これを強調表示するには、次のテストケースを参照してください。

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
{
}

注:

要素の特徴コレクションは読み取り専用です。これは、書き込み可能なメモリの問題が原因です。これが必要な場合は、 https://github.com/dotnet/open-xml-sdk に関して、お客様のシナリオをお知らせください。

登録済みフィーチャの視覚化

IFeatureCollectionのインボックス実装は、使用可能な機能とそのプロパティ/フィールドを確認できるように、便利なデバッグビューを提供します。

機能デバッグビュー

使用できる機能

現在使用できる機能については、以下で説明し、使用可能なスコープを示します。

IDisposableFeature

この機能を使用すると、パッケージまたはパーツが破棄または破棄されたときに実行する必要があるアクションを登録できます。

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 */);

パッケージとパーツには、この機能の独自の実装があります。要素は、使用可能な場合は、その包含パーツの機能を取得します。

IPackageEventsFeature

この機能を使用すると、パッケージが変更されたときのイベント通知を取得できます。

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

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

注:

パッケージが変更されていても、イベントが発生しない場合があります。イベントを発生させるのが理にかなっている領域がすべて特定されているわけではありません。問題が見つかる場合は、問題を報告してください。

IPartEventsFeature

この機能を使用すると、イベントの作成時のイベント通知を取得できます。これは、パーツまたはパッケージに追加される機能です。

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

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

一般に、イベントのシングルトン実装がある可能性があると仮定し、その部分が正しい部分であることを確認します。

注:

パーツが変更されていても、イベントが発生しない場合があります。イベントを発生させるのが理にかなっている領域がすべて特定されているわけではありません。問題が見つかる場合は、問題を報告してください。

IPartRootEventsFeature

この機能を使用すると、パーツルートが変更/読み込み/作成されたときのイベント通知を取得できます。これは、パーツレベルの機能に追加される機能です。

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

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

一般に、イベントのシングルトン実装がある可能性があると仮定し、その部分が正しい部分であることを確認します。

注:

パーツルートが変更されていても、イベントが発生しない場合があります。イベントを発生させるのが理にかなっている領域がすべて特定されているわけではありません。問題が見つかる場合は、問題を報告してください。

IRandomNumberGeneratorFeature

この機能を使用すると、共有サービスで乱数を生成し、配列を埋めることができます。

IParagraphIdGeneratorFeature

この機能を使用すると、段落 ID を含む要素の作成と追跡が可能になります。既定では、これにより値の一意性が確保され、存在する値が標準の制約に従って有効になります。この機能を使用するには:

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

この機能は、少し変更を加えて複数のドキュメント間で一意性を確保するためにも使用できます。

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);

次の方法で共有