Guide pratique pour gérer les outils .NET

  • Article

Cet article s’applique à : ✔️ SDK .NET Core 2.1 et versions ultérieures.

Un outil .NET est un package NuGet spécial qui contient une application console. Vous pouvez installer un outil sur votre ordinateur de la manière suivante :

  • En tant qu’outil global.

    Les fichiers binaires des outils sont installés dans un répertoire par défaut ajouté à la variable d’environnement PATH. Vous pouvez appeler l’outil à partir de n’importe quel répertoire sur l’ordinateur sans spécifier son emplacement. Une version d’un outil est utilisée pour tous les répertoires sur l’ordinateur.

  • En tant qu’outil global dans un emplacement personnalisé (également appelé outil de chemin d’outil).

    Les fichiers binaires des outils sont installés dans un emplacement que vous spécifiez. Vous pouvez appeler l’outil à partir du répertoire d’installation, en fournissant le répertoire avec le nom de la commande ou en ajoutant le répertoire à la variable d’environnement PATH. Une version d’un outil est utilisée pour tous les répertoires sur l’ordinateur.

  • En tant qu’outil local (s’applique au SDK .NET Core 3.0 et versions ultérieures).

    Les fichiers binaires des outils sont installés dans un répertoire par défaut. Vous pouvez appeler l’outil à partir du répertoire d’installation ou de l’un de ses sous-répertoires. Différents répertoires peuvent utiliser différentes versions du même outil.

    L’interface CLI .NET utilise des fichiers manifestes pour effectuer le suivi des outils installés en tant que locaux dans un répertoire. Lorsque le fichier manifeste est enregistré dans le répertoire racine d’un référentiel de code source, un contributeur peut cloner le référentiel et appeler une seule commande CLI .NET pour installer tous les outils répertoriés dans les fichiers manifestes.

Important

Les outils .NET s’exécutent en confiance totale. N’installez pas d’outil .NET, sauf si vous faites confiance à l’auteur.

Les outils .NET peuvent ne pas fonctionner correctement si .NET a été installé via Snap.

Rechercher un outil

Voici quelques façons de trouver des outils :

Vérifier l’auteur et les statistiques

Les outils .NET peuvent être puissants, car ils s’exécutent en confiance totale et les outils globaux sont ajoutés à la variable d’environnement PATH. Par conséquent, ne téléchargez pas d’outils provenant de personnes en qui vous n’avez pas confiance.

Si l’outil est hébergé sur NuGet, vous pouvez vérifier l’auteur et les statistiques en recherchant l’outil.

Installer un outil global

Pour installer un outil en tant qu’outil global, utilisez l’option -g ou --global de l’installation de l’outil dotnet, comme illustré dans l’exemple suivant :

dotnet tool install -g dotnetsay

La sortie montre la commande utilisée pour appeler l’outil et la version installée, comme dans l’exemple suivant :

You can invoke the tool using the following command: dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.

Notes

Par défaut, l’architecture des fichiers binaires .NET à installer représente l’architecture du système d’exploitation en cours d’exécution. Pour spécifier une architecture de système d’exploitation différente, consultez dotnet tool install, --arch option.

L’emplacement par défaut des fichiers binaires d’un outil dépend du système d’exploitation :

Système d’exploitation Chemin d’accès
Linux/mac OS $HOME/.dotnet/tools
Fenêtres %USERPROFILE%\.dotnet\tools

Cet emplacement est ajouté au chemin d’accès de l’utilisateur lors de la première exécution du SDK. Ainsi, les outils globaux peuvent être invoqués à partir de n’importe quel répertoire sans spécifier l’emplacement de l’outil.

L’accès aux outils est spécifique à l’utilisateur et non global à la machine. Un outil global est disponible uniquement pour l’utilisateur qui a installé l’outil.

Installer un outil global dans un emplacement personnalisé

Pour installer un outil en tant qu’outil global dans un emplacement personnalisé, utilisez l’option --tool-path d’installation de l’outil dotnet, comme indiqué dans les exemples suivants :

Sur Windows :

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

Sur Linux ou macOS :

dotnet tool install dotnetsay --tool-path ~/bin

Le SDK .NET n’ajoute pas cet emplacement automatiquement à la variable d’environnement PATH. Pour appeler un outil de chemin d’accès aux outils, vous devez vous assurer que la commande est disponible à l’aide de l’une des méthodes suivantes :

  • Ajoutez le répertoire d’installation à la variable d’environnement PATH.
  • Spécifiez le chemin complet de l’outil lorsque vous l’appelez.
  • Appelez l’outil à partir du répertoire d’installation.

Installer un outil local

S’applique au SDK .NET Core 3.0 et versions ultérieures.

Si vous souhaitez installer un outil pour l’accès local uniquement (pour le répertoire actif et les sous-répertoires), vous devez ajouter l’outil à un fichier manifeste d’outil. Pour créer un fichier manifeste d’outil, exécutez la commande dotnet new tool-manifest :

dotnet new tool-manifest

Cette commande crée un fichier manifeste dotnet-tools.json dans le répertoire .config. Pour ajouter un outil local au fichier manifeste, utilisez la commande d’installation de l’outil dotnet et omettez les options --global et --tool-path, comme indiqué dans l’exemple suivant :

