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

Článek
12/05/2023

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.

Instalace

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.

Využití

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

nebo

apicompat [command] [options]

Příkazy

package | --package <PACKAGE_FILE>

Ověří kompatibilitu prostředků 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 ověřování sestavení i balíčku. Ostatní se vztahují pouze na sestavení nebo pouze balíčky.

Obecné možnosti

--version

Zobrazuje informace o verzi.
--generate-suppression-file

Vygeneruje soubor potlačení kompatibility.
--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 jsou potlačení serializována zpět na disk, můžete zvolit, že chcete zachovat všechny existující (deserializované) výrazy zadáním této možnosti.
--permit-unnecessary-suppressions

Umožňuje nepotřebné potlačení v souboru potlačení.
--suppression-file <FILE>

Určuje cestu k jednomu nebo více souborům potlačení, ze které se mají číst.
--suppression-output-file <FILE>

Určuje cestu k souboru potlačení pro zápis do --generate-suppression-file zadaného umístění. Pokud není zadáno, použije se první --suppression-file cesta.
--noWarn <NOWARN_STRING>

Určuje ID diagnostiky, která se mají potlačit. Například "$(NoWarn);PKV0001".
--respect-internals

Kontroluje rozhraní internal API i public rozhraní API.
--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 lze použít pouze při porovná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 se vyžaduje při porovnávání sestavení.
-r, --right, --right-assembly <PATH>

Určuje cestu k jednomu nebo více sestavením, která slouží jako pravá strana pro porovnání. Tato možnost se vyžaduje 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 balíčku směrného plánu pro 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ílovou architekturu v balíčku směrného plánu . Oddělte více hodnot čárkou.
--baseline-package-frameworks-to-ignore

Určuje sadu cílových architektur, které se mají z balíčku směrného plánu 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.

Share via