Validieren gegen eine Basispaketversion

Die Paketüberprüfung kann Ihnen helfen, Ihr Bibliotheksprojekt anhand einer zuvor veröffentlichten stabilen Version Ihres Pakets zu überprüfen. Um die Paketüberprüfung zu aktivieren, fügen Sie in Ihrer Projektdatei die Eigenschaft PackageValidationBaselineVersion oder die Eigenschaft PackageValidationBaselineName hinzu.

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

Ein Beispiel: Sie arbeiten an dem AdventureWorks.Client NuGet-Paket und möchten sicherstellen, dass Sie keine versehentlichen Änderungen vornehmen. Sie konfigurieren Ihr Projekt so, dass die Paketüberprüfungstools angewiesen werden, API-Kompatibilitätsprüfungen für die vorherige Version des Pakets auszufü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 beauftragt, eine Funktion zum Verbindungstimeout in Ihre Bibliothek einzubauen. Die Connect Methode sieht derzeit wie folgt aus:

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

Da ein Verbindungstimeout eine erweiterte Konfigurationseinstellung ist, denken Sie, 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 Pakets aufgetreten ist. Weitere Informationen finden Sie unter So unterdrücken Sie.

In diesem Beispiel wird CompatibilitySuppressions.xml zur Unterdrückung des CP0002 Fehlers verwendet.

<?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 CompatibilitySuppressions.xml Datei 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>