Behandeln von Problemen mit der Verwendung von .NET-Tools

Möglicherweise treten Probleme auf, wenn Sie versuchen, ein .NET-Tool zu installieren oder auszuführen, das ein globales Tool oder ein lokales Tool sein kann. In diesem Artikel werden die allgemeinen Ursachen und einige mögliche Lösungen beschrieben.

Das installierte .NET-Tool kann nicht ausgeführt werden.

Wenn ein .NET-Tool nicht ausgeführt werden kann, treten wahrscheinlich eines der folgenden Probleme auf:

• Die ausführbare Datei für das Tool wurde nicht gefunden.
• Die richtige Version der .NET-Laufzeit wurde nicht gefunden.

Ausführbare Datei nicht gefunden

Wenn die ausführbare Datei nicht gefunden wird, wird eine Meldung wie folgt angezeigt:

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.

Der Name der ausführbaren Datei bestimmt, wie Sie das Tool aufrufen. In der folgenden Tabelle wird das Format beschrieben:

Globale Werkzeuge

Globale Tools können im Standardverzeichnis oder an einem bestimmten Speicherort installiert werden. Die Standardverzeichnisse sind:

Wenn Sie versuchen, ein globales Tool auszuführen, überprüfen Sie, ob die PATH Umgebungsvariable auf Ihrem Computer den Pfad enthält, in dem Sie das globale Tool installiert haben und dass sich die ausführbare Datei in diesem Pfad befindet.

Die .NET-CLI versucht bei der ersten Verwendung, den Standardspeicherort der Umgebungsvariable „PATH“ hinzuzufügen. Es gibt jedoch einige Szenarien, in denen der Speicherort möglicherweise nicht automatisch zu PATH hinzugefügt wird:

• Wenn Sie Linux verwenden und das .NET SDK mit .tar.gz Dateien und nicht mit apt-get oder rpm installiert haben.
• Wenn Sie macOS 10.15 "Catalina" oder höhere Versionen verwenden.
• Wenn Sie macOS 10.14 "Mojave" oder frühere Versionen verwenden und das .NET SDK mit .tar.gz Dateien und nicht mit .pkginstalliert haben.
• Wenn Sie das .NET Core 3.0 SDK installiert haben und die umgebungsvariable DOTNET_ADD_GLOBAL_TOOLS_TO_PATH auf falsefestgelegt haben.
• Wenn Sie .NET Core 2.2 SDK oder frühere Versionen installiert haben und die umgebungsvariable DOTNET_SKIP_FIRST_TIME_EXPERIENCE auf truefestgelegt haben.

In diesen Szenarien oder wenn Sie die option --tool-pathbeim Installieren eines Dotnet-Toolsangegeben haben, enthält die PATH Umgebungsvariable auf Ihrem Computer nicht automatisch den Pfad, in dem Sie das globale Tool installiert haben. In diesem Fall fügen Sie den Speicherort des Tools (z. B. $HOME/.dotnet/tools) an die Umgebungsvariable PATH an, indem Sie die Methode verwenden, die Ihre Shell zur Aktualisierung der Umgebungsvariablen zur Verfügung stellt. Weitere Informationen finden Sie unter .NET-Tools.

Lokale Tools

Wenn Sie versuchen, ein lokales Tool auszuführen, stellen Sie sicher, dass es eine Manifestdatei namens dotnet-tools.json im aktuellen Verzeichnis oder in einem der übergeordneten Verzeichnisse gibt. Diese Datei kann auch unter einem Ordner namens .config überall in der Projektordnerhierarchie und nicht im Stammordner gespeichert werden. Wenn dotnet-tools.json vorhanden ist, öffnen Sie es, und suchen Sie nach dem Tool, das Sie ausführen möchten. Wenn die Datei keinen Eintrag für "isRoot": trueenthält, überprüfen Sie auch die Dateihierarchie auf zusätzliche Toolmanifestdateien.

Wenn Sie versuchen, ein .NET-Tool auszuführen, das mit einem angegebenen Pfad installiert wurde, müssen Sie diesen Pfad einschließen, wenn Sie das Tool verwenden. Beispiel für die Verwendung eines mit einem Toolpfad installierten Tools:

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

Laufzeit nicht gefunden

.NET-Tools sind frameworkabhängige Anwendungen, was bedeutet, dass sie auf einer .NET-Runtime basieren, die auf Ihrem Computer installiert ist. Wenn die erwartete Laufzeit nicht gefunden wird, folgen sie normalen .NET-Runtime-Roll-Forward-Regeln wie:

