Globales Tool „Microsoft.DotNet.ApiCompat.Tool“

Mit dem Tool "Microsoft.DotNet.ApiCompat.Tool" können Sie API-Kompatibilitätsprüfungen außerhalb von MSBuild durchführen. Das Tool verfügt über zwei Modi:

• Vergleichen Sie ein Paket mit einem Basispaket.
• Vergleichen Sie eine Baugruppe mit einer Referenzbaugruppe.

Installieren

Führen Sie zum Installieren des Tools den folgenden Befehl aus.

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

Weitere Informationen zum Installieren globaler Tools finden Sie unter Installieren eines globalen Tools.

Verwendung

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

-oder-

apicompat [command] [options]

Befehle

• package | --package <PACKAGE_FILE>

  Überprüft die Kompatibilität von Paketressourcen. Wenn nicht angegeben, vergleicht das Tool Assemblys. <PACKAGE_FILE> Gibt den Pfad zur Paketdatei an.

Optionen

Einige Optionen gelten sowohl für die Assembly- als auch für die Paketüberprüfung. Andere gelten nur für Assemblys oder nur für Pakete.

Allgemeine Optionen

• --version

  Zeigt Versionsinformationen an.

• --generate-suppression-file

  Generiert eine Kompatibilitätsunterdrückungsdatei.

• --preserve-unnecessary-suppressions

  Behält beim erneuten Generieren der Unterdrückungsdatei unnötige Unterdrückungen bei.

  Wenn eine vorhandene Unterdrückungsdatei neu generiert wird, wird der Inhalt gelesen, in eine Reihe von Unterdrückungen deserialisiert und dann in einer Liste gespeichert. Einige der Unterdrückungen sind möglicherweise nicht mehr erforderlich, wenn die Inkompatibilität behoben wurde. Wenn die Unterdrückungen wieder auf den Datenträger serialisiert werden, können Sie auswählen, dass alle vorhandenen (deserialisierten) Ausdrücke beibehalten werden, indem Sie diese Option angeben.

• --permit-unnecessary-suppressions

  Erlaubt unnötige Unterdrückungen in der Unterdrückungsdatei.

• --suppression-file <FILE>

  Gibt den Pfad zu einer oder mehreren Unterdrückungsdateien an, aus der gelesen werden soll.

• --suppression-output-file <FILE>

  Gibt den Pfad zu einer Unterdrückungsdatei an, in die geschrieben werden soll, wenn --generate-suppression-file angegeben ist. Wenn nicht angegeben, wird der erste --suppression-file Pfad verwendet.

• --noWarn <NOWARN_STRING>

  Gibt die zu unterdrückenden Diagnose-IDs an. Beispiel: "$(NoWarn);PKV0001".

• --respect-internals

  Überprüft sowohl internal als auch public APIs.

• --roslyn-assemblies-path <FILE>

  Gibt den Pfad zum Verzeichnis an, das die microsoft.CodeAnalysis-Assemblys enthält, die Sie verwenden möchten. Sie müssen diese Eigenschaft nur festlegen, wenn Sie zum Testen einen neueren Compiler als den verwenden möchten, der im SDK enthalten ist.

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

  Steuert die Ausführlichkeit der Protokollebene. Zulässige Werte sind high, normalund low. Der Standardwert lautet normal.

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

  Aktiviert die Regel, die überprüft, ob Parameternamen in öffentlichen Methoden geändert wurden.

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

  Aktiviert die Regel, die überprüft, ob Attribute übereinstimmen.

• --exclude-attributes-file <FILE>

  Gibt den Pfad zu einer oder mehreren Dateien an, die Attribute enthalten, die im DocId-Format ausgeschlossen werden sollen.

Assemblyspezifische Optionen

Diese Optionen gelten nur, wenn Zusammenstellungen verglichen werden.

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

  Gibt den Pfad zu einer oder mehreren Assemblys an, die als linke Seite zum Vergleichen dienen. Diese Option ist beim Vergleichen von Assemblys erforderlich.

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

  Gibt den Pfad zu einer oder mehreren Assemblys an, die als rechte Seite zum Vergleichen dienen. Diese Option ist beim Vergleichen von Assemblys erforderlich.

• --strict-mode

  Führt API-Kompatibilitätsprüfungen im strikten Modus aus.

Paketspezifische Optionen

Diese Optionen gelten nur, wenn Pakete verglichen werden.

• --baseline-package

  Gibt den Pfad zu einem Basispaket an, mit dem das aktuelle Paket überprüft werden soll.

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

  Überprüft die API-Kompatibilität im strikten Modus für Vertrags- und Implementierungsassemblys für alle kompatiblen Zielframeworks. Der Standardwert lautet true.

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

  Überprüft die API-Kompatibilität im strikten Modus für Assemblys, die basierend auf ihrem Zielframework kompatibel sind.

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

  Überprüft die API-Kompatibilität im strikten Modus für Paketbasisplanüberprüfungen.

• --package-assembly-references

  Gibt die Pfade für Assemblyverweise oder deren zugrunde liegende Verzeichnisse für ein bestimmtes Zielframework im Paket an. Trennen Sie mehrere Werte durch ein Komma.

• --baseline-package-assembly-references

  Gibt die Pfade zu Assemblyverweisen oder deren zugrunde liegenden Verzeichnissen für ein bestimmtes Ziel-Framework im Basispaket an. Trennen Sie mehrere Werte durch ein Komma.

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

  Gibt den Satz von Zielframeworks an, die vom Basispaket ignoriert werden sollen. Die Frameworkzeichenfolge muss exakt mit dem Ordnernamen im Basispaket übereinstimmen.

Beispiele

Der folgende Befehl vergleicht die aktuellen und Basislinienversionen einer Assembly.

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

Mit dem folgenden Befehl werden die aktuellen und die Basislinienversionen eines Pakets verglichen.

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

Das folgende Beispiel zeigt den Befehl zum Vergleichen der aktuellen und Basislinienversionen einer Assembly, einschließlich der Überprüfung auf Parameternamenänderungen. Das Beispiel zeigt auch, wie die Ausgabe aussehen könnte, wenn sich ein Parametername geändert hat.

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