Share via

程序集验证

  • 项目

与包验证类似，程序集验证工具支持你以库开发人员身份来验证程序集是否一致且格式良好。 当应用无法打包时，请使用程序集验证而不是包验证。

程序集验证提供以下检查：

  • 验证各个版本之间是否存在中断性变更。
  • 针对所有不同的运行时特定的实现，验证程序集是否具有一组相同的公共 API。
  • 捕获任何适用性缺口。

可以将程序集验证作为 MSBuild 任务运行，也可以使用 Microsoft.DotNet.ApiCompat.Tool 全局工具运行程序集验证。

启用 MSBuild 任务

可以通过将 ApiCompatValidateAssemblies 属性设置为 true 并指定协定（基线）程序集的路径，在 .NET 项目中启用程序集验证。 还必须添加对 Microsoft.DotNet.ApiCompat.Task的包引用。 （该包中的 targets 文件不是 .NET SDK 的一部分。）

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>net8.0</TargetFrameworks>
    <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
    <ApiCompatContractAssembly>[Path to contract assembly]</ApiCompatContractAssembly>
    <IsPackable>false</IsPackable>
  </PropertyGroup>

  <ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
    <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
  </ItemGroup>

</Project>

程序集验证可在多目标项目的外部生成中运行（在 DispatchToInnerBuilds 目标之后），也可以在单目标项目在内部生成中运行（作为 PrepareForRun 目标的一部分）。 它也是完全增量的，这意味着仅当输入和输出发生更改时才会触发比较。

示例

  1. 创建并构建一个名为“ValidateMe”的 C# 类库，其中包含以下简单接口：

    namespace ValidateMe;

public interface IAnimal
{
    string Name { get; }
    //string Sound { get; }
}

  2. 将输出程序集重命名为“ValidateMeV1.dll”。

  3. 通过取消评论该代码行，为接口添加 Sound 属性。

  4. 将 ApiCompatValidateAssemblies 和 ApiCompatContractAssembly 属性和“Microsoft.DotNet.ApiCompat.Task”包引用添加到项目文件。 此外，将程序集的版本提升为“2.0.0”。

    <PropertyGroup>
  <OutputType>Library</OutputType>
  <TargetFrameworks>net8.0</TargetFrameworks>
  <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
  <ApiCompatContractAssembly>$(OutDir)bin\Release\net8.0\ValidateMeV1.dll</ApiCompatContractAssembly>
  <IsPackable>false</IsPackable>
  <Version>2.0.0</Version>
</PropertyGroup>

<ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
   <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
</ItemGroup>

  5. 重新生成类库。

    生成失败并出现以下错误：

    C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API compatibility errors between 'bin\Release\net8.0\ValidateMeV1.dll' (left) and 'C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll' (right):
1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error CP0006: Cannot add interface member 'string ValidateMe.IAnimal.Sound' to C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll because it does not exist on bin\Release\net8.0\ValidateMeV1.dll
1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API breaking changes found. If those are intentional, the APICompat suppression file can be updated by rebuilding with '/p:ApiCompatGenerateSuppressionFile=true'

抑制兼容性警告

有关抑制兼容性警告的信息，请参阅如何抑制。