Zweryfikuj z wersją pakietu wzorcowego

Walidacja pakietu może pomóc w zweryfikowaniu projektu biblioteki względem wcześniej wydanej, stabilnej wersji pakietu. Aby włączyć walidację pakietu, dodaj właściwość PackageValidationBaselineVersion lub PackageValidationBaselineName do pliku projektu.

Walidacja pakietu wykrywa wszelkie zmiany powodujące niekompatybilność w dowolnej z dostarczonych platform docelowych. Wykrywa również, czy obsługa platformy docelowej została porzucona.

Rozważmy na przykład następujący scenariusz. Pracujesz nad pakietem NuGet AdventureWorks.Client i chcesz upewnić się, że nie wprowadzasz przypadkowo zmian, które mogłyby spowodować błędy zgodności. Projekt należy skonfigurować tak, aby narzędzia sprawdzania poprawności pakietu wykonywały kontrole zgodności API w porównaniu do poprzedniej wersji pakietu.

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

Kilka tygodni później masz zadanie dodania obsługi przekroczenia limitu czasu połączenia do biblioteki. Metoda Connect obecnie wygląda następująco:

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

Ponieważ limit czasu połączenia jest zaawansowanym ustawieniem konfiguracji, można po prostu dodać opcjonalny parametr:

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

Jednak podczas próby spakowania zgłasza błąd.

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]

Zdajesz sobie sprawę, że chociaż nie jest to zmiana powodująca niezgodność z kodem źródłowym, to jednak jest to zmiana binarna powodująca niezgodność. Ten problem można rozwiązać, dodając nowe przeciążenie zamiast dodawania parametru do istniejącej metody:

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

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

Gdy teraz spakujesz projekt, zakończy się on powodzeniem.

W przypadku wersji 2.0.0 decydujesz, że chcesz usunąć przestarzałą Connect metodę z pojedynczym string parametrem. Po starannym rozważeniu decydujesz się zaakceptować tę niekompatybilną zmianę.

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

Aby pominąć błąd dla tej celowej zmiany łamiącej zgodność, możesz dodać plik CP0002 do projektu. Plik tłumienia można wygenerować automatycznie, wywołując dotnet pack /p:GenerateCompatibilitySuppressionFile=true raz. Plik zawiera pomijanie dla każdego błędu weryfikacji, który wystąpił podczas pakowania. Aby uzyskać więcej informacji, zapoznaj się z Jak stłumić.

W tym przykładzie CompatibilitySuppressions.xml zawiera pomijanie błędu 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>

Ten plik należy przekazać do kontroli wersji, aby udokumentować i przejrzeć zmiany wprowadzające niezgodności wprowadzone w PR i nadchodzącej wersji.

Po wydaniu pakietu w wersji 2.0.0 możesz usunąć plik CompatibilitySuppressions.xml i zaktualizować PackageValidationBaselineVersion właściwość, aby zweryfikować przyszłe zmiany względem nowej wersji.

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