Verifiera mot en baslinjepaketversion

Med paketverifiering kan du verifiera biblioteksprojektet mot en tidigare utgiven, stabil version av paketet. Om du vill aktivera paketverifiering lägger du till PackageValidationBaselineVersion egenskapen eller PackageValidationBaselineName i projektfilen.

Paketverifiering identifierar eventuella icke-bakåtkompatibla ändringar i något av de levererade målramverken. Den identifierar också om något stöd för målramverket har tagits bort.

Tänk dig till exempel följande scenario. Du arbetar med NuGet-paketet AdventureWorks.Client och vill se till att du inte oavsiktligt gör icke-bakåtkompatibla ändringar. Du konfigurerar projektet för att instruera paketverifieringsverktyg att köra API-kompatibilitetskontroller mot den tidigare versionen av paketet.

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

Några veckor senare får du i uppgift att lägga till stöd för en tidsgräns för anslutning till biblioteket. Metoden Connect ser för närvarande ut så här:

public static HttpClient Connect(string url)
{
    // ...
}

Eftersom en tidsgräns för anslutning är en avancerad konfigurationsinställning räknar du med att du bara kan lägga till en valfri parameter:

public static HttpClient Connect(string url, TimeSpan timeout = default)
{
    // ...
}

Men när du försöker packa genererar det ett fel.

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]

Du inser att även om detta inte är en källbrytande ändring är det en binär icke-bakåtkompatibel ändring. Du löser det här problemet genom att lägga till en ny överlagring i stället för att lägga till en parameter i den befintliga metoden:

public static HttpClient Connect(string url)
{
    return Connect(url, Timeout.InfiniteTimeSpan);
}

public static HttpClient Connect(string url, TimeSpan timeout)
{
    // ...
}

Nu när du packar projektet lyckas det.

För version 2.0.0 bestämmer du dig för att ta bort den föråldrade Connect metoden som har den enda string parametern. Efter noggrant övervägande bestämmer du dig för att acceptera den här icke-bakåtkompatibla ändringen.

<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)
{
    // ...
}

Om du vill förhindra felet för den CP0002 här avsiktliga icke-bakåtkompatibla ändringen kan du lägga till en CompatibilitySuppressions.xml fil i projektet. Du kan generera undertryckningsfilen automatiskt genom att anropa dotnet pack /p:GenerateCompatibilitySuppressionFile=true en gång. Filen innehåller en undertryckning för varje valideringsfel som inträffade under paketet. Mer information finns i Så här undertrycker du.

I det här exemplet innehåller CompatibilitySuppressions.xml undertryckningen för CP0002 felet:

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

Den här filen bör checkas in i källkontrollen för att dokumentera och granska de icke-bakåtkompatibla ändringarna som gjorts i en PR och den kommande versionen.

När du har släppt version 2.0.0 av paketet kan du ta bort CompatibilitySuppressions.xml-filen och uppdatera PackageValidationBaselineVersion egenskapen för att verifiera framtida ändringar mot den nya versionen.

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