次の方法で共有

ベースライン パッケージのバージョンに対して検証する

パッケージの検証は、以前にリリースされた安定したバージョンのパッケージに対してライブラリ プロジェクトを検証するのに役立ちます。 パッケージの検証を有効にするには、プロジェクト ファイルに 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を 1 回呼び出すと、抑制ファイルを自動的に生成できます。 ファイルには、パック中に発生した検証エラーごとに抑制が含まれています。 詳細については、「 抑制する方法」を参照してください。

この例では、 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>