Vue d’ensemble des outils globaux .NET Core.NET Core Global Tools overview

• 05/29/2018
• 5 minutes de lecture
• Contributeurs
  • 
  • 

Cette rubrique s’applique à : ✓ kit SDK .NET Core 2.1 (et versions ultérieures)This topic applies to: ✓ .NET Core 2.1 SDK and later versions

Un outil global .NET Core est un package NuGet spécial qui contient une application console.A .NET Core Global Tool is a special NuGet package that contains a console application. Vous pouvez installer un outil global sur votre machine à un emplacement par défaut inclus dans la variable d’environnement PATH ou à un emplacement personnalisé.A Global Tool can be installed on your machine on a default location that is included in the PATH environment variable or on a custom location.

Pour utiliser un outil global .NET Core :If you want to use a .NET Core Global Tool:

• Recherchez des informations sur l’outil (généralement un site web ou une page GitHub).Find information about the tool (usually a website or GitHub page).
• Vérifiez l’auteur et les statistiques dans la page d’accueil du flux (généralement NuGet.org).Check the author and statistics in the home for the feed (usually NuGet.org).
• Installez l’outil.Install the tool.
• Appelez l’outil.Call the tool.
• Mettez à jour l’outil.Update the tool.
• Désinstallez l’outil.Uninstall the tool.

Rechercher un outil global .NET CoreFind a .NET Core Global Tool

Actuellement, l’interface de ligne de commande (CLI) .NET Core ne comprend pas de fonctionnalité de recherche d’outil global.Currently, there isn't a Global Tool search feature in the .NET Core Command-line Interface (CLI).

Vous trouverez des outils globaux .NET Core sur NuGet.You can find .NET Core Global Tools on NuGet. Toutefois, NuGet ne vous permet pas encore de rechercher spécifiquement des outils globaux .NET Core.However, NuGet doesn't yet allow you to search specifically for .NET Core Global Tools.

Vous pouvez également trouver des suggestions d’outils dans les billets de blog ou dans le dépôt GitHub natemcmaster/dotnet-tools.You may also find tool recommendations in blog posts or in the natemcmaster/dotnet-tools GitHub repository.

Vous pouvez également voir le code source des outils globaux créés par l’équipe ASP.NET dans le dépôt GitHub aspnet/DotNetTools.You can also see the source code for the Global Tools created by the ASP.NET team at the aspnet/DotNetTools GitHub repository.

Vérifier l’auteur et les statistiquesCheck the author and statistics

Étant donné que les outils globaux .NET Core s’exécutent en mode de confiance totale et qu’ils sont généralement installés dans votre chemin, ils peuvent être très puissants.Since .NET Core Global Tools run in full trust and are generally installed on your path, they can be very powerful. Par conséquent, ne téléchargez pas d’outils provenant de personnes en qui vous n’avez pas confiance.Don't download tools from people you don't trust.

Si l’outil est hébergé sur NuGet, vous pouvez vérifier l’auteur et les statistiques en recherchant l’outil.If the tool is hosted on NuGet, you can check the author and statistics by searching for the tool.

Installer un outil globalInstall a Global Tool

Pour installer un outil global, utilisez la commande CLI .NET Core dotnet tool install.To install a Global Tool, you use the dotnet tool install .NET Core CLI command. L’exemple suivant montre comment installer un outil global à l’emplacement par défaut :The following example shows how to install a Global Tool in the default location:

dotnet tool install -g dotnetsay

Si l’outil ne peut pas être installé, des messages d’erreur s’affichent.If the tool can't be installed, error messages are displayed. Assurez-vous que les flux attendus sont vérifiés.Check that the feeds you expected are being checked.

Si vous essayez d’installer une préversion ou une version spécifique de l’outil, vous pouvez spécifier le numéro de version au format suivant :If you're trying to install a pre-release version or a specific version of the tool, you can specify the version number using the following format:

dotnet tool install -g <package-name> --version <version-number>

Si l’installation réussit, un message s’affiche indiquant la commande utilisée pour appeler l’outil et la version installée, comme dans l’exemple suivant :If installation is successful, a message is displayed showing the command used to call the tool and the version installed, similar to the following example:

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

