Problème .NET Problèmes d’utilisation d’outils de baseTroubleshoot .NET Core tool usage issues

Vous pourriez rencontrer des problèmes lorsque vous essayez d’installer ou d’exécuter un outil .NET Core, qui peut être un outil global ou un outil local.You might come across issues when trying to install or run a .NET Core tool, which can be a global tool or a local tool. Cet article décrit les causes profondes communes et certaines solutions possibles.This article describes the common root causes and some possible solutions.

L’outil de base .NET installé ne fonctionne pasInstalled .NET Core tool fails to run

Lorsqu’un outil .NET Core ne fonctionne pas, il est fort probable que vous ayez rencontré l’un des problèmes suivants :When a .NET Core tool fails to run, most likely you ran into one of the following issues:

  • Le fichier exécutable pour l’outil n’a pas été trouvé.The executable file for the tool wasn't found.
  • La version correcte du temps d’exécution .NET Core n’a pas été trouvée.The correct version of the .NET Core runtime wasn't found.

Fichier exécutable non trouvéExecutable file not found

Si le fichier exécutable n’est pas trouvé, vous verrez un message similaire à ce qui suit :If the executable file isn't found, you'll see a message similar to the following:

Could not execute because the specified command or file was not found.
Possible reasons for this include:
  * You misspelled a built-in dotnet command.
  * You intended to execute a .NET Core program, but dotnet-xyz does not exist.
  * You intended to run a global tool, but a dotnet-prefixed executable with this name could not be found on the PATH.

Le nom de l’exécutable détermine comment vous invoquez l’outil.The name of the executable determines how you invoke the tool. Le tableau suivant décrit le format :The following table describes the format:

