ベースライン パッケージ バージョンに対して検証する
パッケージ検証は、以前にリリースされた安定したバージョンのパッケージに対してライブラリ プロジェクトを検証するのに役立ちます。 パッケージ検証を有効にするには、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]
これはソースの破壊的変更ではありませんが、バイナリの破壊的変更であることがわかりました。 この問題を解決するために、既存のメソッドにパラメーターを追加するのではなく、新しいオーバーロードを追加しました。
public static HttpClient Connect(string url)
{
return Connect(url, Timeout.InfiniteTimeSpan);
}
public static HttpClient Connect(string url, TimeSpan timeout)
{
// ...
}
プロジェクトをパッキングすると、成功しました。
バージョン 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>
.NET