v3.0.0 への移行

  • [アーティクル]

v2.20.0 と v3.0.0 の間には、ソース レベルの変更が必要になる可能性があるいくつかの破壊的変更があります。 リマインダーとして、次の 2 種類の破壊的変更があります。

  1. バイナリ: バイナリを置換のドロップとして使用できなくなった場合
  2. ソース: ソースがコンパイルされなくなった場合

v3.0.0 で行われた変更は、しばらく SDK に存在する obsoletion の削除か、アーキテクチャ上の理由で必要な変更 (特に AOT のサポートとトリミングの向上のために) でした。 これらの変更の大部分は バイナリ 破壊的変更側に配置する必要があり、以前のコードでコンパイルと予期される動作を引き続きサポートします。 ただし、いくつかのソースの破壊的な状況を認識する必要があります。

破壊的変更

.NET Standard 1.3 のサポートが削除されました

まだサポート対象のターゲットに .NET Standard 1.3 は必要ありません。代わりに .NET Standard 2.0 を使用できます。 このプロジェクトでは、.NET Framework 3.5 以降と、サポートされている任意の .NET Standard 2.0 プラットフォームが引き続きサポートされます。

必要なアクション: .NET Standard 1.3 を使用している場合は、サポートされているバージョンの .NET にアップグレードしてください

ターゲット フレームワークが変更されました

パッケージの作成を簡略化するために、ビルドされた TFM は一部のパッケージに対して変更されています。 ただし、サポートされているプラットフォーム全体 (上記の .NET Standard 1.3 以外) は変わらないため、ユーザーに明らかな変更は必要ありません。

必要なアクション: なし

OpenXmlPart/OpenXmlContainer/OpenXmlPackage にパブリック コンストラクターが存在しなくなりました

これらは正しい動作を初期化することはなく、公開されるべきではありません。

必要なアクション: コンストラクターではなくメソッドを使用 .Create(...) します。

OpenXML 型のサポート フレームワークが DocumentFormat.OpenXml.Framework パッケージに追加されました

v3.0.0 以降、Open XML SDK のサポート フレームワークは、スタンドアロン パッケージ DocumentFormat.OpenXml.Framework 内になりました。

必要なアクション: 型だけを OpenXmlPackage 操作する場合は、すべての静的クラスを取り込む必要がなくなり、フレームワーク ライブラリを参照できます。

System.IO.Packaging が直接使用されなくなりました

System.IO.Packaging 名前空間から必要な動作を取得することに問題があります。 v3.0 以降では、名前空間内の新しいインターフェイス セットを DocumentFormat.OpenXml.Packaging 使用してパッケージ プロパティにアクセスします。

注:

これらの型は現在、廃止済みとしてマークされていますが、フィードバックごとに形状を変更する権利を留保するという意味でのみ使用されます。 これらの型は将来変更される可能性があるため、使用には注意してください。 ある時点で、obsoletions を削除します。これらは安定した API と見なされます。 詳細については 、こちらを 参照してください。

必要なアクション: を使用している OpenXmlPackage.Package場合、返されるパッケージは 型ではなく System.IO.Packaging.Package、 です DocumentFormat.OpenXml.Packaging.IPackage。

子パーツを追加するパーツのメソッドが拡張メソッドになりました

適切に定義された方法でパーツを追加する重複したメソッドが多数ありました。 これを統合するために、パーツで がサポートされている ISupportedRelationship<T>場合は、拡張メソッドを記述して、パーツが提供できる特定の動作をサポートできます。 このための既存のメソッドは、コンパイル時に新しい拡張メソッドに透過的に再ターゲットする必要があります。

必要なアクション: なし

OpenXmlAttribute が読み取り専用構造体になりました

この型は、変更可能なゲッターとセッターを持つ場合に使用されます。 構造体として、これは誤用が容易であり、最初から読み取り専用になるはずです。

必要なアクション: OpenXmlAttribute を変更する場合は、代わりに新しい操作を作成してください。

EnumValue<TEnum> に構造体が含まれるようになりました