• Eine Anwendung wird auf die höchste Patchversion der angegebenen Haupt- und Nebenversion aktualisiert.
• Wenn keine übereinstimmende Runtime mit einer übereinstimmenden Haupt- und Nebenversion vorhanden ist, wird die nächsthöhere Nebenversion verwendet.
• Ein Rollforward findet nicht zwischen Vorschauversionen der Runtime oder Vorschauversionen und Releaseversionen statt. Daher müssen .NET-Tools, die mit Vorschauversionen erstellt wurden, neu erstellt und vom Autor erneut veröffentlicht und neu installiert werden.

Rollforward findet in zwei gängigen Szenarios nicht standardmäßig statt:

• Nur niedrigere Versionen der Laufzeit sind verfügbar. Beim Rollforward werden nur höhere Versionen der Runtime ausgewählt.
• Es sind nur höhere Hauptversionen der Runtime verfügbar. Roll-Forward überschreitet keine Grenzen zwischen Hauptversionen.

Wenn eine Anwendung keine geeignete Laufzeit finden kann, kann sie nicht ausgeführt werden und meldet einen Fehler.

Mit einem der folgenden Befehle können Sie herausfinden, welche .NET-Runtimes auf Ihrem Computer installiert sind:

dotnet --list-runtimes
dotnet --info

Wenn Sie der Meinung sind, dass das Tool die derzeit installierte Laufzeitversion unterstützen soll, können Sie sich an den Toolautor wenden und sehen, ob sie die Versionsnummer oder das Multiziel aktualisieren können. Nachdem sie das Toolpaket mit einer aktualisierten Versionsnummer in NuGet neu kompiliert und erneut veröffentlicht haben, können Sie Ihre Kopie aktualisieren. Das geschieht zwar nicht, aber die schnellste Lösung für Sie besteht darin, eine Version der Laufzeit zu installieren, die mit dem Tool funktioniert, das Sie ausführen möchten. Um eine bestimmte .NET-Laufzeitversion herunterzuladen, besuchen Sie die .NET-Downloadseite.

Wenn Sie das .NET SDK an einem nicht standardmäßigen Speicherort installieren, müssen Sie die Umgebungsvariable DOTNET_ROOT auf das Verzeichnis festlegen, das die dotnet ausführbare Datei enthält.

Fehler bei der .NET-Toolinstallation

Es gibt eine Reihe von Gründen, warum die Installation eines globalen .NET- oder lokalen Tools fehlschlägt. Wenn die Toolinstallation fehlschlägt, wird eine Meldung wie die folgende angezeigt:

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

Um diese Fehler zu diagnostizieren, werden NuGet-Nachrichten direkt dem Benutzer zusammen mit der vorherigen Nachricht angezeigt. Die NuGet-Nachricht kann Ihnen helfen, das Problem zu identifizieren.

• Durchsetzung der Benennung von Paketen
• Vorschau der Versionen
• Package ist kein .NET-Tool
• NuGet-Feed kann nicht zugegriffen werden
• Paket-ID falsch
• 401 (nicht autorisiert)

Erzwingung der Paketbenennung

Microsoft hat seine Anleitung zur Paket-ID für Tools geändert, was dazu führt, dass eine Reihe von Tools nicht mit dem vorhergesagten Namen gefunden wird. Die neue Anleitung besteht darin, dass allen Microsoft-Tools das Präfix "Microsoft" vorangestellt wird. Dieses Präfix ist reserviert und kann nur für Pakete verwendet werden, die mit einem autorisierten Microsoft-Zertifikat signiert sind.

Während des Übergangs verfügen einige Microsoft-Tools über die alte Form der Paket-ID, während andere über das neue Formular verfügen:

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

Wenn Paket-IDs aktualisiert werden, müssen Sie zur neuen Paket-ID wechseln, um die neuesten Updates zu erhalten. Pakete mit dem vereinfachten Toolnamen sind veraltet.

Vorschauversionen

• Sie versuchen, eine Vorschauversion zu installieren und haben die Option --version nicht zum Angeben der Version verwendet.