Il est possible d’installer des outils globaux dans le répertoire par défaut ou à un emplacement spécifique.Global Tools can be installed in the default directory or in a specific location. Les répertoires par défaut sont :The default directories are:

Ces emplacements sont ajoutés au chemin de l’utilisateur lors de la première exécution du SDK, si bien que les outils globaux qui y sont installés peuvent être appelées directement.These locations are added to the user's path when the SDK is first run, so Global Tools installed there can be called directly.

Notez que les outils globaux sont propres à l’utilisateur, et non globaux pour la machine.Note that the Global Tools are user-specific, not machine global. Le fait d’être propre à l’utilisateur signifie que vous ne pouvez pas installer un outil global disponible pour tous les utilisateurs de la machine.Being user-specific means you cannot install a Global Tool that is available to all users of the machine. L’outil est uniquement disponible pour chaque profil utilisateur dans lequel l’outil a été installé.The tool is only available for each user profile where the tool was installed.

Les outils globaux peuvent également être installés dans un répertoire spécifique.Global Tools can also be installed in a specific directory. Lors d’une installation dans un répertoire spécifique, l’utilisateur doit vérifier que la commande est disponible, en incluant ce répertoire dans le chemin, en appelant la commande avec le répertoire spécifié, ou en appelant l’outil à partir du répertoire spécifié.When installed in a specific directory, the user must ensure the command is available, by including that directory in the path, by calling the command with the directory specified, or calling the tool from within the specified directory. Dans ce cas, CLI .NET Core n’ajoute pas automatiquement cet emplacement à la variable d’environnement PATH.In this case, the .NET Core CLI doesn't add this location automatically to the PATH environment variable.

Utiliser l’outilUse the tool

Une fois que l’outil est installé, vous pouvez l’appeler à l’aide de sa commande.Once the tool is installed, you can call it by using its command. Notez que la commande peut ne pas être identique au nom du package.Note that the command may not be the same as the package name.

Si la commande est dotnetsay, vous l’appelez avec :If the command is dotnetsay, you call it with:

dotnetsay

Si l’auteur de l’outil voulait que l’outil apparaisse dans le contexte de l’invite dotnet, il peut l’avoir écrit de façon à ce que vous l’appeliez en utilisant dotnet <command>, par exemple :If the tool author wanted the tool to appear in the context of the dotnet prompt, they may have written it in a way that you call it as dotnet <command>, such as:

dotnet doc

Vous pouvez déterminer quels outils sont inclus dans un package d’outils globaux installé en répertoriant les packages installés à l’aide de la commande dotnet tool list.You can find which tools are included in an installed Global Tool package by listing the installed packages using the dotnet tool list command.

Vous pouvez également rechercher des instructions d’utilisation sur le site web de l’outil ou en tapant l’une des commandes suivantes :You can also look for usage instructions at the tool's website or by typing one of the following commands:

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

Problèmes potentielsWhat could go wrong

Les outils globaux sont des applications dépendant du framework, ce qui signifie qu’ils reposent sur un runtime .NET Core installé sur votre machine.Global Tools are framework-dependent applications, which means they rely on a .NET Core runtime installed on your machine. Si le runtime attendu est introuvable, ils suivent les règles normales de restauration par progression du runtime .NET Core, à savoir :If the expected runtime is not found, they follow normal .NET Core runtime roll-forward rules such as:

• Une application restaure par progression le correctif le plus élevé de la version principale et secondaire spécifiée.An application rolls forward to the highest patch release of the specified major and minor version.
• En l’absence de runtime correspondant à un numéro de version principale et secondaire, la version secondaire supérieure suivante est utilisée.If there is no matching runtime with a matching major and minor version number, the next higher minor version is used.
• Une restauration par progression ne se produit pas entre des préversions du runtime ou entre des préversions et des versions finales.Roll forward doesn't occur between preview versions of the runtime or between preview versions and release versions. C’est pourquoi les outils globaux créés à l’aide de préversions doivent être regénérés et republiés par l’auteur, puis réinstallés.Thus, Global Tools created using preview versions must be rebuilt and republished by the author and reinstalled.
• D’autres problèmes peuvent se produire avec les outils globaux créés dans .NET Core 2.1 Preview 1.Additional issues can occur with Global Tools created in .NET Core 2.1 Preview 1. Pour plus d’informations, consultez Problèmes connus de .NET Core 2.1 Preview 2.For more information, see .NET Core 2.1 Preview 2 Known Issues.

