Глобальное средство Microsoft.DotNet.ApiCompat.Tool

Статья
12/05/2023

Средство 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.

Поделиться через