Format de nom exécutableExecutable name format Format d’invocationInvocation format
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>
  • Outils globauxGlobal tools

    Des outils globaux peuvent être installés dans l’annuaire par défaut ou dans un endroit 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:

    Système d''exploitationOS PathPath
    Linux/macOSLinux/macOS $HOME/.dotnet/tools
    WindowsWindows %USERPROFILE%\.dotnet\tools

    Si vous essayez d’exécuter un outil PATH global, vérifiez que la variable d’environnement sur votre machine contient le chemin où vous avez installé l’outil global et que l’exécutable est dans ce sens.If you're trying to run a global tool, check that the PATH environment variable on your machine contains the path where you installed the global tool and that the executable is in that path.

    Le CLI core .NET essaie d’ajouter l’emplacement par défaut à la variable d’environnement PATH sur sa première utilisation.The .NET Core CLI tries to add the default location to the PATH environment variable on its first usage. Cependant, il existe certains scénarios où l’emplacement pourrait ne pas être ajouté à PATH automatiquement:However, there are some scenarios where the location might not be added to PATH automatically:

    • Si vous utilisez Linux et que vous avez installé le .NET Core SDK à l’aide de fichiers .tar.gz et non pas apt-get ou rpm.If you're using Linux and you've installed the .NET Core SDK using .tar.gz files and not apt-get or rpm.
    • Si vous utilisez macOS 10.15 "Catalina" ou des versions ultérieures.If you're using macOS 10.15 "Catalina" or later versions.
    • Si vous utilisez macOS 10.14 "Mojave" ou des versions antérieures, et vous avez installé le .NET Core SDK en utilisant des fichiers .tar.gz et non .pkg.If you're using macOS 10.14 "Mojave" or earlier versions, and you've installed the .NET Core SDK using .tar.gz files and not .pkg.
    • Si vous avez installé le .NET Core 3.0 SDK et que vous avez défini la variable de l’environnement DOTNET_ADD_GLOBAL_TOOLS_TO_PATH à false.If you've installed the .NET Core 3.0 SDK and you've set the DOTNET_ADD_GLOBAL_TOOLS_TO_PATH environment variable to false.
    • Si vous avez installé .NET Core 2.2 SDK ou des DOTNET_SKIP_FIRST_TIME_EXPERIENCE versions trueantérieures, et que vous avez défini la variable de l’environnement à .If you've installed .NET Core 2.2 SDK or earlier versions, and you've set the DOTNET_SKIP_FIRST_TIME_EXPERIENCE environment variable to true.

    Dans ces scénarios ou si --tool-path vous PATH avez spécifié l’option, la variable d’environnement sur votre machine ne contient pas automatiquement le chemin où vous avez installé l’outil global.In these scenarios or if you specified the --tool-path option, the PATH environment variable on your machine doesn't automatically contain the path where you installed the global tool. Dans ce cas, appendicez l’emplacement de l’outil (par exemple) $HOME/.dotnet/toolsà la variable d’environnement PATH en utilisant n’importe quelle méthode que votre coquille fournit pour mettre à jour les variables de l’environnement.In that case, append the tool location (for example, $HOME/.dotnet/tools) to the PATH environment variable by using whatever method your shell provides for updating environment variables. Pour plus d’informations, voir .NET Core tools.For more information, see .NET Core tools.

  • Outils locauxLocal tools

    Si vous essayez d’exécuter un outil local, vérifiez qu’il existe un fichier manifeste appelé dotnet-tools.json dans l’annuaire actuel ou l’un de ses répertoires parent.If you're trying to run a local tool, verify that there's a manifest file called dotnet-tools.json in the current directory or any of its parent directories. Ce fichier peut également vivre sous un dossier nommé .config n’importe où dans la hiérarchie du dossier de projet, au lieu du dossier de racine.This file can also live under a folder named .config anywhere in the project folder hierarchy, instead of the root folder. Si dotnet-tools.json existe, ouvrez-le et vérifiez l’outil que vous essayez d’exécuter.If dotnet-tools.json exists, open it and check for the tool you're trying to run. Si le fichier ne contient "isRoot": truepas d’entrée pour , puis vérifiez également plus loin dans la hiérarchie de fichiers pour les fichiers manifestes d’outils supplémentaires.If the file doesn't contain an entry for "isRoot": true, then also check further up the file hierarchy for additional tool manifest files.

    Si vous essayez d’exécuter un outil .NET Core qui a été installé avec un chemin spécifié, vous devez inclure ce chemin lors de l’utilisation de l’outil.If you're trying to run a .NET Core tool that was installed with a specified path, you need to include that path when using the tool. Un exemple d’utilisation d’un outil installé est :An example of using a tool-path installed tool is:

    ..\<toolDirectory>\dotnet-<toolName>
    

Temps d’exécution non trouvéRuntime not found

.NET Les outils de base sont des applications dépendantes du cadre,ce qui signifie qu’ils s’appuient sur un temps d’exécution .NET Core installé sur votre machine..NET Core tools are framework-dependent applications, which means they rely on a .NET Core runtime installed on your machine. Si le temps d’exécution prévu n’est pas trouvé, ils suivent les règles normales .NET Core runtime roll-forward telles que:If the expected runtime isn't 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.
  • S’il n’y a pas de temps d’exécution correspondant avec un numéro de version majeur et mineur correspondant, la prochaine version mineure supérieure est utilisée.If there's 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. Ainsi, les outils .NET Core créés à l’aide de versions de prévisualisation doivent être reconstruits et republiés par l’auteur et réinstallés.So, .NET Core tools created using preview versions must be rebuilt and republished by the author and reinstalled.

Roll-forward ne se produira pas par défaut dans deux scénarios courants :Roll-forward won't occur by default in two common scenarios:

  • Seules des versions inférieures de l’exécution sont disponibles.Only lower versions of the runtime are available. Roll-forward ne sélectionne que les versions ultérieures de l’exécution.Roll-forward only selects later versions of the runtime.
  • Seules des versions majeures supérieures du temps d’exécution sont disponibles.Only higher major versions of the runtime are available. Roll-forward ne franchit pas les frontières des versions majeures.Roll-forward doesn't cross major version boundaries.

