Partage via

Outil de compatibilité des API 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 assemblage à un assemblage de base.

Installez

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

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

Pour plus d’informations sur l’installation d’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. Si aucune spécification n'est donnée, l'outil compare les assemblies. <PACKAGE_FILE> spécifie le chemin d’accès au fichier de package.

Paramètres

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

Options générales

  • --version

    Affiche 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 sérialisées sur disque, vous pouvez choisir de conserver toutes les expressions existantes (désérialisées) 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 lorsque --generate-suppression-file est spécifié. S’il n’est pas spécifié, le premier --suppression-file chemin d’accès est utilisé.

  • --noWarn <NOWARN_STRING>

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

  • --respect-internals

    Vérifie les API internal et public.

  • --roslyn-assemblies-path <FILE>

    Spécifie le chemin d’accès au répertoire qui contient les assemblys 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 verbosité du journal. Les valeurs autorisées sont high, normalet low. La valeur par défaut est 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’assemblage

Ces options s’appliquent uniquement à la comparaison des assemblages.

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

    Spécifie le chemin d’accès à un ou plusieurs assemblys qui servent de côté gauche pour 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 pour 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 au 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 assemblys de contrat et d’implémentation pour toutes les infrastructures cibles compatibles. La valeur par défaut est true.

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

    Valide la compatibilité des API en mode strict pour les assemblys compatibles en fonction de leur infrastructure cible.

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

    Valide la compatibilité des API en mode strict pour les vérifications de la base de référence du 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 infrastructure cible spécifique du package. Séparez plusieurs valeurs par une virgule.

  • --baseline-package-assembly-references

    Spécifie les chemins d’accès aux références d’assembly ou à leurs répertoires sous-jacents pour un framework cible spécifique dans le package baseline. Séparez plusieurs valeurs par une virgule.

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

    Spécifie l’ensemble de frameworks cibles à ignorer à partir du package de référence. La chaîne de framework doit correspondre exactement au nom du dossier dans le paquet de référence.

Exemples

La commande suivante compare les versions actuelles et de référence 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 référence d’un package.

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 ressemble la sortie si un nom de paramètre a 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.
  • Last updated on