Udostępnij za pośrednictwem

Narzędzie globalne Microsoft.DotNet.ApiCompat.Tool

  • Artykuł

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.