Narzędzie globalne Microsoft.DotNet.ApiCompat.Tool

Artykuł
12/05/2023

Narzędzie Microsoft.DotNet.ApiCompat.Tool umożliwia przeprowadzanie kontroli zgodności interfejsu API poza programem MSBuild. Narzędzie ma dwa tryby:

Porównaj pakiet z pakietem odniesienia.
Porównaj zestaw z zestawem bazowym.

Instalowanie

Aby zainstalować narzędzie, uruchom następujące polecenie.

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

Aby uzyskać więcej informacji na temat instalowania narzędzi globalnych, zobacz Instalowanie narzędzia globalnego.

Użycie

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

— lub —

apicompat [command] [options]

Polecenia

package | --package <PACKAGE_FILE>

Sprawdza zgodność zasobów pakietu. Jeśli nie określono, narzędzie porównuje zestawy. <PACKAGE_FILE> określa ścieżkę do pliku pakietu.

Opcje

Niektóre opcje mają zastosowanie zarówno do weryfikacji zestawu, jak i pakietu. Inne dotyczą tylko zestawów lub tylko pakietów.

Opcje ogólne

--version

Wyświetla informacje o wersji.
--generate-suppression-file

Generuje plik pomijania zgodności.
--preserve-unnecessary-suppressions

Zachowuje niepotrzebne pomijania podczas ponownego generowania pliku pomijania.

Gdy istniejący plik pomijania jest ponownie wygenerowany, jego zawartość jest odczytywana, deserializowana w zestawie pomijań, a następnie przechowywana na liście. Niektóre pomijania mogą już nie być konieczne, jeśli niezgodność została naprawiona. Gdy pomijania są serializowane z powrotem na dysk, można zachować wszystkie istniejące (deserializowane) wyrażenia, określając tę opcję.
--permit-unnecessary-suppressions

Zezwala na niepotrzebne pomijanie w pliku pomijania.
--suppression-file <FILE>

Określa ścieżkę do co najmniej jednego pliku pomijania do odczytu.
--suppression-output-file <FILE>

Określa ścieżkę do pliku pomijania do zapisu, gdy --generate-suppression-file jest określony. Jeśli nie określono, zostanie użyta pierwsza --suppression-file ścieżka.
--noWarn <NOWARN_STRING>

Określa identyfikatory diagnostyczne do pomijania. Na przykład "$(NoWarn);PKV0001".
--respect-internals

Sprawdza interfejsy API i internalpublic .
--roslyn-assemblies-path <FILE>

Określa ścieżkę do katalogu zawierającego zestawy Microsoft.CodeAnalysis, których chcesz użyć. Tę właściwość należy ustawić tylko wtedy, gdy chcesz przetestować go przy użyciu nowszego kompilatora niż to, co znajduje się w zestawie SDK.
-v, --verbosity [high|low|normal]

Kontroluje szczegółowość na poziomie dziennika. Dozwolone wartości to high, normali low. Wartość domyślna to normal.
--enable-rule-cannot-change-parameter-name

Włącza regułę, która sprawdza, czy nazwy parametrów zostały zmienione w metodach publicznych.
--enable-rule-attributes-must-match

Włącza regułę, która sprawdza, czy atrybuty są zgodne.
--exclude-attributes-file <FILE>

Określa ścieżkę do co najmniej jednego pliku zawierającego atrybuty do wykluczenia w formacie DocId .

Opcje specyficzne dla zestawu

Te opcje mają zastosowanie tylko w przypadku porównywania zestawów.

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

Określa ścieżkę do co najmniej jednego zestawu, które służą jako lewa strona do porównania. Ta opcja jest wymagana podczas porównywania zestawów.
-r, --right, --right-assembly <PATH>

Określa ścieżkę do co najmniej jednego zestawu, które służą jako prawa strona do porównania. Ta opcja jest wymagana podczas porównywania zestawów.
--strict-mode

Wykonuje kontrole zgodności interfejsu API w trybie ścisłym.

Opcje specyficzne dla pakietu

Te opcje mają zastosowanie tylko w przypadku porównywania pakietów.

--baseline-package

Określa ścieżkę do pakietu bazowego w celu zweryfikowania bieżącego pakietu.
--enable-strict-mode-for-compatible-tfms

Sprawdza zgodność interfejsu API w trybie ścisłym dla zestawów kontraktów i implementacji dla wszystkich zgodnych platform docelowych. Wartość domyślna to true.
--enable-strict-mode-for-compatible-frameworks-in-package

Sprawdza zgodność interfejsu API w trybie ścisłym dla zestawów, które są zgodne na podstawie ich platformy docelowej.
--enable-strict-mode-for-baseline-validation

Sprawdza zgodność interfejsu API w trybie ścisłym na potrzeby sprawdzania punktu odniesienia pakietu.
--package-assembly-references

Określa ścieżki do odwołań do zestawów lub ich katalogów bazowych dla określonej platformy docelowej w pakiecie. Oddzielaj wiele wartości przecinkami.
--baseline-package-assembly-references

Określa ścieżki do odwołań do zestawów lub ich katalogów bazowych dla określonej platformy docelowej w pakiecie odniesienia . Oddzielaj wiele wartości przecinkami.
--baseline-package-frameworks-to-ignore

Określa zestaw platform docelowych do ignorowania z pakietu bazowego. Ciąg struktury musi dokładnie odpowiadać nazwie folderu w pakiecie odniesienia.

Przykłady

Następujące polecenie porównuje bieżące i bazowe wersje zestawu.

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

Następujące polecenie porównuje bieżące i bazowe wersje pakietu.

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

W poniższym przykładzie pokazano polecenie, aby porównać bieżące i bazowe wersje zestawu, w tym sprawdzanie zmian nazw parametrów. W przykładzie pokazano również, jak mogą wyglądać dane wyjściowe, jeśli nazwa parametru uległa zmianie.

>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