Verwalten von .NET-Tools

Artikel
07/25/2023

Dieser Artikel gilt für: ✔️ .NET Core 2.1 SDK und höher.

Ein .NET-Tool ist ein spezielles NuGet-Paket, das eine Konsolenanwendung enthält. Sie können ein Tool mit folgenden Verfahren auf dem Computer installieren:

Als globales Tool.

Die Binärdateien für das Tool werden in einem Standardverzeichnis installiert, das der Umgebungsvariablen PATH hinzugefügt wird. Sie können das Tool aus einem beliebigen Verzeichnis auf dem Computer aufrufen, ohne seinen Speicherort anzugeben. Eine Version eines Tools wird für alle Verzeichnisse auf dem Computer verwendet.
Als globales Tool an einem benutzerdefinierten Speicherort (auch „Toolpfadtool“ genannt).

Die Binärdateien für das Tool werden an einem von Ihnen angegebenen Speicherort installiert. Sie können das Tool im Installationsverzeichnis aufrufen, oder indem Sie das Verzeichnis mit dem Befehlsnamen angeben oder das Verzeichnis der Umgebungsvariablen PATH hinzufügen. Eine Version eines Tools wird für alle Verzeichnisse auf dem Computer verwendet.
Als lokales Tool (ab .NET Core SDK 3.0).

Die Binärdateien des Tools werden in einem Standardverzeichnis installiert. Sie können das Tool im Installationsverzeichnis oder einem seiner Unterverzeichnisse aufrufen. Verschiedene Verzeichnisse können unterschiedliche Versionen desselben Tools verwenden.

Die .NET-CLI nutzt Manifestdateien, um nachzuverfolgen, welche Tools lokal in einem Verzeichnis installiert sind. Wenn die Manifestdatei im Stammverzeichnis eines Quellcoderepositorys gespeichert ist, kann ein Mitwirkender das Repository klonen und einen einzelnen .NET-CLI-Befehl aufrufen, mit dem alle in den Manifestdateien aufgeführten Tools installiert werden.

Wichtig

.NET-Tools werden mit voller Vertrauenswürdigkeit ausgeführt. Installieren Sie nur .NET-Tools von Autoren, denen Sie vertrauen.

.NET-Tools funktionieren möglicherweise nicht ordnungsgemäß, wenn .NET über Snap installiert wurde.

Suchen eines Tools

Es folgen einige Möglichkeiten, Tools zu finden:

Suchen Sie mit dem Befehl dotnet tool search nach einem Tool, das auf „NuGet.org“ veröffentlicht wird.
Durchsuchen Sie die NuGet-Website mithilfe des Pakettypfilters „.NET tool“. Weitere Informationen finden Sie unter Finding and choosing packages (Suchen und Auswählen von Paketen).
Sehen Sie sich den Quellcode der vom ASP.NET Core-Team im GitHub-Repository dotnet/aspnetcore im Verzeichnis „Tools“ erstellten Tools an.
Weitere Informationen zu Diagnosetools finden Sie unter .NET-Diagnosetools.

Überprüfen des Autors und der Statistiken

Da .NET-Tools mit voller Vertrauenswürdigkeit ausgeführt und globale Tools der Umgebungsvariablen PATH hinzugefügt werden, können sie sehr leistungsfähig sein. Laden Sie keine Tools von Personen herunter, denen Sie nicht vertrauen.

Wenn das Tool auf NuGet gehostet wird, können Sie den Autor und seine Statistiken überprüfen, indem Sie nach dem Tool suchen.

Installieren eines globalen Tools

Um ein Tool als globales Tool zu installieren, verwenden Sie, wie im folgenden Beispiel gezeigt, mit dotnet tool install die Option -g oder --global:

dotnet tool install -g dotnetsay

Die Ausgabe zeigt den zum Aufrufen des Tools verwendeten Befehl und die installierte Version, ähnlich wie im folgenden Beispiel:

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

Hinweis

Standardmäßig stellt die Architektur der zu installierenden .NET-Binärdateien die derzeit ausgeführte Betriebssystemarchitektur dar. Informationen zum Angeben einer anderen Betriebssystemarchitektur finden Sie unter dotnet tool install, --arch option.

Der Standardspeicherort der Binärdateien eines Tools hängt vom Betriebssystem ab:

BS	Path
Linux/macOS	`$HOME/.dotnet/tools`
Window	`%USERPROFILE%\.dotnet\tools`

