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 belangrijke wijzigingen in een van de verzonden 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 krijgt u de taak om ondersteuning voor een time-out voor een verbinding aan uw bibliotheek toe te voegen. 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 in te pakken, 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 zich dat hoewel dit geen bronverbrekingswijziging is, het een binaire wijziging die fouten optreedt. 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)
{
    // ...
}

Wanneer 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 wijziging die fouten veroorzaken 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 één keer aan te roepen dotnet pack /p:GenerateCompatibilitySuppressionFile=true . Het bestand bevat een onderdrukking voor elke validatiefout die is opgetreden tijdens het inpakken. Zie Onderdrukken voor meer informatie.

In dit voorbeeld bevat de CompatibilitySuppressions.xml de onderdrukking voor 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 ingecheckt bij broncodebeheer om de belangrijke wijzigingen in een pull-aanvraag en de aanstaande release te bekijken.

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>