Valider par rapport à une version de package de référence

La validation de package peut vous aider à valider votre projet de bibliothèque par rapport à une version antérieure et stable de votre package. Pour activer la validation du package, ajoutez la propriété PackageValidationBaselineVersion ou PackageValidationBaselineName à votre fichier projet.

La validation de package détecte les changements cassants sur l’une des infrastructures cibles livrées. Elle détecte également si une prise en charge de l’infrastructure cible a été supprimée.

Par exemple, considérez le scénario suivant. Vous travaillez sur le package NuGet AdventureWorks.Client et vous voulez vous assurer que vous n’effectuez pas des changements cassants par accident. Vous configurez votre projet pour indiquer aux outils de validation de package d’exécuter des vérifications de compatibilité des API par rapport à la version précédente du package.

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

Quelques semaines plus tard, vous avez la tâche d’ajouter la prise en charge d’un délai d’expiration de connexion à votre bibliothèque. La Connect méthode ressemble actuellement à ceci :

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

Étant donné qu’un délai d’expiration de connexion est un paramètre de configuration avancé, vous pensez que vous pouvez simplement ajouter un paramètre facultatif :

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

Toutefois, lorsque vous essayez d'emballer, cela génère une erreur.

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]

Vous réalisez que bien que ce n'est pas une modification qui casse la compatibilité source, il s'agit d'une modification qui casse la compatibilité binaire. Vous résolvez ce problème en ajoutant une nouvelle surcharge au lieu d’ajouter un paramètre à la méthode existante :

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

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

Maintenant, lorsque vous empaquetez le projet, il aboutit.

Pour la version 2.0.0, vous décidez de supprimer la méthode obsolète Connect qui a le paramètre unique string . Après une considération minutieuse, vous décidez d’accepter ce changement majeur.

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

Pour supprimer l’erreur CP0002 de ce changement cassant intentionnel, vous pouvez ajouter un fichier CompatibilitySuppressions.xml à votre projet. Vous pouvez générer automatiquement le fichier de suppression en appelant dotnet pack /p:GenerateCompatibilitySuppressionFile=true une seule fois. Le fichier contient une suppression pour chaque erreur de validation qui s’est produite pendant le pack. Pour plus d’informations, consultez Comment supprimer.

Dans cet exemple, le CompatibilitySuppressions.xml contient la suppression de l’erreur 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>

Ce fichier doit être vérifié dans le contrôle de source afin de documenter et d’examiner les changements cassants effectués dans une RP et la version à venir.

Une fois que vous avez publié la version 2.0.0 du package, vous pouvez supprimer le fichier CompatibilitySuppressions.xml et mettre à jour la PackageValidationBaselineVersion propriété pour valider les futures modifications par rapport à la nouvelle version.

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