根據基準套件版本來進行驗證

發行項
03/12/2024

套件驗證可以幫助您根據先前發佈的穩定套件版本來驗證您的程式庫專案。若要啟用套件驗證，請將 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>

共用方式為

根據基準套件版本來進行驗證

其他資源