Outil global Microsoft.DotNet.ApiCompat.Tool

L’outil Microsoft.DotNet.ApiCompat.Tool vous permet d’effectuer des vérifications de compatibilité des API en dehors de MSBuild. L’outil a deux modes :

• Comparez un package à un package de référence.
• Comparez un assembly à un assembly de ligne de base.

Installer

Pour installer l’outil, exécutez la commande suivante.

dotnet tool install --global Microsoft.DotNet.ApiCompat.Tool

Pour plus d’informations sur l’installation des outils globaux, consultez Installer un outil global.

Utilisation

Microsoft.DotNet.ApiCompat.Tool [command] [options]

-ou-

apicompat [command] [options]

Commandes

• package | --package <PACKAGE_FILE>

  Valide la compatibilité des ressources de package. S’il n’est pas spécifié, l’outil compare les assemblys. <PACKAGE_FILE> spécifie le chemin du fichier de package.

Options

Certaines options s’appliquent à la fois à l’assembly et à la validation de package. D’autres s’appliquent aux assemblys ou aux packages uniquement.

Options générales

• --version

  Afficher les informations de version.

• --generate-suppression-file

  Génère un fichier de suppression de compatibilité.

• --preserve-unnecessary-suppressions

  Conserve les suppressions inutiles lors de la régénération du fichier de suppression.

  Lorsqu’un fichier de suppression existant est régénéré, son contenu est lu, désérialisé dans un ensemble de suppressions, puis stocké dans une liste. Il est possible que certaines des suppressions ne soient plus nécessaires si l’incompatibilité a été corrigée. Lorsque les suppressions sont resérialisées sur disque, vous pouvez choisir de conserver toutes les expressions (désérialisées) existantes en spécifiant cette option.

• --permit-unnecessary-suppressions

  Autorise les suppressions inutiles dans le fichier de suppression.

• --suppression-file <FILE>

  Spécifie le chemin d’accès à un ou plusieurs fichiers de suppression à lire.

• --suppression-output-file <FILE>

  Spécifie le chemin d’accès à un fichier de suppression à écrire quand --generate-suppression-file est spécifié. S’il n’est pas spécifié, le premier chemin d’accès --suppression-file est utilisé.

• --noWarn <NOWARN_STRING>

  Spécifie les ID de diagnostic à supprimer. Par exemple : "$(NoWarn);PKV0001".

• --respect-internals

  Vérifie à la fois les API internal et public.

• --roslyn-assemblies-path <FILE>

  Spécifie le chemin d’accès au répertoire qui contient les assemblies Microsoft.CodeAnalysis que vous souhaitez utiliser. Vous devez uniquement définir cette propriété si vous souhaitez tester avec un compilateur plus récent que ce qui se trouve dans le kit de développement logiciel (SDK).

• -v, --verbosity [high|low|normal]

  Contrôle le niveau de la verbosité du journal. Les valeurs autorisées sont high, normal et low. Par défaut, il s’agit de normal.

• --enable-rule-cannot-change-parameter-name

  Active la règle qui vérifie si les noms de paramètres ont changé dans les méthodes publiques.

• --enable-rule-attributes-must-match

  Active la règle qui vérifie si les attributs correspondent.

• --exclude-attributes-file <FILE>

  Spécifie le chemin d’accès à un ou plusieurs fichiers qui contiennent des attributs à exclure au format DocId.

Options spécifiques à l’assembly

Ces options s’appliquent uniquement lorsque les assemblys sont comparés.

• -l, --left, --left-assembly <PATH>

  Spécifie le chemin d’accès à un ou plusieurs assemblys qui servent de côté gauche à comparer. Cette option est requise lors de la comparaison d’assemblys.

• -r, --right, --right-assembly <PATH>

  Spécifie le chemin d’accès à un ou plusieurs assemblys qui servent de côté droit à comparer. Cette option est requise lors de la comparaison d’assemblys.

• --strict-mode

  Effectue des vérifications de compatibilité des API en mode strict.

Options spécifiques à un package

Ces options s’appliquent uniquement lorsque les packages sont comparés.

• --baseline-package

  Spécifie le chemin d’accès à un package de référence pour valider le package actuel.

• --enable-strict-mode-for-compatible-tfms

  Valide la compatibilité des API en mode strict pour les assemblies de contrat et d’implémentation pour toutes les versions cibles de .Net Framework compatibles. Par défaut, il s’agit de true.

• --enable-strict-mode-for-compatible-frameworks-in-package

  Valide la compatibilité des API en mode strict pour les assemblies compatibles en fonction de leur version cible de .Net Framework.

• --enable-strict-mode-for-baseline-validation

  Valide la compatibilité des API en mode strict pour les vérifications de base de package.

• --package-assembly-references

  Spécifie les chemins d’accès aux références d’assembly ou à leurs répertoires sous-jacents pour une version cible de .Net Framework spécifique dans le package. Séparez les valeurs multiples par des virgules.

• --baseline-package-assembly-references

  Spécifie les chemins d’accès aux références d’assembly ou à leurs répertoires sous-jacents pour une version cible de .Net Framework spécifique dans le package de la ligne de base. Séparez les valeurs multiples par des virgules.

• --baseline-package-frameworks-to-ignore

  Spécifie l’ensemble de versions cibles de .Net Framework à ignorer à partir du package de la ligne de base. La chaîne d’infrastructure doit correspondre exactement au nom du dossier dans le package de la ligne de base.

Exemples

La commande suivante compare les versions actuelles et de la ligne de base d’un assembly.

apicompat --left bin\Release\net8.0\LibApp5.dll --right bin\Release\net8.0\LibApp5-baseline.dll

La commande suivante compare les versions actuelles et de la ligne de base d’un assembly.

apicompat package "bin\Release\LibApp5.1.0.0.nupkg" --baseline-package "bin\Release\LibApp5.2.0.0.nupkg"

L’exemple suivant montre la commande permettant de comparer les versions actuelles et de référence d’un assembly, y compris la vérification des modifications de nom de paramètre. L’exemple montre également à quoi ressemblerait la sortie si un nom de paramètre était changé.

>apicompat -l LibApp5-baseline.dll -r LibApp5.dll --enable-rule-cannot-change-parameter-name
API compatibility errors between 'LibApp5-baseline.dll' (left) and 'LibApp5.dll' (right):
CP0017: Parameter name on member 'KitchenHelpers.ToastBreadAsync(int, int)'
changed from 'slices' to 'numSlices'.
API breaking changes found. If those are intentional, the APICompat
suppression file can be updated by specifying the '--generate-suppression-file' parameter.