根据基线包版本进行验证

项目
12/06/2023

包验证可帮助你根据之前发布的稳定版包来验证库项目。若要启用包验证，请将 PackageValidationBaselineVersion 或 PackageValidationBaselineName 属性添加到项目文件。

包验证可检测针对任何已发布的目标框架的任何中断性变更。它还会检测是否已删除任何目标框架支持。

例如，考虑以下情况。你正在处理 AdventureWorks.Client NuGet 包，并且想要确保不会意外进行中断性变更。你将项目配置为指示包验证工具针对早期版本的包运行 API 兼容性检查。

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

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <PackageVersion>1.1.0</PackageVersion>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>1.0.0</PackageValidationBaselineVersion>
  </PropertyGroup>

</Project>

几周后，你的任务是为库添加对连接超时的支持。 Connect 方法目前如下所示：

public static HttpClient Connect(string url)
{
    // ...
}

由于连接超时是一个高级配置设置，因此你认为可以添加一个可选参数：

public static HttpClient Connect(string url, TimeSpan timeout = default)
{
    // ...
}

但是，当你尝试打包时，它将引发错误。

D:\demo>dotnet pack
MSBuild version 17.3.2+561848881 for .NET
  Determining projects to restore...
  All projects are up-to-date for restore.
  AdventureWorks.Client -> D:\demo\bin\Debug\net6.0\AdventureWorks.Client.dll
C:\Program Files\dotnet\sdk\6.0.413\Sdks\Microsoft.NET.Sdk\targets\Microsoft.NET.Compatibility.Common.targets(33,5): error CP0002: Member 'A.B.Connect(string)' exists on [Baseline] lib/net6.0/AdventureWorks.Client.dll but not on lib/net6.0/AdventureWorks.Client.dll [D:\demo\AdventureWorks.Client.csproj]

BaselineVersion

你发现虽然这不是源中断性变更，但它是二进制中断性变更。通过添加新的重载（而不是向现有方法添加参数）即可解决此问题：

public static HttpClient Connect(string url)
{
    return Connect(url, Timeout.InfiniteTimeSpan);
}

public static HttpClient Connect(string url, TimeSpan timeout)
{
    // ...
}

现在当你打包项目时，它就会成功。

BaselineVersionSuccessful

对于版本 2.0.0，你决定要删除具有单个 string 参数的过时 Connect 方法。仔细考虑后，你决定接受此中断性变更。

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

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <PackageVersion>2.0.0</PackageVersion>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>1.1.0</PackageValidationBaselineVersion>
  </PropertyGroup>

</Project>

- public static HttpClient Connect(string url)
- {
-     return Connect(url, Timeout.InfiniteTimeSpan);
- }

public static HttpClient Connect(string url, TimeSpan timeout)
{
    // ...
}

若要抑制此有意中断性变更的 CP0002 错误，可以将 CompatibilitySuppressions.xml 文件添加到项目中。可通过调用 dotnet pack /p:GenerateCompatibilitySuppressionFile=true 一次来自动生成抑制文件。该文件包含打包期间发生的每个验证错误的抑制。有关详细信息，请参阅如何抑制。

在此示例中，CompatibilitySuppressions.xml 包含 CP0002 错误的抑制：

<?xml version="1.0" encoding="utf-8"?>
<Suppressions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <Suppression>
    <DiagnosticId>CP0002</DiagnosticId>
    <Target>M:A.B.Connect(System.String)</Target>
    <Left>lib/net6.0/AdventureWorks.Client.dll</Left>
    <Right>lib/net6.0/AdventureWorks.Client.dll</Right>
    <IsBaselineSuppression>true</IsBaselineSuppression>
  </Suppression>
</Suppressions>

应将此文件签入源代码管理，以记录和查看 PR 和即将发布的版本中所做的中断性变更。

发布包版本 2.0.0 后，可删除 CompatibilitySuppressions.xml 文件并更新 PackageValidationBaselineVersion 属性，以验证新版本的未来更改。

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

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <PackageVersion>2.1.0</PackageVersion>
    <EnablePackageValidation>true</EnablePackageValidation>
    <PackageValidationBaselineVersion>2.0.0</PackageValidationBaselineVersion>
  </PropertyGroup>

</Project>

通过

根据基线包版本进行验证

其他资源