Partager via

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 rencontrez probablement l’un des problèmes suivants :

Fichier exécutable introuvable

Si le fichier exécutable est introuvable, un message semblable à ce qui suit s’affiche :

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 du nom de fichier exécutable Format d’appel
dotnet-<toolName>.exe dotnet <toolName>
<toolName>.exe <toolName>

Outils globaux

Les outils globaux peuvent être installés dans le répertoire par défaut ou dans un emplacement spécifique. Les répertoires par défaut sont les suivants :

Système d’exploitation Chemin
Linux/macOS $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.

L’interface CLI .NET tente d’ajouter l’emplacement par défaut à la variable d’environnement PATH lors de sa première utilisation. Toutefois, il existe certains scénarios où l’emplacement peut ne pas être ajouté automatiquement à PATH :

  • Si vous utilisez Linux et que vous avez installé le Kit de développement logiciel (SDK) .NET à l'aide de fichiers .tar.gz plutôt que d'utiliser apt-get ou rpm.
  • Si vous utilisez macOS 10.15 « Catalina » ou version ultérieure.
  • Si vous utilisez macOS 10.14 « Mojave » ou versions antérieures, et que vous avez installé le Kit de développement logiciel (SDK) .NET à l’aide de .tar.gz fichiers et non .pkg.
  • Si vous avez installé le Kit de développement logiciel (SDK) .NET Core 3.0 et que vous avez défini la variable d’environnement DOTNET_ADD_GLOBAL_TOOLS_TO_PATH sur false.
  • Si vous avez installé le Kit de développement logiciel (SDK) .NET Core 2.2 ou versions antérieures, et que vous avez défini la variable d’environnement DOTNET_SKIP_FIRST_TIME_EXPERIENCE sur true.

Dans ces scénarios ou si vous avez spécifié l’option --tool-pathlors de l’installation d’un 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 des variables d’environnement. Pour plus d’informations, consultez les 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, au lieu du 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 la hiérarchie de fichiers pour obtenir des fichiers manifestes d’outils supplémentaires.

Si vous essayez d’exécuter un outil .NET installé avec un chemin d’accès 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 applications dépendantes du framework, ce qui signifie qu’ils s’appuient sur un runtime .NET installé sur votre ordinateur. Si le runtime attendu n’est pas trouvé, ils suivent les règles normales de restauration du runtime .NET, telles que :

  • Une application est transférée vers la version corrective la plus élevée de la version principale et mineure spécifiée.
  • S’il n’existe aucun runtime correspondant avec un numéro de version principale et secondaire correspondant, la prochaine version mineure supérieure est utilisée.
  • Les mises à jour ne se produisent pas entre les versions préliminaires de l'environnement d'exécution ou entre les versions préliminaires et les versions finales. Par conséquent, les outils .NET créés à l’aide de versions préliminaires doivent être reconstruits et republiés par l’auteur et réinstallés.

Le roll-forward 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 principales 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 et voir s’il peut mettre à jour le numéro de version ou multi-cible. Une fois qu’ils ont recompilé et republié leur package d’outils sur NuGet avec un numéro de version mis à jour, vous pouvez mettre à jour votre copie. Bien que cela ne se produise pas, 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 spécifique du runtime .NET, visitez la page de téléchargement .NET.

Si vous installez le Kit de développement logiciel (SDK) .NET à un emplacement autre que celui par défaut, vous devez définir la variable d’environnement DOTNET_ROOT 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 à celui 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 diagnostiquer ces échecs, les messages NuGet sont affichés directement à l’utilisateur, 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é ses instructions sur l'identifiant de package pour les outils, ce qui fait qu'un certain nombre d'outils ne sont pas trouvés sous le nom prévu. Les nouvelles consignes sont que tous les outils Microsoft doivent être précédés de « Microsoft ». Ce préfixe est réservé et ne peut être utilisé que pour les packages signés par un certificat autorisé par Microsoft.

Pendant la transition, certains outils Microsoft auront l’ancienne forme 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 préversion et 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 l'intégralité de l'aperçu. 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 n’était pas un outil .NET.

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

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

Le flux NuGet n’est pas accessible

  • Le flux NuGet requis n’est pas accessible, 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 des flux avec nuget.config, demander un fichier nuget.config spécifique ou spécifier des flux supplémentaires avec le commutateur --add-source. Par défaut, NuGet génère une erreur pour tout flux qui ne peut pas se connecter. L’indicateur --ignore-failed-sources peut ignorer ces sources non accessibles.

ID de paquet 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 mauvaise saisie, ou parce que l'outil a été déplacé ou est devenu obsolète. Pour les outils sur NuGet.org, une façon de vous assurer que le nom est correct consiste à rechercher l’outil à NuGet.org et à copier la commande d’installation.

401 (non autorisé)

Il est probable que vous avez spécifié un autre flux NuGet et que ce flux nécessite l’authentification. Il existe plusieurs façons de résoudre ce problème :

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

    Si vous installez un outil à partir du flux NuGet Microsoft, votre flux personnalisé retourne cette erreur avant que le flux NuGet de Microsoft retourne un résultat. L’erreur met fin à la demande, annulant toute autre demande de flux en attente, qui peut être le flux NuGet de Microsoft. L’ajout de l’option --ignore-failed-sources provoque le traitement de cette erreur comme un avertissement et permet à d’autres flux de traiter la requête.

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

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

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

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

  • Utilisez une configuration NuGet personnalisée, --configfile <FILE> paramètre.

    Créez un fichier nuget.config local avec uniquement le flux NuGet Microsoft 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 la référence 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