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

パッケージ検証は、以前にリリースされた安定したバージョンのパッケージに対してライブラリ プロジェクトを検証するのに役立ちます。 パッケージ検証を有効にするには、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 では、1 つの 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>