Comment gérer les outils .NET
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 :
- Utilisez la commande de recherche d’outils dotnet pour rechercher un outil publié dans NuGet.org.
- Utilisez le filtre de type de package .NET pour rechercher le site web NuGet . Pour plus d’informations, consultez Recherche et sélection des packages.
- Consultez le code source des outils que l’équipe ASP.NET Core a créée dans le répertoire Outils du référentiel GitHub dotnet/aspnetcore.
- En savoir plus sur les outils de diagnostic dans les outils de diagnostic .NET.
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 -g
d’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-path
d’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