Comment gérer les outils .NET

Cet article s’applique aux versions suivantes du ✔️ Kit de développement logiciel (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 des manières suivantes :

  • En tant qu’outil global.

    Les fichiers binaires de l’outil 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 de l’ordinateur sans spécifier son emplacement. Une version d’un outil est utilisée pour tous les répertoires de la machine.

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

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

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

    Les fichiers binaires de l’outil 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 manifeste 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 dépôt 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.

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

Système d''exploitation Path
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

Cet emplacement est ajouté au chemin d’accès de l’utilisateur lors de la première exécution du Kit de développement logiciel (SDK). Ainsi, les outils globaux peuvent être appelé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 à l’ordinateur global. Un outil global n’est disponible que 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-pathd’installation de l’outil dotnet, comme illustré 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 Kit de développement logiciel (SDK) .NET n’ajoute pas automatiquement cet emplacement à la variable d’environnement PATH. Pour appeler un outil de chemin d’outil, 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 d’accès complet à l’outil lorsque vous l’appelez.
  • Appelez l’outil à partir du répertoire d’installation.

Installer un outil local

S’applique au Kit de développement logiciel (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 et les sous-répertoires actuels), vous devez ajouter l’outil à un fichier manifeste d’outil. Pour créer un fichier manifeste d’outil, exécutez la dotnet new tool-manifest commande :

dotnet new tool-manifest

Cette commande crée un fichier manifeste nommé dotnet-tools.json sous le répertoire .config . Pour ajouter un outil local au fichier manifeste, utilisez la commande d’installation de l’outil dotnet et omettez les --global options et --tool-path , comme illustré 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 dépôt. Une fois que vous avez vérifié le fichier manifeste dans le dépôt, les développeurs qui extrayent 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 dotnet tool restore commande :

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 montre 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 indiqué 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 du chemin d’outils, utilisez l’option --tool-path .

Appeler un outil global

Pour les outils globaux, utilisez la commande tool par elle-même. Par exemple, si la commande est ou dotnet-doc, c’est dotnetsay 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 dotnet commande 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 dotnet commande pour appeler un outil global :

  • Un outil global et un outil local ont la même commande précédé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 appelez dotnet dotnet-doc l’outil local. Pour appeler l’outil global, utilisez la commande seule :

dotnet-doc

Appeler un outil de chemin d’outil

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

Appeler un outil local

Pour appeler un outil local, vous devez utiliser la dotnet commande à 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 par 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 de le désinstaller et de le réinstaller 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 Kit de développement logiciel (SDK) recherche le premier fichier manifeste contenant l’ID de package dans le répertoire actif et les répertoires parents. S’il n’existe aucun ID de package de ce type dans un fichier manifeste, le KIT de développement logiciel (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 Kit de développement logiciel (SDK) recherche le premier fichier manifeste contenant l’ID de package dans le répertoire actif et les répertoires parents.

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

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

dotnet tool --help

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

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

Voir aussi