Si une application ne trouve pas un runtime approprié, elle ne parvient pas à s’exécuter et signale une erreur.If an application cannot find an appropriate runtime, it fails to run and reports an error.

Un autre problème susceptible de se produire vient du fait qu’un outil global créé pendant une préversion antérieure risque de ne pas s’exécuter avec vos runtimes .NET Core actuellement installés.Another issue that might happen is that a Global Tool that was created during an earlier preview may not run with your currently installed .NET Core runtimes. Vous pouvez voir quels runtimes sont installés sur votre machine à l’aide de la commande suivante :You can see which runtimes are installed on your machine using the following command:

dotnet --list-runtimes

Contactez l’auteur de l’outil global pour voir s’il peut recompiler et republier son package d’outils sur NuGet avec un numéro de version mis à jour.Contact the author of the Global Tool and see if they can recompile and republish their tool package to NuGet with an updated version number. Une fois la mise à jour du package effectuée sur NuGet, vous pouvez mettre à jour votre copie.Once they have updated the package on NuGet, you can update your copy.

CLI .NET Core essaie d’ajouter les emplacements par défaut à la variable d’environnement PATH lors de sa première utilisation.The .NET Core CLI tries to add the default locations to the PATH environment variable on its first usage. Toutefois, dans certains cas, il n’est pas possible d’ajouter automatiquement l’emplacement à PATH, notamment :However, there are a couple of scenarios where the location might not be added to PATH automatically, such as:

• Si vous avez défini la variable d’environnement DOTNET_SKIP_FIRST_TIME_EXPERIENCE.If you've set the DOTNET_SKIP_FIRST_TIME_EXPERIENCE environment variable.
• Sur macOS, si vous avez installé le SDK .NET Core à l’aide de fichiers .tar.gz et non .pkg.On macOS, if you've installed the .NET Core SDK using .tar.gz files and not .pkg.
• Sur Linux, vous devez modifier le fichier d’environnement d’interpréteur de commandes pour configurer PATH.On Linux, you need to edit the shell environment file to configure the PATH.

Autres commandes CLIOther CLI commands

Le SDK .NET Core contient d’autres commandes qui prennent en charge des outils globaux .NET Core.The .NET Core SDK contains other commands that support .NET Core Global Tools. Utilisez l’une des commandes dotnet tool avec l’une des options suivantes :Use any of the dotnet tool commands with one of the following options:

• --global ou -g spécifient que la commande s’applique aux outils globaux à l’échelle de l’utilisateur.--global or -g specifies that the command is applicable to user-wide Global Tools.
• --tool-path spécifie un emplacement personnalisé pour les outils globaux.--tool-path specifies a custom location for Global Tools.

Pour déterminer les commandes disponibles pour les outils globaux :To find out which commands are available for Global Tools:

dotnet tool --help

La mise à jour d’un outil global implique de le désinstaller puis de le réinstaller avec la dernière version stable.Updating a Global Tool involves uninstalling and reinstalling it with the latest stable version. Pour mettre à jour un outil global, utilisez la commande dotnet tool update :To update a Global Tool, use the dotnet tool update command:

dotnet tool update -g <packagename>

Supprimez un outil global avec dotnet tool uninstall :Remove a Global Tool using the dotnet tool uninstall:

dotnet tool uninstall -g <packagename>

Pour afficher tous les outils globaux actuellement installés sur la machine, ainsi que leur version et leurs commandes, utilisez la commande dotnet tool list :To display all of the Global Tools currently installed on the machine, along with their version and commands, use the dotnet tool list command:

dotnet tool list -g