Dieser Speicherort wird dem Benutzerpfad hinzugefügt, wenn das SDK zum ersten Mal ausgeführt wird. Daher können globale Tools von jedem Verzeichnis aus aufgerufen werden, ohne den Speicherort des Tools anzugeben.

Der Toolzugriff ist benutzerspezifisch und nicht global für Computer. Ein globales Tool ist nur für den Benutzer verfügbar, der das Tool installiert hat.

Installieren eines globalen Tools an einem benutzerdefinierten Speicherort

Um ein Tool als globales Tool an einem benutzerdefinierten Speicherort zu installieren, verwenden Sie, wie in den folgenden Beispielen gezeigt, mit dotnet tool install die Option --tool-path:

Unter Windows:

dotnet tool install dotnetsay --tool-path c:\dotnet-tools

Unter Linux oder macOS:

dotnet tool install dotnetsay --tool-path ~/bin

Das .NET SDK fügt diesen Speicherort nicht automatisch der Umgebungsvariablen PATH hinzu. Zum Aufrufen eines Toolpfadtools müssen Sie sicherstellen, dass der Befehl verfügbar ist, indem Sie eine der folgenden Methoden verwenden:

Fügen Sie das Installationsverzeichnis der Umgebungsvariablen PATH hinzu.
Geben Sie den vollständigen Pfad zum Tool an, wenn Sie es aufrufen.
Rufen das Tool im Installationsverzeichnis auf.

Installieren eines lokalen Tools

Gilt ab .NET Core 3.0 SDK.

Um ein Tool nur für den lokalen Zugriff (für das aktuelle Verzeichnis und Unterverzeichnisse) zu installieren, müssen Sie es der Manifestdatei des Tools hinzufügen. Führen Sie den Befehl dotnet new tool-manifest aus, um eine Manifestdatei für das Tool zu erstellen:

dotnet new tool-manifest

Mit diesem Befehl wird im Verzeichnis .config eine Manifestdatei mit dem Namen dotnet-tools.json erstellt. Um der Manifestdatei ein lokales Tool hinzuzufügen, verwenden Sie den Befehl dotnet tool installohne die Optionen --global und --tool-path, wie im folgenden Beispiel gezeigt:

dotnet tool install dotnetsay

Die Befehlsausgabe zeigt, in welcher Manifestdatei sich das neu installierte Tool befindet, ähnlich wie im folgenden Beispiel:

You can invoke the tool from this directory using the following command:
dotnet tool run dotnetsay
Tool 'dotnetsay' (version '2.1.4') was successfully installed.
Entry is added to the manifest file /home/name/botsay/.config/dotnet-tools.json.

Das folgende Beispiel zeigt eine Manifestdatei, in der zwei lokale Tools installiert sind:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    },
    "dotnetsay": {
      "version": "2.1.3",
      "commands": [
        "dotnetsay"
      ]
    }
  }
}

In der Regel fügen Sie ein lokales Tool zum Stammverzeichnis des Repositorys hinzu. Nach dem Einchecken der Manifestdatei im Repository erhalten Entwickler, die Code aus dem Repository auschecken, die neueste Manifestdatei. Um alle in der Manifestdatei aufgeführten Tools zu installieren, führen sie den Befehl dotnet tool restore aus:

dotnet tool restore

Die Ausgabe gibt die wiederhergestellten Tools an:

Tool 'botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

Installieren einer bestimmten Toolversion

Um eine Vorab- oder bestimmte Version eines Tools zu installieren, geben Sie die Versionsnummer mit der Option --version an, wie im folgenden Beispiel gezeigt:

dotnet tool install dotnetsay --version 2.1.3

Um eine Vorabversion des Tools ohne Angabe der genauen Versionsnummer zu installieren, verwenden Sie die Option --version, und geben Sie einen Platzhalter an, wie im folgenden Beispiel gezeigt:

dotnet tool install --global dotnetsay --version "*-rc*"

Verwenden eines Tools

Der Befehl zum Aufrufen eines Tools kann sich vom Namen des Pakets, das Sie installieren, unterscheiden. Um alle derzeit für den aktuellen Benutzer auf dem Computer installierten Tools anzuzeigen, führen Sie den Befehl dotnet tool list aus:

dotnet tool list

Die Ausgabe zeigt die Version und den Befehl jedes Tools, ähnlich wie im folgenden Beispiel:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
botsay          1.0.0        botsay         /home/name/repository/.config/dotnet-tools.json
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Wie im obigen Beispiel gezeigt, enthält die Liste lokale Tools. Verwenden Sie die Option --global, um globale Tools anzuzeigen. Verwenden Sie die Option --tool-path, um Tools für den Toolpfad anzuzeigen.