dotnet tool install dotnetsay

La sortie de commande indique dans quel fichier manifeste l’outil nouvellement installé est présent, comme dans l’exemple suivant :

You can invoke the tool from this directory using the following command:
dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Entry is added to the manifest file /home/name/botsay/.config/dotnet-tools.json.

L’exemple suivant montre un fichier manifeste avec deux outils locaux installés :

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

Vous ajoutez généralement un outil local au répertoire racine du référentiel. Après avoir vérifié le fichier manifeste dans le référentiel, les développeurs qui extraient le code du référentiel obtiennent le dernier fichier manifeste. Pour installer tous les outils répertoriés dans le fichier manifeste, ils exécutent la commande dotnet tool restore :

dotnet tool restore

La sortie indique les outils restaurés :

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Installer une version d’outil spécifique

Pour installer une version préliminaire ou une version spécifique d’un outil, spécifiez le numéro de version à l’aide de l’option --version, comme illustré dans l’exemple suivant :

dotnet tool install dotnetsay --version 2.1.3

Pour installer une version préliminaire de l’outil sans spécifier le numéro de version exact, utilisez l’option --version et fournissez un caractère générique, comme illustré dans l’exemple suivant :

dotnet tool install --global dotnetsay --version "*-rc*"

Utiliser un outil

La commande que vous utilisez pour appeler un outil peut être différente du nom du package que vous installez. Pour afficher tous les outils actuellement installés sur l’ordinateur pour l’utilisateur actuel, utilisez la commande dotnet tool list :

dotnet tool list

La sortie affiche la version et la commande de chaque outil, comme dans l’exemple suivant :

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Comme illustré dans l’exemple précédent, la liste affiche les outils locaux. Pour afficher les outils globaux, utilisez l’option --global. Pour afficher les outils de chemin d’outils, utilisez l’option --tool-path.

Pour lister un outil spécifique, utilisez la commande dotnet tool list <PACKAGE_ID> :

dotnet tool list dotnetsay

La sortie liste uniquement cet outil s’il est installé, comme dans l’exemple suivant :

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Appeler un outil global

Pour les outils globaux, utilisez la commande outil elle-même. Par exemple, si la commande est dotnetsay ou dotnet-doc, c’est ce que vous utilisez pour appeler l’outil global :

dotnetsay
dotnet-doc

Si la commande commence par le préfixe dotnet-, une autre façon d’appeler l’outil consiste à utiliser la commande dotnet et à omettre le préfixe de commande de l’outil. Par exemple, si la commande est dotnet-doc, la commande suivante appelle l’outil :

dotnet doc

Toutefois, dans le scénario suivant, vous ne pouvez pas utiliser la commande dotnet pour appeler un outil global :

  • L’outil global et l’outil local ont la même commande préfixée par dotnet-.
  • Vous souhaitez appeler l’outil global à partir d’un répertoire qui est dans l’étendue de l’outil local.

Dans ce scénario, dotnet doc et dotnet dotnet-doc appellent l’outil local. Pour appeler l’outil global, utilisez la commande seule :

dotnet-doc

Appeler un outil de chemin d’accès aux outils

Pour appeler un outil global installé à l’aide de l’option tool-path, vérifiez que la commande est disponible comme expliqué précédemment dans cet article.

Appeler un outil local

Pour appeler un outil local, vous devez utiliser la commande dotnet à partir du répertoire d’installation. Vous pouvez utiliser le formulaire long (dotnet tool run <COMMAND_NAME>) ou le formulaire court (dotnet <COMMAND_NAME>), comme illustré dans les exemples suivants :

dotnet tool run dotnetsay
dotnet dotnetsay

Si la commande est précédée d’un préfixe dotnet-, vous pouvez inclure ou omettre le préfixe lorsque vous appelez l’outil. Par exemple, si la commande est dotnet-doc, l’un des exemples suivants appelle l’outil local :

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

Mettre à jour un outil

La mise à jour d’un outil implique la désinstallation et la réinstallation avec la dernière version stable. Pour mettre à jour un outil, utilisez la commande dotnet tool update avec la même option que celle que vous avez utilisée pour installer l’outil :

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

Pour un outil local, le SDK recherche dans le répertoire actif et les répertoires parents pour rechercher le premier fichier manifeste contenant l’ID de package. S’il n’existe aucun ID de package de ce type dans un fichier manifeste, le SDK ajoute une nouvelle entrée au fichier manifeste le plus proche.

Désinstaller un outil

Désinstallez un outil à l’aide de la commande dotnet tool uninstall avec la même option que celle que vous avez utilisée pour installer l’outil :

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

Pour un outil local, le SDK recherche dans le répertoire actif et les répertoires parents pour rechercher le premier fichier manifeste contenant l’ID de package.

Obtenir de l’aide et résoudre les problèmes

Si un outil ne parvient pas à installer ou à s’exécuter, consultez Résoudre les problèmes d’utilisation de l’outil .NET. Vous pouvez obtenir la liste des commandes et paramètres dotnet tool disponibles à l’aide du paramètre --help :

dotnet tool --help

Pour obtenir des instructions d’utilisation des outils, entrez l’une des commandes suivantes ou consultez le site web de l’outil :

<command> --help
dotnet <command> --help

Voir aussi