Microsoft.DotNet.ApiCompat.Tool globaal gereedschap

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 samenstelling met een basislijnsamenstelling.

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]

Opdrachten

• package | --package <PACKAGE_FILE>

  Valideert de compatibiliteit van pakket-assets. Als niet gespecificeerd, vergelijkt het hulpprogramma assemblages. <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 alleen assemblies 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 onderdrukking weer op schijf serieel wordt opgeslagen, kunt u ervoor kiezen 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 op om uit te lezen.

• --suppression-output-file <FILE>

  Hiermee geeft u het pad op naar een onderdrukkingsbestand om naar toe 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 internal als public 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 op naar een of meer bestanden die attributen bevatten die moeten worden uitgesloten in DocId-indeling.

Assembly-specifieke opties

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

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

  Hiermee geeft u het pad op naar een of meer assembly's die als de linkerkant dienen voor vergelijking. Deze optie is vereist bij het vergelijken van assembly's.

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

  Hiermee geeft u het pad op naar een of meer assembly's die als de rechterkant worden gebruikt bij de vergelijking. 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

  Specificeert het pad naar een referentie-pakket 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 specificeert u de paden naar assemblyverwijzingen of hun onderliggende directories voor een specifiek doelframework in het pakket. Scheid meerdere waarden met een komma.

• --baseline-package-assembly-references

  Hiermee specificeert u de paden naar assemblyverwijzingen of hun onderliggende mappen voor een specifiek doelframework in het basislijnpakket. Scheid meerdere waarden met een komma.

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

  Hiermee specificeert u de set doelframeworks die moeten worden genegeerd in het referentiepakket. 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.