通过

API 兼容性工具

  • 项目

跨平台兼容性已成为 .NET 库作者的主流要求。 但是，如果不使用工具来验证程序集和包，它们可能包含意外的中断性变更。 作为库作者，你需要确保多目标程序集兼容。 例如，对于同时以 .NET 6 和 .NET Standard 2.0 为目标的包，你必须确保针对 .NET Standard 2.0 二进制文件编译的代码可以针对 .NET 6 二进制文件运行。

如果使用该更改的源继续编译而无需更改，就可以认为该更改是安全且兼容的。 但是，如果未重新编译使用者，这些更改仍然会在运行时导致问题。 例如，向方法添加可选参数或更改常量的值可能会导致此类兼容性问题。

.NET SDK 提供了各种方法供你用来比较为不同目标框架生成的版本。 你还可以依据基线版本验证较新版本，以确保未引入中断性变更。 启用 MSBuild 任务，以在编译时验证程序集或在打包时验证包。 或者，使用 Microsoft.DotNet.ApiCompat.Tool 全局工具 在 MSBuild 外部进行验证。

有关包验证的详细信息，请参阅包验证。当应用无法打包时，应使用程序集验证。 有关程序集验证的详细信息，请参阅程序集验证。

注意

若要将程序集验证作为 MSBuild 任务运行，必须添加对 Microsoft.DotNet.ApiCompat.Task 的包引用。 同样，如果要测试 .NET SDK 中尚不可用的较新功能，你也可以添加对此包的引用。 例如，在使用 .NET 8 SDK 时，你可以引用 Microsoft.DotNet.ApiCompat.Task 包的 9.0.100-preview 版本。

严格模式

默认情况下，验证会执行兼容性检查。 但是，你也可以选择使用严格模式。 在严格模式下，验证会执行相等性检查。 等同的意思是未进行任何 API 添加或程序集更改（甚至是兼容性更改也没有）。

严格模式的用例包括：

  • 维护，其中通常禁止添加 API。
  • 用于跟踪 API 更改。 如果将 ApiCompatGenerateSuppressionFile 设置为 true，API 兼容性功能将在抑制文件中记录所有兼容性差异。

若要为命令行工具启用严格模式，请指定 --strict-mode 选项，或指定 --enable-strict* 选项中的一个。 若要为 MSBuild 任务启用严格模式，请将以下一个或多个 MSBuild 属性添加到项目文件：