Globalt verktyg för Microsoft.DotNet.ApiCompat.Tool

Artikel
12/05/2023

Med verktyget Microsoft.DotNet.ApiCompat.Tool kan du utföra API-kompatibilitetskontroller utanför MSBuild. Verktyget har två lägen:

Jämför ett paket med ett baslinjepaket.
Jämför en sammansättning med en baslinjesammansättning.

Installera

Kör följande kommando för att installera verktyget.

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

Mer information om hur du installerar globala verktyg finns i Installera ett globalt verktyg.

Användning

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

-eller-

apicompat [command] [options]

Kommandon

package | --package <PACKAGE_FILE>

Verifierar pakettillgångarnas kompatibilitet. Om det är ospecificerat jämför verktyget sammansättningar. <PACKAGE_FILE> anger sökvägen till paketfilen.

Alternativ

Vissa alternativ gäller för både sammansättning och paketverifiering. Andra gäller endast för sammansättningar eller endast paket.

Allmänna alternativ

--version

Visar versionsinformation.
--generate-suppression-file

Genererar en kompatibilitetsundertryckningsfil.
--preserve-unnecessary-suppressions

Bevarar onödiga undertryckningar när du återskapar undertryckningsfilen.

När en befintlig undertryckningsfil återskapas läses innehållet, deserialiseras till en uppsättning undertryckningar och lagras sedan i en lista. Vissa av undertryckningarna kanske inte längre är nödvändiga om inkompatibiliteten har åtgärdats. När undertryckningarna serialiseras tillbaka till disken kan du välja att behålla alla befintliga (deserialiserade) uttryck genom att ange det här alternativet.
--permit-unnecessary-suppressions

Tillåter onödiga undertryckningar i undertryckningsfilen.
--suppression-file <FILE>

Anger sökvägen till en eller flera undertryckningsfiler att läsa från.
--suppression-output-file <FILE>

Anger sökvägen till en undertryckningsfil som ska skrivas till när --generate-suppression-file har angetts. Om den är ospecificerad används den första --suppression-file sökvägen.
--noWarn <NOWARN_STRING>

Anger diagnostik-ID:t som ska utelämnas. Exempel: "$(NoWarn);PKV0001"
--respect-internals

Kontrollerar både internal och public API:er.
--roslyn-assemblies-path <FILE>

Anger sökvägen till katalogen som innehåller de Microsoft.CodeAnalysis-sammansättningar som du vill använda. Du behöver bara ange den här egenskapen om du vill testa med en nyare kompilator än vad som finns i SDK:n.
-v, --verbosity [high|low|normal]

Styr loggnivåns verbositet. Tillåtna värden är high, normaloch low. Standardvärdet är normal.
--enable-rule-cannot-change-parameter-name

Aktiverar regeln som kontrollerar om parameternamn har ändrats i offentliga metoder.
--enable-rule-attributes-must-match

Aktiverar regeln som kontrollerar om attributen matchar.
--exclude-attributes-file <FILE>

Anger sökvägen till en eller flera filer som innehåller attribut som ska undantas i DocId-format .

Sammansättningsspecifika alternativ

De här alternativen gäller endast när sammansättningar jämförs.

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

Anger sökvägen till en eller flera sammansättningar som fungerar som den vänstra sidan att jämföra. Det här alternativet krävs vid jämförelse av sammansättningar.
-r, --right, --right-assembly <PATH>

Anger sökvägen till en eller flera sammansättningar som fungerar som den högra sidan att jämföra. Det här alternativet krävs vid jämförelse av sammansättningar.
--strict-mode

Utför API-kompatibilitetskontroller i strikt läge.

Paketspecifika alternativ

De här alternativen gäller endast när paket jämförs.

--baseline-package

Anger sökvägen till ett baslinjepaket som det aktuella paketet ska verifieras mot.
--enable-strict-mode-for-compatible-tfms

Validerar API-kompatibilitet i strikt läge för kontrakts- och implementeringssammansättningar för alla kompatibla målramverk. Standardvärdet är true.
--enable-strict-mode-for-compatible-frameworks-in-package

Validerar API-kompatibilitet i strikt läge för sammansättningar som är kompatibla baserat på deras målramverk.
--enable-strict-mode-for-baseline-validation

Validerar API-kompatibilitet i strikt läge för paketbaslinjekontroller.
--package-assembly-references

Anger sökvägarna till sammansättningsreferenser eller deras underliggande kataloger för ett specifikt målramverk i paketet. Avgränsa flera värden med kommatecken.
--baseline-package-assembly-references

Anger sökvägarna till sammansättningsreferenser eller deras underliggande kataloger för ett specifikt målramverk i baslinjepaketet . Avgränsa flera värden med kommatecken.
--baseline-package-frameworks-to-ignore

Anger den uppsättning målramverk som ska ignoreras från baslinjepaketet. Ramverkssträngen måste exakt matcha mappnamnet i baslinjepaketet.

Exempel

Följande kommando jämför de aktuella versionerna och baslinjeversionerna av en sammansättning.

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

Följande kommando jämför de aktuella versionerna och baslinjeversionerna av ett paket.

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

I följande exempel visas kommandot för att jämföra de aktuella versionerna och baslinjeversionerna av en sammansättning, inklusive kontrollen av ändringar i parameternamnet. Exemplet visar också hur utdata kan se ut om ett parameternamn har ändrats.

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

Dela via