Validation d’assembly

Comme pour la validation de package, les outils de validation d’assembly vous permettent, en tant que développeur de bibliothèques, de vérifier que vos assemblys sont cohérents et bien formés. Utilisez la validation d’assembly au lieu de la validation de package lorsque votre application ne peut pas être ajoutée dans un package.

La validation d’assembly fournit les vérifications suivantes :

• Ils vérifient qu’il n’y a pas de changements cassants entre les versions.
• Permet de vérifier que l’assembly a le même ensemble d’API publiques pour toutes les différentes implémentations spécifiques au runtime.
• Permet de détecter les failles d’applicabilité.

Vous pouvez exécuter la validation d’assembly en tant que tâche MSBuild ou à l’aide de l’outil global Microsoft.DotNet.ApiCompat.Tool.

Activer une tâche MSBuild

Vous activez la validation d’assembly dans votre projet .NET en définissant la propriété ApiCompatValidateAssemblies sur true et en spécifiant le chemin d’accès au contrat (base de référence) d’assembly. Vous devez également ajouter une référence de package à Microsoft.DotNet.ApiCompat.Task. (Les fichiers targets de ce package ne font pas partie du Kit de développement logiciel (SDK) .NET.)

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFrameworks>net8.0</TargetFrameworks>
    <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
    <ApiCompatContractAssembly>[Path to contract assembly]</ApiCompatContractAssembly>
    <IsPackable>false</IsPackable>
  </PropertyGroup>

  <ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
    <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
  </ItemGroup>

</Project>

La validation d’assembly s’exécute dans la build externe pour les projets à plusieurs cibles (après la cible DispatchToInnerBuilds) ou dans la build interne pour un projet à cible unique (dans le cadre de la cible PrepareForRun). Elle est également entièrement incrémentielle, ce qui signifie que la comparaison est déclenchée uniquement en cas de changement des entrées ou des sorties.

Exemple

1. Créez et générez une bibliothèque de classes C# nommée « ValidateMe » qui contient l’interface simple suivante :

   namespace ValidateMe;
   
   public interface IAnimal
   {
       string Name { get; }
       //string Sound { get; }
   }
   

2. Renommez l’assembly de sortie en « ValidateMeV1.dll ».

3. Ajoutez la propriété Sound à l’interface en supprimant les marques de commentaire de cette ligne de code.

4. Ajoutez les propriétés ApiCompatValidateAssemblies et ApiCompatContractAssembly ainsi que la référence de package « Microsoft.DotNet.ApiCompat.Task » à votre fichier projet. Incrémentez également la version de votre assembly à « 2.0.0 ».

   <PropertyGroup>
     <OutputType>Library</OutputType>
     <TargetFrameworks>net8.0</TargetFrameworks>
     <ApiCompatValidateAssemblies>true</ApiCompatValidateAssemblies>
     <ApiCompatContractAssembly>$(OutDir)bin\Release\net8.0\ValidateMeV1.dll</ApiCompatContractAssembly>
     <IsPackable>false</IsPackable>
     <Version>2.0.0</Version>
   </PropertyGroup>
   
   <ItemGroup Condition="'$(ApiCompatValidateAssemblies)' == 'true'">
      <PackageReference Include="Microsoft.DotNet.ApiCompat.Task" Version="8.0.100" PrivateAssets="all" IsImplicitlyDefined="true" />
   </ItemGroup>
   

5. Regénérez votre bibliothèque de classes.

   La build échoue avec les erreurs suivantes :

   C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API compatibility errors between 'bin\Release\net8.0\ValidateMeV1.dll' (left) and 'C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll' (right):
   1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error CP0006: Cannot add interface member 'string ValidateMe.IAnimal.Sound' to C:\Users\me\source\repos\ValidateMe\bin\Release\net8.0\ValidateMe.dll because it does not exist on bin\Release\net8.0\ValidateMeV1.dll
   1>C:\Users\me\.nuget\packages\microsoft.dotnet.apicompat.task\8.0.100\build\Microsoft.DotNet.ApiCompat.ValidateAssemblies.Common.targets(16,5): error : API breaking changes found. If those are intentional, the APICompat suppression file can be updated by rebuilding with '/p:ApiCompatGenerateSuppressionFile=true'
   

Supprimer les avertissements de compatibilité

Pour obtenir plus d’informations sur la suppression des avertissements de compatibilité, consultez Procédure de suppression.