Überprüfen anhand einer Baselinepaketversion

Mithilfe der Paketüberprüfung können Sie Ihr Bibliotheksprojekt anhand einer zuvor veröffentlichten, stabilen Version Ihres Pakets überprüfen. Um die Paketüberprüfung zu aktivieren, fügen Sie der Projektdatei die Eigenschaft PackageValidationBaselineVersion oder PackageValidationBaselineName hinzu.

Bei der Paketüberprüfung werden alle Breaking Changes in einem der ausgelieferten Zielframeworks erkannt. Außerdem wird erkannt, ob die Unterstützung des Zielframeworks gelöscht wurde.

Ein Beispiel: Sie arbeiten am NuGet-Paket „AdventureWorks.Client“ und möchten sicherstellen, dass Sie nicht versehentlich Breaking Changes vornehmen. Sie konfigurieren Ihr Projekt so, dass Paketüberprüfungstools angewiesen werden, API-Kompatibilitätsprüfungen für die vorherige Version des Pakets durchzuführen.

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

Einige Wochen später werden Sie damit beauftragt, Unterstützung für ein Verbindungstimeout zu Ihrer Bibliothek hinzuzufügen. Die Connect-Methode sieht derzeit wie folgt aus:

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

Da es sich bei einem Verbindungstimeout um eine erweiterte Konfigurationseinstellung handelt, können Sie damit rechnen, dass Sie einfach einen optionalen Parameter hinzufügen können:

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

Wenn Sie jedoch versuchen, einen Packvorgang durchzuführen, wird ein Fehler ausgegeben.

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]

Sie werden feststellen, dass dies zwar kein Breaking Change für die Quelle ist, es sich aber um einen eine binären Breaking Change handelt. Sie lösen dieses Problem, indem Sie eine neue Überladung hinzufügen, anstatt der vorhandenen Methode einen Parameter hinzuzufügen:

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

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

Wenn Sie das Projekt jetzt packen, ist es erfolgreich.

Für Version 2.0.0 entscheiden Sie, dass Sie die veraltete Connect-Methode mit dem einzelnen string-Parameter entfernen möchten. Nach sorgfältiger Überlegung entscheiden Sie sich, diese Änderung anzunehmen.

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

Um den CP0002-Fehler für diesen beabsichtigten Breaking Change zu unterdrücken, fügen Sie Ihrem Projekt die Datei CompatibilitySuppressions.xml hinzu. Sie können die Unterdrückungsdatei automatisch generieren, indem Sie einmal dotnet pack /p:GenerateCompatibilitySuppressionFile=true aufrufen. Die Datei enthält eine Unterdrückung für jeden Überprüfungsfehler, der während des Packens aufgetreten ist. Weitere Informationen finden Sie unter Vorgehensweise: Unterdrücken.

In diesem Beispiel enthält die Datei CompatibilitySuppressions.xml die Unterdrückung für den CP0002-Fehler:

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

Diese Datei sollte in die Quellcodeverwaltung eingecheckt werden, um die in einer PR und der kommenden Version vorgenommenen Breaking Changes zu dokumentieren und zu überprüfen.

Nachdem Sie Version 2.0.0 des Pakets veröffentlicht haben, können Sie die Datei CompatibilitySuppressions.xml löschen und die PackageValidationBaselineVersion-Eigenschaft aktualisieren, um zukünftige Änderungen anhand der neuen Version zu überprüfen.

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