Verwalten von .NET-Tools

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

Ein .NET-Tool ist ein spezielles NuGet-Paket, das eine Konsolenanwendung enthält. Sie können ein Tool auf Ihrem Computer auf folgende Weise installieren:

  • Als globales Tool.

    Die Toolbinärdateien werden in einem Standardverzeichnis installiert, das der PATH-Umgebungsvariablen 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 aus dem Installationsverzeichnis aufrufen, indem Sie das Verzeichnis mit dem Befehlsnamen angeben oder das Verzeichnis der PATH-Umgebungsvariablen hinzufügen. Eine Version eines Tools wird für alle Verzeichnisse auf dem Computer verwendet.

  • Als lokales Tool (gilt für .NET Core SDK 3.0 und höhere Versionen).

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

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

Wichtig

.NET-Tools werden mit voller Vertrauenswürdigkeit ausgeführt. Installieren Sie kein .NET-Tool, es sei denn, Sie vertrauen dem Autor.

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

Suchen eines Tools

Es folgen einige Möglichkeiten, Tools zu finden:

Überprüfen des Autors und der Statistiken

.NET-Tools können leistungsfähig sein, da sie voll vertrauenswürdig ausgeführt werden und globale Tools der UMGEBUNGsvariable PATH hinzugefügt werden. 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.

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

Betriebssystem Pfad
Linux/macOS $HOME/.dotnet/tools
Windows %USERPROFILE%\.dotnet\tools

Dieser Speicherort wird dem Pfad des Benutzers hinzugefügt, wenn das SDK zum ersten Mal ausgeführt wird. Daher können globale Tools aus einem beliebigen Verzeichnis aufgerufen werden, ohne den Toolspeicherort anzugeben.

Der Zugriff auf Tools ist benutzerspezifisch und gilt nicht global auf dem 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

Wenn Sie ein Tool als globales Tool an einem benutzerdefinierten Speicherort installieren möchten, verwenden Sie die --tool-path Option dotnet tool install (wie in den folgenden Beispielen gezeigt):

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. Um ein Toolpfadtool aufzurufen, 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.

Wenn Sie ein Tool nur für den lokalen Zugriff (für das aktuelle Verzeichnis und die Unterverzeichnisse) installieren möchten, müssen Sie das Tool einer Toolmanifestdatei 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 das neu installierte Tool vorhanden ist, ä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, den Sie zum Aufrufen eines Tools verwenden, unterscheidet sich möglicherweise vom Namen des Pakets, das Sie installieren. 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 vorherigen Beispiel gezeigt, werden in der Liste lokale Tools angezeigt. Verwenden Sie die --global Option, um globale Tools anzuzeigen. Verwenden Sie die --tool-path Option, um Toolpfadtools anzuzeigen.

Aufrufen eines globalen Tools

Verwenden Sie für globale Tools den Tool-Befehl eigenständig. Wenn der Befehl z. B. oder dotnet-docistdotnetsay, verwenden Sie dies, um das globale Tool aufzurufen:

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 aus einem Verzeichnis aufrufen, das sich im Bereich des lokalen Tools befindet.

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 mithilfe der tool-path Option installiert wird, stellen Sie sicher, dass der Befehl wie weiter oben in diesem Artikel erläutert verfügbar ist.

Aufrufen eines lokalen Tools

Um ein lokales Tool aufzurufen, müssen Sie den dotnet Befehl aus dem Installationsverzeichnis verwenden. 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 nach der ersten Manifestdatei, die die Paket-ID enthält. Wenn keine solche Paket-ID in einer Manifestdatei vorhanden ist, 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 zum Installieren 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 nach der ersten Manifestdatei, 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

Siehe auch