共用方式為

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

套件驗證可以幫助您將程式庫專案與先前發行且穩定版本的套件進行驗證。 若要啟用套件驗證，請將 `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)
{
    // ...
}

現在當您打包專案時，它會成功。

基準版本成功

針對 2.0.0 版，您決定要移除具有單一Connect參數的過時string方法。 仔細考慮之後，您決定接受這項重大變更。

<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>

小提示

除了刪除 CompatibilitySuppressions.xml 檔案之外，您也可以考慮設定 ApiCompatPreserveUnnecessarySuppressions 等屬性。

  • Last updated on