Outils de compatibilité des API

  • Article

La compatibilité multiplateforme est devenue une exigence courante pour les créateurs de bibliothèques .NET. Toutefois, sans outils pour valider les assemblys et les packages, il est possible qu’ils contiennent des changements cassants involontaires. En tant qu’auteur de bibliothèque, vous devez vérifier que les assemblys multi-ciblés sont compatibles. Par exemple, pour un package ciblant plusieurs cibles pour .NET 6 et .NET Standard 2.0, vous devez vérifier que le code compilé sur le binaire .NET Standard 2.0 peut s’exécuter sur le binaire .NET 6.

Vous pouvez penser qu’une modification est sûre et compatible si la source consommant cette modification continue de se compiler sans modifications. Cependant, les modifications peuvent toujours causer des problèmes au moment de l’exécution si le consommateur n’a pas été recompilé. Par exemple, l’ajout d’un paramètre facultatif à une méthode ou la modification de la valeur d’une constante peut entraîner ces types de problèmes de compatibilité.

Le Kit de développement logiciel (SDK) .NET vous offre différentes façons de comparer les versions générées pour différents frameworks cibles. Vous pouvez également valider une version plus récente par rapport à une version de référence pour veiller à ce qu’aucun changement cassant n’ait été introduit. Activez des tâches MSBuild pour valider vos assemblys au moment de la compilation ou vos packages lorsque vous créez un package. Vous pouvez également utiliser l’outil global Microsoft.DotNet.ApiCompat.Tool pour valider en dehors de MSBuild.

Si vous souhaitez obtenir plus d’informations sur la validation de packages, consultez Validation de package. La validation de l’assembly doit être utilisée lorsque votre application ne peut pas être ajoutée dans un package. Pour obtenir plus d’informations sur la validation d’assembly, consultez Validation d’assembly.

Remarque

Si vous souhaitez exécuter la validation d’assembly en tant que tâche MSBuild, vous devez ajouter une référence de package à Microsoft.DotNet.ApiCompat.Task. De la même façon, vous pouvez également ajouter une référence à ce package lorsque vous souhaitez tester des fonctionnalités plus récentes qui ne sont pas encore disponibles dans le Kit de développement logiciel (SDK) .NET. Par exemple, vous pouvez référencer la version 9.0.100-preview du package Microsoft.DotNet.ApiCompat.Task lors de l’utilisation du Kit de développement logiciel (SDK) .NET 8.

Mode strict

Par défaut, la validation effectue des vérifications de compatibilité. Toutefois, vous pouvez également choisir le mode strict. En mode strict, la validation effectue des vérifications d’égalité. L’égalité signifie qu’aucun ajout d’API, ou aucune modification d’assembly, même compatible, n’a été apporté.

Les cas d’usage du mode strict sont les suivants :

  • Maintenance dans laquelle les ajouts d’API sont généralement interdits.
  • Pour le suivi des modifications d’API. La fonctionnalité de compatibilité d’API enregistre toutes les différences de compatibilité dans le fichier de suppression si vous définissez ApiCompatGenerateSuppressionFile sur true.

Pour activer le mode strict pour l’outil en ligne de commande, spécifiez l’option --strict-mode ou l’une des options --enable-strict*. Pour activer le mode strict pour les tâches MSBuild, ajoutez une ou plusieurs des propriétés MSBuild suivantes à votre Fichier projet :