Résoudre les problèmes d’utilisation des outils .NET

  • Article

Vous pouvez rencontrer des problèmes lors de la tentative d’installation ou d’exécution d’un outil .NET, qui peut être un outil global ou un outil local. Cet article décrit les causes racines courantes et certaines solutions possibles.

Échec de l’exécution de l’outil .NET installé

Lorsqu’un outil .NET ne parvient pas à s’exécuter, vous avez probablement rencontré l’un des problèmes suivants :

Fichier exécutable introuvable

Si le fichier exécutable est introuvable, vous verrez un message de ce type s’afficher :

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 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 la façon dont vous appelez l’outil. Le tableau suivant décrit le format :

Format de nom exécutable Format d’appel
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>

Outils globaux

Il est possible d’installer des outils globaux dans le répertoire par défaut ou à un emplacement spécifique. Les répertoires par défaut sont :

Système d''exploitation Chemin d’accès
Linux/mac OS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

Si vous essayez d’exécuter un outil global, vérifiez que la variable d’environnement PATH sur votre ordinateur contient le chemin d’accès où vous avez installé l’outil global et que l’exécutable se trouve dans ce chemin.

CLI .NET essaie d’ajouter l’emplacement par défaut à la variable d’environnement PATH lors de sa première utilisation. Toutefois, il y a des cas où il n’est pas possible d’ajouter automatiquement l’emplacement à PATH :

  • Si vous utilisez Linux et que vous avez installé le SDK .NET à l’aide de fichiers .tar.gz et non pas apt-get ou rpm.
  • Si vous utilisez macOS 10.15 « Catalina » ou des versions ultérieures.
  • Si vous utilisez macOS 10.14 « Mojave » ou des versions antérieures et que vous avez installé le SDK .NET à l’aide de fichiers .tar.gz et non pas .pkg.
  • Si vous avez installé le SDK .NET Core 3.0 et que vous avez défini la DOTNET_ADD_GLOBAL_TOOLS_TO_PATH variable d’environnement sur false.
  • Si vous avez installé le SDK .NET Core 2.2 ou des versions antérieures et que vous avez défini la DOTNET_SKIP_FIRST_TIME_EXPERIENCE variable d’environnement sur true.

Dans ces genres de cas ou si vous avez spécifié l’option --tool-pathpendant l’installation l’outil dotnet, la variable d’environnement PATH sur votre ordinateur ne contient pas automatiquement le chemin d’accès où vous avez installé l’outil global. Dans ce cas, ajoutez l’emplacement de l’outil (par exemple, $HOME/.dotnet/tools) à la variable d’environnement PATH à l’aide de la méthode que votre interpréteur de commandes fournit pour mettre à jour les variables d’environnement. Pour plus d’informations, consultez Outils .NET.

Outils locaux

Si vous essayez d’exécuter un outil local, vérifiez qu’il existe un fichier manifeste appelé dotnet-tools.json dans le répertoire actif ou dans l’un de ses répertoires parents. Ce fichier peut également se trouver sous un dossier nommé .config n’importe où dans la hiérarchie des dossiers du projet, plutôt que dans le dossier racine. Si dotnet-tools.json existe, ouvrez-le et recherchez l’outil que vous essayez d’exécuter. Si le fichier ne contient pas d’entrée pour "isRoot": true, vérifiez également plus en haut dans la hiérarchie de fichiers pour obtenir d’autres fichiers manifestes d’outils.

Si vous essayez d’exécuter un outil .NET qui a été installé avec un chemin spécifié, vous devez inclure ce chemin lors de l’utilisation de l’outil. Voici un exemple d’utilisation d’un outil installé :

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

Runtime introuvable

Les outils .NET sont des applications dépendant du framework, ce qui signifie qu’ils reposent sur un runtime .NET installé sur votre ordinateur. Si le runtime attendu est introuvable, ils suivent les règles normales de restauration par progression du runtime .NET, à savoir :

  • Une application restaure par progression le correctif le plus élevé de la version principale et secondaire spécifiée.
  • En l’absence de runtime correspondant à un numéro de version principale et secondaire, la version secondaire supérieure suivante est utilisée.
  • Une restauration par progression ne se produit pas entre des préversions du runtime ou entre des préversions et des versions finales. Par conséquent, les outils .NET créés à l’aide de préversions doivent être regénérés et republiés par l’auteur, puis réinstallés.

La restauration par progression ne se produit pas par défaut dans deux scénarios courants :

  • Seules les versions inférieures du runtime sont disponibles. La restauration par progression sélectionne uniquement les versions ultérieures du runtime.
  • Seules les versions majeures supérieures du runtime sont disponibles. La restauration par progression ne franchit pas les limites des versions majeures.

Si une application ne trouve pas un runtime approprié, elle ne parvient pas à s’exécuter et signale une erreur.

Vous pouvez déterminer quels runtimes .NET sont installés sur votre ordinateur à l’aide de l’une des commandes suivantes :

dotnet --list-runtimes
dotnet --info

Si vous pensez que l’outil doit prendre en charge la version du runtime que vous avez actuellement installée, vous pouvez contacter l’auteur de l’outil pour savoir s’il/elle peut mettre à jour le numéro de version ou multi-cible. Une fois que l’auteur a recompilé et republié son package d’outils dans NuGet avec un numéro de version mis à jour, vous pouvez mettre à jour votre copie. Bien que ceci n’ait pas lieu, la solution la plus rapide consiste à installer une version du runtime qui fonctionne avec l’outil que vous essayez d’exécuter. Pour télécharger une version du runtime .NET spécifique, consultez la page de téléchargement .NET.

