Microsoft.DotNet.ApiCompat.Tool 全局工具

项目
12/13/2023

Microsoft.DotNet.ApiCompat.Tool 工具支持你在 MSBuild 外部执行 API 兼容性检查。该工具有两种模式：

将包与基线包进行比较。
将程序集与基线程序集进行比较。

安装

要安装该工具，请运行以下命令。

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>

指定要抑制的诊断 ID。例如 "$(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.

通过

Microsoft.DotNet.ApiCompat.Tool 全局工具

安装

使用情况

命令

选项

常规选项

特定于程序集的选项

特定于包的选项

示例

其他资源