Инструмент совместимости API Microsoft.DotNet.ApiCompat.Tool

Средство Microsoft.DotNet.ApiCompat.Tool позволяет выполнять проверки совместимости API за пределами MSBuild. Средство имеет два режима:

  • Сравните пакет с базовым пакетом.
  • Сравните сборку с базовой сборкой.

Установка

Чтобы установить средство, выполните следующую команду.

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

Дополнительные сведения об установке глобальных средств см. в разделе "Установка глобального средства".

Использование

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

-или-

apicompat [command] [options]

Команды

  • package | --package <PACKAGE_FILE>

    Проверяет совместимость ресурсов пакета. Если не указано, средство сравнивает сборки. <PACKAGE_FILE> указывает путь к файлу пакета.

Опции

Некоторые параметры применяются как к проверке сборки, так и к проверке пакета. Другие применяются только к сборкам или только к пакетам.

Общие параметры

  • --version

    Отображает сведения о версии.

  • --generate-suppression-file

    Создает файл подавления совместимости.

  • --preserve-unnecessary-suppressions

    Сохраняет ненужные подавления при повторном создании файла подавления.

    При повторном создании существующего файла подавления его содержимое считывается, десериализуется в набор подавлений, а затем сохраняется в списке. Некоторые из подавлений могут больше не потребоваться, если несовместимость была исправлена. Когда данные подавления сериализуются обратно на диск, можно сохранить все существующие (десериализированные) выражения, указав этот параметр.

  • --permit-unnecessary-suppressions

    Разрешает ненужные подавления в файле подавления.

  • --suppression-file <FILE>

    Указывает путь к одному или нескольким файлам подавления для чтения.

  • --suppression-output-file <FILE>

    Указывает путь к файлу подавления, в который будет записано при указании --generate-suppression-file. Если не указано, используется первый --suppression-file путь.

  • --noWarn <NOWARN_STRING>

    Указывает диагностические идентификаторы, которые следует подавлять. Например: "$(NoWarn);PKV0001".

  • --respect-internals

    Проверяет оба internal и public API.

  • --roslyn-assemblies-path <FILE>

    Указывает путь к каталогу, который содержит сборки Microsoft.CodeAnalysis, которые вы хотите использовать. Это свойство необходимо задать только в том случае, если вы хотите протестировать с помощью более нового компилятора, чем то, что находится в пакете SDK.

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

    Управляет степенью детализации логов. Допустимые значения: high, normalи low. Значение по умолчанию — normal.

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

    Включает правило, которое проверяет, изменились ли имена параметров в общедоступных методах.

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

    Включает правило, которое проверяет соответствие атрибутов.

  • --exclude-attributes-file <FILE>

    Указывает путь к одному или нескольким файлам, содержащим атрибуты, которые следует исключить в формате DocId .

Параметры для конкретной сборки

Эти параметры применимы только при сравнении сборок.

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

    Указывает путь к одной или нескольким сборкам, которые служат левой стороной для сравнения. Этот параметр необходим при сравнении сборок.

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

    Указывает путь к одной или нескольким сборкам, которые служат правой стороной для сравнения. Этот параметр необходим при сравнении сборок.

  • --strict-mode

    Выполняет проверки совместимости API в строгом режиме.

Параметры для конкретного пакета

Эти параметры применимы только при сравнении пакетов.

  • --baseline-package

    Задает путь к эталонному пакету, чтобы сравнить и проверить текущий пакет по отношению к нему.

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

    Проверяет совместимость API в строгом режиме для сборок контракта и реализации для всех совместимых целевых фреймворков. Значение по умолчанию — true.

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

    Проверяет совместимость API в строгом режиме для сборок, совместимых с целевой платформой.

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

    Проверяет совместимость API в строгом режиме для проверок базовых пакетов.

  • --package-assembly-references

    Указывает пути к ссылкам на сборки или их базовые каталоги для конкретной целевой платформы в пакете. Разделите несколько значений с запятыми.

  • --baseline-package-assembly-references

    Задает пути к ссылкам на сборки или их базовые каталоги для конкретной целевой платформы в базовом пакете. Разделите несколько значений с запятыми.

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

    Задает набор целевых фреймворков для исключения из базового пакета. Строка платформы должна точно соответствовать имени папки в базовом пакете.

Примеры

Следующая команда сравнивает текущие и базовые версии сборки.

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

Следующая команда сравнивает текущие и базовые версии пакета.

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

В следующем примере показана команда для сравнения текущих и базовых версий сборки, включая проверку изменений имени параметра. В примере также показано, что выходные данные могут выглядеть, если имя параметра изменилось.

>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.
  • Last updated on