Microsoft.DotNet.ApiCompat.Tool グローバル ツール

  • [アーティクル]

Microsoft.DotNet.ApiCompat.Tool ツールを使うと、MSBuild の外部で API 互換性チェックを実行できます。 このツールには、次の 2 つのモードがあります。

  • パッケージをベースライン パッケージと比較します。
  • アセンブリをベースライン アセンブリと比較します。

インストール

このツールをインストールするには、次のコマンドを実行します。

dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool

グローバル ツールのインストールの詳細については、「グローバル ツールのインストール」を参照してください。

使用方法

Microsoft.DotNet.ApiCompat.Tool [command] [options]

または

apicompat [command] [options]

コマンド

  • package | --package <PACKAGE_FILE>

    パッケージ資産の互換性を検証します。 指定しない場合、アセンブリが比較されます。 <PACKAGE_FILE> は、パッケージ ファイルへのパスを指定します。

[オプション]

一部のオプションは、アセンブリとパッケージの検証の両方に適用されます。 その他はアセンブリのみまたはパッケージのみに適用されます。

[全般] オプション

  • --version

    バージョン情報を表示します。

  • --generate-suppression-file

    互換性抑制ファイルを生成します。

  • --preserve-unnecessary-suppressions

    抑制ファイルを再生成するときに不要な抑制を保持します。

    既存の抑制ファイルが再生成されるときは、その内容が読み取られ、一連の抑制に逆シリアル化された後、リストに格納されます。 非互換性が修正された場合、一部の抑制は不要になる可能性があります。 抑制をシリアル化してディスクに戻すとき、ユーザーは、このオプションを指定することで、既存の (逆シリアル化された) 式を "すべて" そのままにすることを選択できます。

  • --permit-unnecessary-suppressions

    抑制ファイル内の不要な抑制を許可します。

  • --suppression-file <FILE>

    読み取り元の 1 つ以上の抑制ファイルへのパスを指定します。

  • --suppression-output-file <FILE>

    --generate-suppression-file の指定時に書き込む抑制ファイルへのパスを指定します。 指定しないと、最初の --suppression-file パスが使われます。

  • --noWarn <NOWARN_STRING>

    抑制する診断 ID を指定します。 たとえば、"$(NoWarn);PKV0001" のようにします。

  • --respect-internals

    internal API と public API の両方を確認します。

  • --roslyn-assemblies-path <FILE>

    使用する Microsoft.CodeAnalysis アセンブリを含むディレクトリへのパスを指定します。 このプロパティを設定する必要があるのは、SDK のコンパイラより新しいコンパイラでテストする場合のみです。

  • -v, --verbosity [high|low|normal]

    ログ レベルの詳細度を制御します。 使用可能な値は、high、normal、low です。 既定値は、normal です。

  • --enable-rule-cannot-change-parameter-name

    パラメータ名がパブリック メソッドで変更されたかどうかをチェックするルールを有効にします。

  • --enable-rule-attributes-must-match

    属性が一致するかどうかをチェックするルールを有効にします。

  • --exclude-attributes-file <FILE>

    除外する属性が DocId 形式で含まれる 1 つ以上のファイルへのパスを指定します。

アセンブリ固有のオプション

これらのオプションは、アセンブリを比較する場合にのみ適用されます。

  • -l, --left, --left-assembly <PATH>

    比較対象の左側として機能する 1 つ以上のアセンブリへのパスを指定します。 このオプションは、アセンブリを比較するときに必要です。

  • -r, --right, --right-assembly <PATH>

    比較対象の右側として機能する 1 つ以上のアセンブリへのパスを指定します。 このオプションは、アセンブリを比較するときに必要です。

  • --strict-mode

    API 互換性チェックを厳格モードで実行します。

パッケージ固有のオプション

これらのオプションは、パッケージを比較する場合にのみ適用されます。

  • --baseline-package

    現在のパッケージを検証する対象のベースライン パッケージへのパスを指定します。

  • --enable-strict-mode-for-compatible-tfms

    互換性のあるすべてのターゲット フレームワークのコントラクト アセンブリと実装アセンブリについて、API の互換性を厳格モードで検証します。 既定値は、true です。

  • --enable-strict-mode-for-compatible-frameworks-in-package

    ターゲット フレームワークに基づいて互換性のあるアセンブリについて、API の互換性を厳格モードで検証します。

  • --enable-strict-mode-for-baseline-validation

    パッケージ ベースライン チェックについて、API の互換性を厳格モードで検証します。

  • --package-assembly-references

    パッケージ内の特定のターゲット フレームワークのアセンブリ参照またはその基になるディレクトリへのパスを指定します。 複数の値はコンマで区切ります。

  • --baseline-package-assembly-references

    ベースライン パッケージ内の特定のターゲット フレームワークのアセンブリ参照またはその基になるディレクトリへのパスを指定します。 複数の値はコンマで区切ります。

  • --baseline-package-frameworks-to-ignore

    ベースライン パッケージから無視する一連のターゲット フレームワークを指定します。 フレームワーク文字列は、ベースライン パッケージ内のフォルダー名と正確に一致する必要があります。

例

次のコマンドは、アセンブリの現在のバージョンとベースライン バージョンを比較します。

apicompat --left bin\Release\net8.0\LibApp5.dll --right bin\Release\net8.0\LibApp5-baseline.dll

次のコマンドは、パッケージの現在のバージョンとベースライン バージョンを比較します。

apicompat package "bin\Release\LibApp5.1.0.0.nupkg" --baseline-package "bin\Release\LibApp5.2.0.0.nupkg"

次の例では、アセンブリの現在のバージョンとベースライン バージョンで、パラメーター名の変更のチェックなどの比較を行うコマンドを示します。 この例では、パラメーター名が変更された場合に出力がどのようになるかも示されています。

>apicompat -l LibApp5-baseline.dll -r LibApp5.dll --enable-rule-cannot-change-parameter-name
API compatibility errors between 'LibApp5-baseline.dll' (left) and 'LibApp5.dll' (right):
CP0017: Parameter name on member 'KitchenHelpers.ToastBreadAsync(int, int)'
changed from 'slices' to 'numSlices'.
API breaking changes found. If those are intentional, the APICompat
suppression file can be updated by specifying the '--generate-suppression-file' parameter.