API 互換性ツール

  • [アーティクル]

.NET ライブラリ作成者にとって、クロスプラットフォームの互換性は主流の要件になっています。 ただし、アセンブリとパッケージを検証するツールがないと、意図しない破壊的変更が含まれる可能性があります。 ライブラリの作成者は、マルチターゲット アセンブリに互換性があることを確認する必要があります。 たとえば、.NET 6 および .NET Standard 2.0 をマルチターゲットとするパッケージの場合、.NET Standard 2.0 バイナリを対象にコンパイルされたコードを、.NET 6 バイナリを対象にして確実に実行できる必要があります。

ある変更が、安全で互換性があると捉えられることがあります。それは、その変更を利用しているソースが、変更しなくても引き続きコンパイルされた場合です。 ただし、コンシューマーが再コンパイルされなかった場合、その変更によって実行時に問題が発生する可能性があります。 たとえば、省略可能なパラメーターをメソッドに追加したり、定数の値を変更したりすると、このような互換性の問題が発生する可能性があります。

.NET SDK には、異なるターゲット フレームワーク用にビルドされたバージョンを比較するためのさまざまな方法が用意されています。 ベースライン バージョンに対して新しいバージョンを検証して、破壊的変更が発生していないことを確認することもできます。 MSBuild タスクを有効にして、コンパイル時、または pack を実行したときのパッケージのライブラリを検証します。 または、Microsoft.DotNet.ApiCompat.Tool グローバル ツールを使用して、MSBuild の外部で検証します。

パッケージの検証の詳細については、「パッケージの検証」を参照してください。アセンブリの検証は、アプリで pack を実行できない場合に使用する必要があります。 アセンブリの検証の詳細については、「アセンブリの検証」を参照してください。

Note

MSBuild タスクとしてアセンブリの検証を実行するには、Microsoft.DotNet.ApiCompat.Task にパッケージ参照を追加する必要があります。 同様に、.NET SDK でまだ使用できない新しい機能をテストする場合にも、このパッケージ参照を追加できます。 たとえば、.NET 8 SDK の使用中に Microsoft.DotNet.ApiCompat.Task パッケージの 9.0.100-preview バージョンを参照できます。

厳格モード

既定では、検証によって "互換性" チェックが実行されます。 ただし、"厳格モード" にオプトインすることもできます。 厳格モードでは、検証によって "等値" チェックが実行されます。 等値は、API の追加やアセンブリの変更 (互換性のあるものも含む) が行われないことを意味します。

厳格モードのユース ケースには次のものがあります。

  • 通常、API の追加が禁止されているサービス。
  • API の変更を追跡する場合。 APICompatGenerateSuppressionFile を true に設定すると、API 互換性機能によって抑制ファイル内のすべての互換性の差異が記録されます。

コマンドライン ツールで厳格モードを有効にするには、--strict-mode オプションまたは --enable-strict* オプションのいずれかを指定します。 MSBuild タスクの厳格モードを有効にするには、次の MSBuild プロパティをプロジェクト ファイルに 1 つ以上追加します。