.NET-Tools, die sich in der Vorschau befinden, müssen mit einem Teil des Namens angegeben werden, um anzugeben, dass sie sich in der Vorschau befinden. Sie müssen die gesamte Vorschau nicht einschließen. Wenn sich die Versionsnummern im erwarteten Format befinden, können Sie etwas wie das folgende Beispiel verwenden:

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

Das Paket ist kein .NET-Tool.

• Ein NuGet-Paket mit diesem Namen wurde gefunden, aber es war kein .NET-Tool.

Wenn Sie versuchen, ein NuGet-Paket zu installieren, das ein normales NuGet-Paket und kein .NET-Tool ist, wird ein Fehler wie folgt angezeigt:

NU1212: Ungültige Projektpaketkombination für <toolName>. DotnetToolReference-Projektstil darf nur Verweise vom Typ DotnetTool enthalten.

Auf nuGet-Feed kann nicht zugegriffen werden

• Auf den erforderlichen NuGet-Feed kann nicht zugegriffen werden, möglicherweise aufgrund eines Internetverbindungsproblems.

Die Toolinstallation erfordert Zugriff auf den NuGet-Feed, der das Toolpaket enthält. Er schlägt fehl, wenn der Feed nicht verfügbar ist. Sie können Feeds mit nuget.configändern, eine bestimmte nuget.config Datei anfordern oder zusätzliche Feeds mit der Option --add-source angeben. Standardmäßig löst NuGet einen Fehler für jeden Feed aus, der keine Verbindung herstellen kann. Die Kennzeichnung --ignore-failed-sources kann diese nicht erreichbaren Quellen überspringen.

Paket-ID falsch

• Sie haben den Namen des Tools falsch eingegeben.

Ein häufiger Grund für fehler ist, dass der Toolname nicht korrekt ist. Dies kann aufgrund von Tippfehlern oder weil das Tool verschoben oder veraltet wurde, auftreten. Bei Tools auf NuGet.org können Sie sicherstellen, dass der Name korrekt ist, indem Sie bei NuGet.org nach dem Tool suchen und den Installationsbefehl kopieren.

401 (nicht autorisiert)

Höchstwahrscheinlich haben Sie einen alternativen NuGet-Feed angegeben, und dieser Feed erfordert Authentifizierung. Es gibt einige verschiedene Möglichkeiten, dies zu lösen:

• Fügen Sie den parameter --ignore-failed-sources hinzu, um den Fehler aus dem privaten Feed zu umgehen und den öffentlichen Microsoft-Feed zu verwenden.

  Wenn Sie ein Tool aus dem Microsoft NuGet-Feed installieren, gibt Ihr benutzerdefinierter Feed diesen Fehler zurück, bevor der NuGet-Feed von Microsoft ein Ergebnis zurückgibt. Der Fehler beendet die Anforderung und bricht alle anderen ausstehenden Feedanforderungen ab, was der NuGet-Feed von Microsoft sein könnte. Wenn Sie die Option --ignore-failed-sources hinzufügen, wird dieser Fehler durch den Befehl als Warnung behandelt, und andere Feeds können die Anforderung verarbeiten.

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

• Erzwingen Sie den Microsoft NuGet-Feed mit dem --add-source-Parameter.

  Es ist möglich, dass in der globalen oder lokalen NuGet-Konfigurationsdatei der öffentliche Microsoft NuGet-Feed fehlt. Verwenden Sie eine Kombination aus den parametern --add-source und --ignore-failed-sources, um den fehlerhaften Feed zu vermeiden und sich auf den öffentlichen Microsoft-Feed zu verlassen.

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

• Verwenden Sie eine benutzerdefinierte NuGet-Konfiguration, --configfile <FILE> Parameter.

  Erstellen Sie eine lokale nuget.config Datei mit nur dem öffentlichen Microsoft NuGet-Feed, und verweisen Sie darauf mit dem parameter --configfile:

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

  Hier ist eine Beispielkonfigurationsdatei:

  <?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>
  

  Weitere Informationen finden Sie unter nuget.config Referenz.

• Fügen Sie der Konfigurationsdatei die erforderlichen Anmeldeinformationen hinzu.

  Wenn Sie wissen, dass das Paket im konfigurierten Feed vorhanden ist, geben Sie die Anmeldeinformationen in der NuGet-Konfigurationsdatei an. Weitere Informationen zu Anmeldeinformationen in einer NuGet-Konfigurationsdatei finden Sie im Abschnitt packageSourceCredentials der Referenz zu „nuget.config“.

Siehe auch

• .NET Tools