Effectuer une validation 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 précédemment publiée et stable de votre package. Pour activer la validation de package, ajoutez la propriété PackageValidationBaselineVersion ou PackageValidationBaselineName à votre fichier projet.

La validation de package détecte toutes les changements cassants sur l’un des frameworks cibles fournis. Il détecte également si la prise en charge du framework cible a été supprimée.

Par exemple, considérez le scénario suivant. Vous travaillez sur le package NuGet AdventureWorks.Client et vous souhaitez vous assurer que vous n’apportez pas accidentellement des changements cassants. 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 êtes chargé d’ajouter la prise en charge d’un délai de connexion à votre bibliothèque. La méthode Connect se présente actuellement ainsi :

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

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

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

Toutefois, lorsque vous essayez d’effectuer un empaquetage, une erreur est générée.

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 vous rendez compte que même s’il ne s’agit pas d’un changement cassant de la source, il s’agit d’un changement cassant 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 réussit.

Pour la version 2.0.0, vous décidez si vous souhaitez supprimer la méthode obsolète Connect qui a le paramètre unique string. Après un examen approfondi, vous décidez d’accepter ce changement cassant.

<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 la création du pack. Pour obtenir plus d’informations, consultez Procédure de suppression.

Dans cet exemple, le fichier 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 archivé dans le contrôle de code source pour documenter et examiner les changements cassants apportés dans une demande de tirage et la prochaine version.

Une fois que vous avez publié la version 2.0.0 du package, vous pouvez supprimer le fichier CompatibilitySuppressions.xml et mettre à jour la propriété PackageValidationBaselineVersion pour valider de 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>