Microsoft.DotNet.ApiCompat.Tool global tool

Artikel
12/05/2023

Met het hulpprogramma Microsoft.DotNet.ApiCompat.Tool kunt u API-compatibiliteitscontroles uitvoeren buiten MSBuild. Het hulpprogramma heeft twee modi:

Vergelijk een pakket met een basislijnpakket.
Vergelijk een assembly met een basislijnassembly.

Installeren

Voer de volgende opdracht uit om het hulpprogramma te installeren.

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

Zie Een algemeen hulpprogramma installeren voor meer informatie over het installeren van globale hulpprogramma's.

Gebruik

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

– of –

apicompat [command] [options]

Opdracht

package | --package <PACKAGE_FILE>

Valideert de compatibiliteit van pakketassets. Als dit niet is opgegeven, vergelijkt het hulpprogramma assembly's. <PACKAGE_FILE> hiermee geeft u het pad naar het pakketbestand.

Opties

Sommige opties zijn van toepassing op zowel assembly- als pakketvalidatie. Andere zijn alleen van toepassing op assembly's of alleen pakketten.

Algemene opties

--version

Geeft versiegegevens weer.
--generate-suppression-file

Hiermee wordt een compatibiliteitsonderdrukkingsbestand gegenereerd.
--preserve-unnecessary-suppressions

Bewaart onnodige onderdrukkingen bij het regenereren van het onderdrukkingsbestand.

Wanneer een bestaand onderdrukkingsbestand opnieuw wordt gegenereerd, wordt de inhoud ervan gelezen, gedeserialiseerd in een set onderdrukkingen en vervolgens opgeslagen in een lijst. Sommige onderdrukkingen zijn mogelijk niet meer nodig als de incompatibiliteit is opgelost. Wanneer de onderdrukkingen terug naar schijf worden geserialiseerd, kunt u ervoor kiezen om alle bestaande (gedeserialiseerde) expressies te behouden door deze optie op te geven.
--permit-unnecessary-suppressions

Maakt onnodige onderdrukkingen in het onderdrukkingsbestand mogelijk.
--suppression-file <FILE>

Hiermee geeft u het pad naar een of meer onderdrukkingsbestanden waaruit moet worden gelezen.
--suppression-output-file <FILE>

Hiermee geeft u het pad naar een onderdrukkingsbestand om naar te schrijven wanneer --generate-suppression-file is opgegeven. Als dit niet is opgegeven, wordt het eerste --suppression-file pad gebruikt.
--noWarn <NOWARN_STRING>

Hiermee geeft u de diagnostische id's die moeten worden onderdrukt. Bijvoorbeeld "$(NoWarn);PKV0001".
--respect-internals

Controleert zowel internalpublic als API's.
--roslyn-assemblies-path <FILE>

Hiermee geeft u het pad naar de map die de Microsoft.CodeAnalysis-assembly's bevat die u wilt gebruiken. U hoeft deze eigenschap alleen in te stellen als u wilt testen met een nieuwere compiler dan wat zich in de SDK bevindt.
-v, --verbosity [high|low|normal]

Hiermee bepaalt u de uitgebreidheid van het logboekniveau. Toegestane waarden zijn high, normalen low. De standaardwaarde is normal.
--enable-rule-cannot-change-parameter-name

Hiermee schakelt u de regel in waarmee wordt gecontroleerd of parameternamen zijn gewijzigd in openbare methoden.
--enable-rule-attributes-must-match

Hiermee schakelt u de regel in waarmee wordt gecontroleerd of kenmerken overeenkomen.
--exclude-attributes-file <FILE>

Hiermee geeft u het pad naar een of meer bestanden die kenmerken bevatten die moeten worden uitgesloten in DocId-indeling .

Assemblyspecifieke opties

Deze opties zijn alleen van toepassing wanneer assembly's worden vergeleken.

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

Hiermee geeft u het pad naar een of meer assembly's die dienen als de linkerkant om te vergelijken. Deze optie is vereist bij het vergelijken van assembly's.
-r, --right, --right-assembly <PATH>

Hiermee geeft u het pad naar een of meer assembly's die als de rechterkant dienen om te vergelijken. Deze optie is vereist bij het vergelijken van assembly's.
--strict-mode

Voert API-compatibiliteitscontroles uit in de strikte modus.

Pakketspecifieke opties

Deze opties zijn alleen van toepassing wanneer pakketten worden vergeleken.

--baseline-package

Hiermee geeft u het pad naar een basislijnpakket om het huidige pakket te valideren.
--enable-strict-mode-for-compatible-tfms

Valideert API-compatibiliteit in strikte modus voor contract- en implementatieassembly's voor alle compatibele doelframeworks. De standaardwaarde is true.
--enable-strict-mode-for-compatible-frameworks-in-package

Valideert API-compatibiliteit in strikte modus voor assembly's die compatibel zijn op basis van hun doelframework.
--enable-strict-mode-for-baseline-validation

Valideert API-compatibiliteit in de strikte modus voor pakketbasislijncontroles.
--package-assembly-references

Hiermee geeft u de paden naar assemblyverwijzingen of de onderliggende mappen voor een specifiek doelframework in het pakket. Scheid meerdere waarden met een komma.
--baseline-package-assembly-references

Hiermee geeft u de paden naar assemblyverwijzingen of de onderliggende mappen voor een specifiek doelframework in het basislijnpakket op. Scheid meerdere waarden met een komma.
--baseline-package-frameworks-to-ignore

Hiermee geeft u de set doelframeworks die moeten worden genegeerd uit het basislijnpakket. De frameworktekenreeks moet exact overeenkomen met de mapnaam in het basislijnpakket.

Voorbeelden

Met de volgende opdracht worden de huidige en basislijnversies van een assembly vergeleken.

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

Met de volgende opdracht worden de huidige en basislijnversies van een pakket vergeleken.

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

In het volgende voorbeeld ziet u de opdracht om de huidige en basislijnversies van een assembly te vergelijken, inclusief de controle op wijzigingen in de parameternaam. In het voorbeeld ziet u ook hoe de uitvoer eruit kan zien als een parameternaam is gewijzigd.

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

Delen via