Si vous installez le SDK .NET à un emplacement autre que celui par défaut, vous devez définir la variable DOTNET_ROOT d’environnement sur le répertoire qui contient l’exécutable dotnet.

Échec de l’installation de l’outil .NET

Il existe plusieurs raisons pour lesquelles l’installation d’un outil .NET global ou local peut échouer. Lorsque l’installation de l’outil échoue, un message semblable au suivant s’affiche :

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 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 faciliter le diagnostic de ces échecs, l’utilisateur voit directement les messages NuGet, ainsi que le message précédent. Le message NuGet peut vous aider à identifier le problème.

Application de l’affectation de noms de package

Microsoft a modifié son aide sur l’ID de package pour les outils, ce qui a entraîné l’impossibilité de trouver un certain nombre d’outils avec le nom prédit. Avec la nouvelle aide, tous les outils Microsoft sont précédés de « Microsoft ». Ce préfixe est réservé et ne peut être utilisé que pour les packages signés d’un certificat autorisé par Microsoft.

Pendant la transition, certains outils Microsoft auront l’ancien formulaire de l’ID de package, tandis que d’autres auront le nouveau formulaire :

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

À mesure que les ID de package sont mis à jour, vous devez passer au nouvel ID de package pour obtenir les dernières mises à jour. Les packages portant le nom de l’outil simplifié seront déconseillés.

Versions précommerciales

  • Vous tentez d’installer une version précommerciale et vous n’avez pas utilisé l’option --version pour spécifier la version.

Les outils .NET en préversion doivent être spécifiés avec une partie du nom pour indiquer qu’ils sont en préversion. Vous n’avez pas besoin d’inclure la préversion entière. En supposant que les numéros de version sont au format attendu, vous pouvez utiliser quelque chose comme l’exemple suivant :

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

Le package n’est pas un outil .NET

  • Un package NuGet de ce nom a été trouvé, mais il ne s’agissait pas d’un outil .NET.

Si vous essayez d’installer un package NuGet qui est un package NuGet standard et non pas un outil .NET, vous verrez une erreur similaire à ce qui suit :

NU1212 : combinaison projet-package non valide pour <toolName>. Le style de projet DotnetToolReference ne peut contenir que des références du type DotnetTool.

Impossible d’accéder au flux NuGet

  • Impossible d’accéder au flux NuGet requis, peut-être en raison d’un problème de connexion Internet.

L’installation de l’outil nécessite l’accès au flux NuGet qui contient le package d’outils. Elle échoue si le flux n’est pas disponible. Vous pouvez modifier les flux avec nuget.config, demander un fichier spécifique nuget.config ou spécifier des flux supplémentaires avec le commutateur --add-source. Par défaut, NuGet lève une erreur pour tout flux qui ne peut pas se connecter. L’indicateur --ignore-failed-sources peut ignorer ces sources inaccessibles.

ID de package incorrect

  • Vous avez mal tapé le nom de l’outil.

Une raison courante de l’échec est que le nom de l’outil n’est pas correct. Cela peut se produire en raison d’une saisie incorrecte ou parce que l’outil a été déplacé ou déconseillé. Pour les outils sur NuGet.org, une façon de vous assurer que votre nom est correct consiste à rechercher l’outil sur NuGet.org et à copier la commande d’installation.

401 (Non autorisé)

Vous avez probablement spécifié un autre flux NuGet et ce flux nécessite une authentification. Voici les différentes manières de résoudre cela :

  • Ajoutez le paramètre --ignore-failed-sources pour contourner l’erreur à partir du flux privé et utilisez le flux Microsoft public.

    Si vous installez un outil à partir du flux Microsoft NuGet, votre flux personnalisé retourne cette erreur avant que le flux NuGet de Microsoft ne retourne un résultat. L’erreur met fin à la demande, annulant toutes les autres demandes de flux en attente, qui peuvent être le flux NuGet de Microsoft. L’ajout de l’option --ignore-failed-sources entraîne le traitement de cette erreur par la commande comme un avertissement et autorise d’autres flux à traiter la demande.

    dotnet tool install -g --ignore-failed-sources <toolName>

  • Forcez le flux Microsoft NuGet avec le paramètre --add-source.

    Il est possible que le flux Microsoft NuGet public manque au fichier de configuration NuGet global ou local. Utilisez une combinaison des paramètres --add-source et --ignore-failed-sources pour éviter le flux erroné et vous fier au flux Microsoft public.

    dotnet tool install -g --add-source 'https://api.nuget.org/v3/index.json' --ignore-failed-sources <toolName>

  • Utilisez un paramètre de configuration --configfile <FILE> NuGet personnalisé.

    Créez un fichier nuget.config local avec uniquement le flux Microsoft NuGet public et référencez-le avec le paramètre --configfile :

    dotnet tool install -g --configfile "./nuget.config" <toolName>

    Voici un exemple de fichier de configuration :

    <?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" protocolVersion="3" />
  </packageSources>
</configuration>

    Pour plus d’informations, consultez Référence sur nuget.config.

  • Ajoutez les informations d’identification requises au fichier de configuration.

    Si vous savez que le package existe dans le flux configuré, fournissez les informations d’identification de connexion dans le fichier de configuration NuGet. Pour plus d’informations sur les informations d’identification dans un fichier de configuration NuGet, consultez la section packageSourceCredentials de la référence nuget.config.

Voir aussi