Verwenden Sie zum Auflisten eines bestimmten Tools den Dotnet-Toolliste <PACKAGE_ID> Befehl:

dotnet tool list dotnetsay

Die Ausgabe listet dieses Tool nur auf, wenn es installiert ist, ähnlich wie im folgenden Beispiel:

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

Aufrufen eines globalen Tools

Verwenden Sie für globale Tools den Tool-Befehl eigenständig. Wenn der Befehl beispielsweise dotnetsay oder dotnet-doc lautet, rufen Sie das globale Tool mit Folgendem auf:

dotnetsay
dotnet-doc

Wenn der Befehl mit dem Präfix dotnet- beginnt, können Sie das Tool alternativ auch mit dem Befehl dotnet ohne das Präfix des tool-Befehls aufrufen. Wenn der Befehl z. B. dotnet-doc lautet, wird das Tool mit dem folgenden Befehl aufgerufen:

dotnet doc

Im folgenden Szenario können Sie jedoch nicht den Befehl dotnet verwenden, um ein globales Tool aufzurufen:

Für ein globales Tool und ein lokales Tool gilt der gleiche Befehl mit dem Präfix dotnet-.
Sie möchten das globale Tool in einem Verzeichnis aufrufen, das im Geltungsbereich des lokalen Tools liegt.

In diesem Fall rufen dotnet doc und dotnet dotnet-doc das lokale Tool auf. Um das globale Tool aufzurufen, verwenden Sie den Befehl eigenständig:

dotnet-doc

Aufrufen eines Toolpfadtools

Um ein globales Tool aufzurufen, das mit der Option tool-path installiert wurde, stellen Sie sicher, dass der Befehl verfügbar ist, was weiter oben in diesem Artikel erläutert wurde.

Aufrufen eines lokalen Tools

Um ein lokales Tool aufzurufen, müssen Sie im Installationsverzeichnis den Befehl dotnet ausführen. Sie können die Langform (dotnet tool run <COMMAND_NAME>) oder Kurzform (dotnet <COMMAND_NAME>) verwenden, wie in den folgenden Beispielen gezeigt:

dotnet tool run dotnetsay
dotnet dotnetsay

Wenn dem Befehl das Präfix dotnet- vorangestellt ist, können Sie das Präfix beim Aufruf des Tools einschließen oder weglassen. Wenn der Befehl z. B. dotnet-doc lautet, ruft eines der folgenden Beispiele das lokale Tool auf:

dotnet tool run dotnet-doc
dotnet dotnet-doc
dotnet doc

Aktualisieren eines Tools

Das Aktualisieren eines Tools umfasst das Deinstallieren und Neuinstallieren mit der neuesten stabilen Version. Verwenden Sie zum Aktualisieren eines Tools den Befehl dotnet tool update mit derselben Option, die Sie auch zur Installation des Tools verwendet haben:

dotnet tool update --global <packagename>
dotnet tool update --tool-path <packagename>
dotnet tool update <packagename>

Bei einem lokalen Tool sucht das SDK im aktuellen Verzeichnis und den übergeordneten Verzeichnissen, um die erste Manifestdatei zu finden, die die Paket-ID enthält. Wenn es in keiner Manifestdatei keine solche Paket-ID gibt, fügt das SDK der nächstgelegenen Manifestdatei einen neuen Eintrag hinzu.

Deinstallieren eines Tools

Deinstallieren Sie ein Tool mit dem Befehl dotnet tool uninstall mit der gleichen Option, die Sie zur Installation des Tools verwendet haben:

dotnet tool uninstall --global <packagename>
dotnet tool uninstall --tool-path <packagename>
dotnet tool uninstall <packagename>

Bei einem lokalen Tool sucht das SDK im aktuellen Verzeichnis und den übergeordneten Verzeichnissen, um die erste Manifestdatei zu finden, die die Paket-ID enthält.

Hilfe und Problembehandlung

Wenn ein Tool nicht installiert oder ausgeführt werden kann, finden Sie unter Behandlung von Problemen bei der Nutzung von .NET-Tools weitere Informationen. Eine Liste der verfügbaren dotnet tool-Befehle und -Parameter können Sie mit dem --help-Parameter abrufen:

dotnet tool --help

Um Anweisungen zur Nutzung des Tools zu erhalten, geben Sie einen der folgenden Befehle ein, oder besuchen Sie die Website des Tools:

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