Si une application ne peut pas trouver un temps d’exécution approprié, elle ne s’exécute pas et signale une erreur.If an application can't find an appropriate runtime, it fails to run and reports an error.

Vous pouvez savoir quels arrêts .NET Core sont installés sur votre machine à l’aide d’une des commandes suivantes :You can find out which .NET Core runtimes are installed on your machine using one of the following commands:

dotnet --list-runtimes
dotnet --info

Si vous pensez que l’outil doit prendre en charge la version en temps d’exécution que vous avez actuellement installé, vous pouvez contacter l’auteur de l’outil et voir s’ils peuvent mettre à jour le numéro de version ou multi-cible.If you think the tool should support the runtime version you currently have installed, you can contact the tool author and see if they can update the version number or multi-target. Une fois qu’ils ont recompilé et réédité leur paquet d’outils à NuGet avec un numéro de version mis à jour, vous pouvez mettre à jour votre copie.Once they've recompiled and republished their tool package to NuGet with an updated version number, you can update your copy. Bien que cela ne se produise pas, la solution la plus rapide pour vous est d’installer une version du temps d’exécution qui fonctionnerait avec l’outil que vous essayez d’exécuter.While that doesn't happen, the quickest solution for you is to install a version of the runtime that would work with the tool you're trying to run. Pour télécharger une version spécifique .NET Core runtime, visitez la page de téléchargement .NET Core.To download a specific .NET Core runtime version, visit the .NET Core download page.

Si vous installez le SDK core .NET à un emplacement DOTNET_ROOT non par défaut, dotnet vous devez définir la variable d’environnement à l’annuaire qui contient l’exécutable.If you install the .NET Core SDK to a non-default location, you need to set the environment variable DOTNET_ROOT to the directory that contains the dotnet executable.

l’installation d’outil de base de net-NET échoue.NET Core tool installation fails

Il ya un certain nombre de raisons pour lesquelles l’installation d’un outil mondial ou local .NET Core peut échouer.There are a number of reasons the installation of a .NET Core global or local tool may fail. Lorsque l’installation de l’outil échoue, vous verrez un message similaire à celui suivant :When the tool installation fails, you'll see a message similar to the following one:

Tool '{0}' failed to install. This failure may have been caused by:

* You are attempting to install a preview release and did not use the --version option to specify the version.
* A package by this name was found, but it was not a .NET Core tool.
* The required NuGet feed cannot be accessed, perhaps because of an Internet connection problem.
* You mistyped the name of the tool.

For more reasons, including package naming enforcement, visit https://aka.ms/failure-installing-tool

Pour aider à diagnostiquer ces défaillances, les messages NuGet sont affichés directement à l’utilisateur, ainsi que le message précédent.To help diagnose these failures, NuGet messages are shown directly to the user, along with the previous message. Le message NuGet peut vous aider à identifier le problème.The NuGet message may help you identify the problem.

Exécution de nommage de paquetPackage naming enforcement

Microsoft a changé ses conseils sur l’ID package pour les outils, résultant en un certain nombre d’outils ne sont pas trouvés avec le nom prévu.Microsoft has changed its guidance on the Package ID for tools, resulting in a number of tools not being found with the predicted name. La nouvelle orientation est que tous les outils Microsoft soient préfixés avec "Microsoft".The new guidance is that all Microsoft tools be prefixed with "Microsoft." Ce préfixe est réservé et ne peut être utilisé que pour les paquets signés avec un certificat autorisé par Microsoft.This prefix is reserved and can only be used for packages signed with a Microsoft authorized certificate.

Pendant la transition, certains outils Microsoft auront l’ancienne forme de l’ID paquet, tandis que d’autres auront le nouveau formulaire:During the transition, some Microsoft tools will have the old form of the package ID, while others will have the new form:

