Comment gérer les outils .NET

  • Article
  • 8 minutes de lecture

Cet article s’applique au 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 de la manière suivante :

  • En tant qu’outil global.

    Les fichiers binaires d’outils sont installés dans un répertoire par défaut ajouté à la variable d’environnement PATH. Vous pouvez appeler l’outil à partir d’un 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’outils).

    Les fichiers binaires d’outils sont installés à 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 KIT 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’une 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 suivre les 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 toute confiance. N’installez pas d’outil .NET, sauf si vous approuvez l’auteur.

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 toute confiance 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 ou --global l’option -gd’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 Chemin d’accès
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

Cet emplacement est ajouté au chemin d’accès de l’utilisateur lorsque le Kit de développement logiciel (SDK) est exécuté pour la première fois. Ainsi, les outils globaux peuvent être appelés à partir d’un 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 est uniquement disponible 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’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 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 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 actuel 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 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 options et --tool-path les --global options, 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 référentiel. Après avoir vérifié le fichier manifeste dans le référentiel, les développeurs qui extraitnt 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 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 .

Appeler un outil global

Pour les outils globaux, utilisez la commande d’outil 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 le même préfixe dotnet-de commande par .
  • 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 elle-même :

dotnet-doc

Appeler un outil de chemin d’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 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 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 Kit de développement logiciel (SDK) recherche dans le répertoire actuel et les répertoires parents pour rechercher le premier fichier manifeste contenant l’ID du package. S’il n’y a pas d’ID de package 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 de désinstallation de l’outil dotnet 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 dans le répertoire actuel et les répertoires parents pour rechercher le premier fichier manifeste contenant l’ID du package.

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

Si un outil ne parvient pas à installer ou à exécuter, 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 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