Weryfikowanie wersji pakietu bazowego

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

Walidacja pakietu wykrywa wszelkie zmiany powodujące niezgodność 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 powodujących niezgodność. Projekt należy skonfigurować tak, aby instruował narzędzia sprawdzania poprawności pakietów w celu uruchomienia kontroli zgodności interfejsu API względem 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ść źródła, jest to binarna zmiana 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)
{
    // ...
}

Teraz, gdy spakujesz projekt, zakończy się 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ę zmianę powodującą niezgodność.

<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 zamierzonej CP0002 zmiany powodującej niezgodność, możesz dodać plik CompatibilitySuppressions.xml do projektu. Plik pomijania można wygenerować automatycznie, wywołując raz dotnet pack /p:GenerateCompatibilitySuppressionFile=true . Plik zawiera pomijanie dla każdego błędu weryfikacji, który wystąpił podczas pakowania. Aby uzyskać więcej informacji, zobacz Jak pominąć.

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 zaewidencjonować w kontroli źródła, aby udokumentować i przejrzeć zmiany powodujące niezgodność wprowadzone w żądaniu ściągnięcia 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 w 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>