v3.0.0 以降では、 EnumValue<T> 列挙値に関する情報を含むカスタム型をラップします。 以前は、これらの型は C# 型システムの列挙値に格納されていましたが、アクセスするにはリフレクションが必要であり、非常に大きな AOT コンパイル アプリケーションが発生していました。

必要なアクション: 同様の API サーフェスを使用できますが、これに対して公開されている列挙値は定数ではなくなり、以前のいくつかのシナリオ (属性値) では使用できません。

必要な一般的な変更は、switch ステートメントが機能しなくなった点です。

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

なる：

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

OpenXmlElementList が構造体になりました

OpenXmlElementList が構造体になりました。 利用可能な場所に加えて、IReadOnlyList<OpenXmlElement>まだ実装されていますIEnumerable<OpenXmlElement>。

必要なアクション: これは構造体であるため、結果を持つ null 可能性のあるコード パターンは代わりに になります OpenXmlElementList? 。 null チェックはコンパイラによってフラグが設定され、値自体は次のようにラップ解除する必要があります。

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

または

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

IdPartPair が読み取り専用構造体になりました

この型は、パーツ内のペアを列挙するために使用され、多くの不要な割り当てが発生しました。 この変更は、再コンパイル時に透過的である必要があります。

必要なアクション: これは構造体であるため、null 処理コードを更新する必要があります。

OpenXmlPartReader は、すべてのパーツについて認識しなくなりました

以前のバージョンでは、 OpenXmlPartReader は 厳密に型指定されたすべてのパーツについて知っていました。 より優れた AOT シナリオに必要な結合を減らすために、既知のパッケージのリーダーを型指定しました。 WordprocessingDocumentPartReaderSpreadsheetDocumentPartReaderPresentationDocumentPartReader

必要なアクション: の使用を、必要に応じてドキュメント固有の OpenXmlPartReader リーダーに置き換えます。 既知のパッケージからパーツ リーダーを作成する場合は、既存 OpenXmlPart のものを受け取るコンストラクターを使用して、予想される厳密に型指定されたパーツを作成してください。

スキーマ情報の属性が削除されました

SchemaAttrAttribute と ChildElementInfoAttribute が型から削除され、型自体が存在しなくなりました。

必要なアクション: これらの種類が必要な場合は、 GitHub に問い合わせて、最適な方法を特定してください。

OpenXmlPackage.Close が削除されました

これは、 呼び出し以外に何も役に立たなかったが、どちらを呼び出 .Dispose()すべきかについての混乱を引き起こした。 これは、 を呼び出 .Dispose()すと予想され、できれば using パターンで削除されます。

必要なアクション: 呼び出しを削除し、パッケージが正しく破棄されていることを確認する

OpenXmlPackage.CanSave がインスタンス プロパティになりました

このプロパティは、フレームワークに依存していた静的プロパティでした。 これで、設定とバッキング ストアに応じてパッケージごとのインスタンスが変更される可能性があります。

必要なアクション: 静的プロパティの使用をインスタンスに置き換えます。

OpenXmlPackage.PartExtensionProvider が変更されました

このプロパティは、使用する拡張機能を変更するためのアクセスを許可するディクショナリを提供しました。 これは、 によって IPartExtensionFeatureサポートされるようになりました。

必要なアクション: 使用状況を に OpenXmlPackage.Features.GetRequired<IPartExtensionFeature>()置き換えます。

MarkupCompatibilityProcessMode.ProcessAllParts を含むパッケージが、実際にすべてのパーツを処理するようになりました

以前は、部品が読み込まれていない場合に処理を最小限に抑えるヒューリスティックがありました。 ただし、これにより、誰かが保存時に実際に処理しないように XML を手動で編集したシナリオなどのシナリオが発生しました。 v3.0.0 では、この動作が修正され、オプトインされている場合は、すべての部分が処理されます。

必要なアクション: 読み込まれたパーツのみを処理する場合は、 MarkupCompatibilityProcessMode.ProcessLoadedPartsOnly