Globální nástroj Microsoft.DotNet.ApiCompat.Tool

Nástroj Microsoft.DotNet.ApiCompat.Tool umožňuje provádět kontroly kompatibility rozhraní API mimo nástroj MSBuild. Nástroj má dva režimy:

• Porovnejte balíček se standardním balíčkem.
• Porovnejte sestavení se standardním sestavením.

Instalujte

Pokud chcete nástroj nainstalovat, spusťte následující příkaz.

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

Další informace o instalaci globálních nástrojů naleznete v tématu Instalace globálního nástroje.

Použití

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

nebo

apicompat [command] [options]

Příkazy

• package | --package <PACKAGE_FILE>

  Ověří kompatibilitu zdrojů balíčků. Pokud není zadaný, nástroj porovnává sestavení. <PACKAGE_FILE> určuje cestu k souboru balíčku.

Možnosti

Některé možnosti platí pro validaci sestavení i balíku. Ostatní se vztahují pouze na sestavení nebo pouze na balíčky.

Obecné možnosti

• --version

  Zobrazuje informace o verzi.

• --generate-suppression-file

  Vygeneruje soubor pro potlačení problému s kompatibilitou.

• --preserve-unnecessary-suppressions

  Zachovává nepotřebné potlačení při opětovném vygenerování souboru potlačení.

  Při opětovném vygenerování existujícího souboru potlačení se jeho obsah načte, deserializuje do sady potlačení a uloží se do seznamu. Některé potlačení už nemusí být nutné, pokud byla opravena nekompatibilitu. Pokud je potlačení znovu serializováno na disk, můžete zvolit zachování všech existujících (deserializovaných) výrazů zadáním této možnosti.

• --permit-unnecessary-suppressions

  Povoluje zbytečná potlačení v souboru pro potlačení.

• --suppression-file <FILE>

  Určuje cestu k jednomu nebo více souborům potlačení, ze kterých se má číst.

• --suppression-output-file <FILE>

  Určuje cestu k souboru pro potlačení, do kterého se bude zapisovat, když je zadáno --generate-suppression-file. Pokud není zadána, použije se cesta první --suppression-file.

• --noWarn <NOWARN_STRING>

  Určuje diagnostické identifikátory, které se mají potlačit. Například: "$(NoWarn);PKV0001".

• --respect-internals

  Kontroluje obě API, internal i public.

• --roslyn-assemblies-path <FILE>

  Určuje cestu k adresáři, který obsahuje sestavení Microsoft.CodeAnalysis, která chcete použít. Tuto vlastnost je potřeba nastavit jenom v případě, že chcete testovat s novějším kompilátorem, než jaký je v sadě SDK.

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

  Řídí úroveň podrobností na úrovni protokolu. Povolené hodnoty jsou high, normala low. Výchozí hodnota je normal.

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

  Povolí pravidlo, které kontroluje, jestli se názvy parametrů změnily ve veřejných metodách.

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

  Povolí pravidlo, které kontroluje, jestli se atributy shodují.

• --exclude-attributes-file <FILE>

  Určuje cestu k jednomu nebo více souborům, které obsahují atributy, které se mají vyloučit ve formátu DocId .

Možnosti specifické pro sestavení

Tyto možnosti jsou použitelné pouze při porovnávání sestavení.

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

  Určuje cestu k jednomu nebo více sestavením, která slouží jako levá strana pro porovnání. Tato možnost je nutná při porovnávání sestavení.

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

  Určuje cestu k jedné nebo více sestavám, které slouží jako pravá strana pro porovnání. Tato možnost je nutná při porovnávání sestavení.

• --strict-mode

  Provádí kontroly kompatibility rozhraní API v přísném režimu.

Možnosti specifické pro balíček

Tyto možnosti se použijí pouze při porovnání balíčků.

• --baseline-package

  Určuje cestu k základnímu balíčku k ověření aktuálního balíčku.

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

  Ověřuje kompatibilitu rozhraní API v přísném režimu pro sestavení kontraktu a implementace pro všechny kompatibilní cílové architektury. Výchozí hodnota je true.

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

  Ověřuje kompatibilitu rozhraní API v přísném režimu pro sestavení, která jsou kompatibilní na základě jejich cílové architektury.

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

  Ověřuje kompatibilitu rozhraní API v přísném režimu pro kontroly standardních hodnot balíčků.

• --package-assembly-references

  Určuje cesty k odkazům na sestavení nebo jejich podkladovým adresářům pro konkrétní cílovou architekturu v balíčku. Oddělte více hodnot čárkou.

• --baseline-package-assembly-references

  Určuje cesty k odkazům na sestavení nebo jejich podkladovým adresářům pro konkrétní cílový rámec v balíčku základní. Oddělte více hodnot čárkou.

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

  Určuje sadu cílových frameworků, které se mají z výchozího balíčku ignorovat. Řetězec architektury musí přesně odpovídat názvu složky v balíčku podle směrného plánu.

Příklady

Následující příkaz porovnává aktuální a základní verze sestavení.

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

Následující příkaz porovnává aktuální a základní verze balíčku.

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

Následující příklad ukazuje příkaz, který porovná aktuální a základní verze sestavení, včetně kontroly změn názvu parametru. Příklad také ukazuje, jak může výstup vypadat, pokud se změnil název parametru.

>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.