Valideren op basis van een basislijnpakketversie

Met pakketvalidatie kunt u uw bibliotheekproject valideren op basis van een eerder uitgebrachte, stabiele versie van uw pakket. Als u pakketvalidatie wilt inschakelen, voegt u de PackageValidationBaselineVersion of PackageValidationBaselineName eigenschap toe aan uw projectbestand.

Pakketvalidatie detecteert eventuele destructieve wijzigingen in elk van de uitgeleverde doelframeworks. Ook wordt gedetecteerd of er ondersteuning voor het doelframework is verwijderd.

Bekijk bijvoorbeeld het volgende scenario. U werkt aan het NuGet-pakket AdventureWorks.Client en u wilt ervoor zorgen dat u niet per ongeluk wijzigingen aanbrengt die fouten veroorzaken. U configureert uw project voor het instrueren van hulpprogramma's voor pakketvalidatie om API-compatibiliteitscontroles uit te voeren op basis van de vorige versie van het pakket.

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

Een paar weken later bent u belast met de taak om uw bibliotheek te voorzien van ondersteuning voor een time-out van een verbinding. De Connect methode ziet er momenteel als volgt uit:

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

Aangezien een verbindingstime-out een geavanceerde configuratie-instelling is, kunt u alleen een optionele parameter toevoegen:

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

Wanneer u echter probeert te verpakken, treedt er een fout op.

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]

U realiseert dat hoewel dit geen bronbrekende wijziging is, het een binaire brekende wijziging is. U lost dit probleem op door een nieuwe overbelasting toe te voegen in plaats van een parameter toe te voegen aan de bestaande methode:

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

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

Nu u het project inpakt, slaagt het.

Voor versie 2.0.0 besluit u dat u de verouderde Connect methode met de enkele string parameter wilt verwijderen. Na zorgvuldige overweging besluit u deze ingrijpende verandering te accepteren.

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

Als u de CP0002-fout voor deze opzettelijke wijziging wilt onderdrukken, kunt u een CompatibilitySuppressions.xml-bestand toevoegen aan uw project. U kunt het onderdrukkingsbestand automatisch genereren door dotnet pack /p:GenerateCompatibilitySuppressionFile=true één keer aan te roepen. Het bestand bevat een onderdrukking voor elke validatiefout die is opgetreden tijdens het inpakken. Zie voor meer informatie Hoe te onderdrukken.

In dit voorbeeld bevat de CompatibilitySuppressions.xml de onderdrukking van de CP0002 fout:

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

Dit bestand moet worden opgenomen in het versiebeheersysteem om de brekende wijzigingen in een pull request en de aanstaande release te documenteren en te beoordelen.

Nadat u versie 2.0.0 van het pakket hebt uitgebracht, kunt u het CompatibilitySuppressions.xml bestand verwijderen en de PackageValidationBaselineVersion eigenschap bijwerken om toekomstige wijzigingen in de nieuwe release te valideren.

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