Globales Tool „Microsoft.DotNet.ApiCompat.Tool“

Artikel
12/13/2023

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 eines Pakets mit einem Basispaket.
Vergleichen einer Assembly mit einer Basisassembly.

Installieren

Führen Sie den folgenden Befehl aus, um das Tool zu installieren.

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 dem 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/denen 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. Ohne Angabe wird der erste --suppression-file-Pfad verwendet.
--noWarn <NOWARN_STRING>

Gibt die zu unterdrückenden Diagnose-IDs an. Beispielsweise "$(NoWarn);PKV0001".
--respect-internals

Überprüft sowohl die internal-API als auch die publicAPI.
--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, normal und low. Der Standardwert ist 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 Dateien an, die auszuschließende Attribute im Format DocId enthalten.

Assemblyspezifische Optionen

Diese Optionen gelten nur, wenn Assemblys 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 Strict-Modus aus.

Paketspezifische Optionen

Diese Optionen gelten nur, wenn Pakete verglichen werden.

--baseline-package

Gibt den Pfad zu einem Basispaket an, anhand dessen das aktuelle Paket überprüft werden soll.
--enable-strict-mode-for-compatible-tfms

Überprüft die API-Kompatibilität im Strict-Modus für Vertrags- und Implementierungsassemblys für alle kompatiblen Zielframeworks. Der Standardwert ist true.
--enable-strict-mode-for-compatible-frameworks-in-package

Überprüft die API-Kompatibilität im Strict-Modus für Assemblys, die basierend auf ihrem Zielframework kompatibel sind.
--enable-strict-mode-for-baseline-validation

Überprüft die API-Kompatibilität im Strict-Modus für Paketbasisü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 für Assemblyverweise oder deren zugrunde liegende Verzeichnisse für ein bestimmtes Zielframework 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

Mit dem folgenden Befehl werden die aktuellen und die Basisversionen einer Assembly verglichen.

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 Basisversionen 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 Versionen und der Basisversionen einer Assembly, einschließlich der Überprüfung auf Änderungen der Parameternamen. 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.

Share via