dotnet tool install -g Microsoft.<toolName>
dotnet tool install -g <toolName>

Au fur et à mesure que les identifiants de paquet sont mis à jour, vous devrez modifier le nouvel ID du paquet pour obtenir les dernières mises à jour.As package IDs are updated, you'll need to change to the new package ID to get the latest updates. Les paquets avec le nom simplifié de l’outil seront dépréciés.Packages with the simplified tool name will be deprecated.

Extrait des versionsPreview releases

  • Vous essayez d’installer une version de prévisualisation et n’avez pas utilisé l’option --version pour spécifier la version.You're attempting to install a preview release and didn't use the --version option to specify the version.

.NET Les outils de base qui sont en prévisualisation doivent être spécifiés avec une partie du nom pour indiquer qu’ils sont en prévisualisation..NET Core tools that are in preview must be specified with a portion of the name to indicate that they are in preview. Vous n’avez pas besoin d’inclure l’aperçu complet.You don't need to include the entire preview. En supposant que les numéros de version sont dans le format prévu, vous pouvez utiliser quelque chose comme l’exemple suivant:Assuming the version numbers are in the expected format, you can use something like the following example:

dotnet tool install -g --version 1.1.0-pre <toolName>

Le paquet n’est pas un outil .NET CorePackage isn't a .NET Core tool

  • Un paquet NuGet de ce nom a été trouvé, mais ce n’était pas un outil .NET Core.A NuGet package by this name was found, but it wasn't a .NET Core tool.

Si vous essayez d’installer un package NuGet qui est un paquet NuGet régulier et non un outil .NET Core, vous verrez une erreur similaire à ce qui suit:If you try to install a NuGet package that is a regular NuGet package and not a .NET Core tool, you'll see an error similar to the following:

NU1212: Combinaison de projets invalides pour <ToolName>.NU1212: Invalid project-package combination for <ToolName>. Le style du projet DotnetToolReference ne peut contenir que des références du type DotnetTool.DotnetToolReference project style can only contain references of the DotnetTool type.

L’alimentation NuGet ne peut pas être consultéeNuGet feed can't be accessed

  • Le flux NuGet requis ne peut pas être consulté, peut-être en raison d’un problème de connexion Internet.The required NuGet feed can't be accessed, perhaps because of an Internet connection problem.

L’installation d’outils nécessite l’accès à l’alimentation NuGet qui contient le paquet d’outils.Tool installation requires access to the NuGet feed that contains the tool package. Il échoue si le flux n’est pas disponible.It fails if the feed isn't available. Vous pouvez modifier nuget.configles flux nuget.config avec, demander un fichier --add-source spécifique, ou spécifier des flux supplémentaires avec le commutateur.You can alter feeds with nuget.config, request a specific nuget.config file, or specify additional feeds with the --add-source switch. Par défaut, NuGet lance une erreur pour tout flux qui ne peut pas se connecter.By default, NuGet throws an error for any feed that can't connect. Le --ignore-failed-sources drapeau peut sauter ces sources non accessibles.The flag --ignore-failed-sources can skip these non-reachable sources.

Identifiant de paquet incorrectPackage ID incorrect

  • Vous avez mal interprété le nom de l’outil.You mistyped the name of the tool.

Une raison commune de l’échec est que le nom de l’outil n’est pas correct.A common reason for failure is that the tool name isn't correct. Cela peut se produire en raison de mauvaisty, ou parce que l’outil a bougé ou a été déprécié.This can happen because of mistyping, or because the tool has moved or been deprecated. Pour les outils sur NuGet.org, une façon de s’assurer que vous avez le nom correct est de rechercher l’outil à NuGet.org et copier la commande d’installation.For tools on NuGet.org, one way to ensure you have the name correct is to search for the tool at NuGet.org and copy the installation command.

Voir aussiSee also