Verwalten von .NET Core-ToolsHow to manage .NET Core tools

Dieser Artikel gilt für: ✔️ .NET Core 2.1 SDK und neuere VersionenThis article applies to: ✔️ .NET Core 2.1 SDK and later versions

Ein .NET Core-Tool ist ein spezielles NuGet-Paket, das eine Konsolenanwendung enthält.A .NET Core tool is a special NuGet package that contains a console application. Ein Tool kann auf folgende Weisen auf dem Computer installiert werden:A tool can be installed on your machine in the following ways:

  • Als globales Tool.As a global tool.

    Die Binärdateien für das Tool werden in einem Standardverzeichnis installiert, das der Umgebungsvariablen PATH hinzugefügt wird.The tool binaries are installed in a default directory that is added to the PATH environment variable. Sie können das Tool aus einem beliebigen Verzeichnis auf dem Computer aufrufen, ohne seinen Speicherort anzugeben.You can invoke the tool from any directory on the machine without specifying its location. Eine Version eines Tools wird für alle Verzeichnisse auf dem Computer verwendet.One version of a tool is used for all directories on the machine.

  • Als globales Tool an einem benutzerdefinierten Speicherort (auch „Toolpfadtool“ genannt).As a global tool in a custom location (also known as a tool-path tool).

    Die Binärdateien für das Tool werden an einem von Ihnen angegebenen Speicherort installiert.The tool binaries are installed in a location that you specify. Sie können das Tool im Installationsverzeichnis aufrufen oder indem Sie das Verzeichnis mit dem Befehlsnamen angeben oder das Verzeichnis zur Umgebungsvariablen PATH hinzufügen.You can invoke the tool from the installation directory or by providing the directory with the command name or by adding the directory to the PATH environment variable. Eine Version eines Tools wird für alle Verzeichnisse auf dem Computer verwendet.One version of a tool is used for all directories on the machine.

  • Als lokales Tool (ab .NET Core SDK 3.0).As a local tool (applies to .NET Core SDK 3.0 and later).

    Die Binärdateien des Tools werden in einem Standardverzeichnis installiert.The tool binaries are installed in a default directory. Sie rufen das Tool im Installationsverzeichnis oder einem seiner Unterverzeichnisse auf.You invoke the tool from the installation directory or any of its subdirectories. Verschiedene Verzeichnisse können unterschiedliche Versionen desselben Tools verwenden.Different directories can use different versions of the same tool.

    Die .NET-CLI nutzt Manifestdateien, um nachzuverfolgen, welche Tools lokal in einem Verzeichnis installiert sind.The .NET CLI uses manifest files to keep track of which tools are installed as local to a directory. Wenn die Manifestdatei im Stammverzeichnis eines Quellcoderepositorys gespeichert ist, kann ein Mitwirkender das Repository klonen und einen einzelnen .NET Core-CLI-Befehl aufrufen, mit dem alle in den Manifestdateien aufgeführten Tools installiert werden.When the manifest file is saved in the root directory of a source code repository, a contributor can clone the repository and invoke a single .NET Core CLI command that installs all of the tools listed in the manifest files.

Wichtig

.NET Core-Tools werden mit voller Vertrauenswürdigkeit ausgeführt..NET Core tools run in full trust. Installieren Sie .NET Core-Tools nur von Autoren, denen Sie vertrauen.Do not install a .NET Core tool unless you trust the author.

Suchen eines ToolsFind a tool

Derzeit bietet .NET Core keine Suchfunktion für Tools.Currently, .NET Core doesn't have a tool search feature. Es folgen einige Möglichkeiten, Tools zu finden:Here are some ways to find tools:

Überprüfen des Autors und der StatistikenCheck the author and statistics

Da .NET Core-Tools mit voller Vertrauenswürdigkeit ausgeführt und globale Tools der Umgebungsvariablen PATH hinzugefügt werden, können sie sehr leistungsfähig sein.Since .NET Core tools run in full trust, and global tools are added to the PATH environment variable, they can be very powerful. Laden Sie keine Tools von Personen herunter, denen Sie nicht vertrauen.Don't download tools from people you don't trust.

Wenn das Tool auf NuGet gehostet wird, können Sie den Autor und seine Statistiken überprüfen, indem Sie nach dem Tool suchen.If the tool is hosted on NuGet, you can check the author and statistics by searching for the tool.

Installieren eines globalen ToolsInstall a global tool

Um ein Tool als globales Tool zu installieren, verwenden Sie, wie im folgenden Beispiel gezeigt, mit dotnet tool install die Option -g oder --global:To install a tool as a global tool, use the -g or --global option of dotnet tool install, as shown in the following example:

dotnet tool install -g dotnetsay

Die Ausgabe zeigt den zum Aufrufen des Tools verwendeten Befehl und die installierte Version, ähnlich wie im folgenden Beispiel:The output shows the command used to invoke the tool and the version installed, similar to the following example:

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:The default location for a tool's binaries depends on the operating system:

BetriebssystemOS PfadPath
Linux/macOSLinux/macOS $HOME/.dotnet/tools
WindowsWindows %USERPROFILE%\.dotnet\tools

Dieser Speicherort wird beim ersten Ausführen des SDK dem Pfad des Benutzers hinzugefügt, sodass globale Tools in jedem beliebigen Verzeichnis aufgerufen werden können, ohne dass der Speicherort des Tools angegeben werden muss.This location is added to the user's path when the SDK is first run, so global tools can be invoked from any directory without specifying the tool location.

Der Zugriff auf Tools ist benutzerspezifisch und gilt nicht global auf dem Computer.Tool access is user-specific, not machine global. Ein globales Tool ist nur für den Benutzer verfügbar, der das Tool installiert hat.A global tool is only available to the user that installed the tool.

Installieren eines globalen Tools an einem benutzerdefinierten SpeicherortInstall a global tool in a custom location

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.To install a tool as a global tool in a custom location, use the --tool-path option of dotnet tool install, as shown in the following examples.

Unter Windows:On Windows:

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

Unter Linux oder macOS:On Linux or macOS:

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

Das .NET Core SDK fügt diesen Speicherort nicht automatisch der Umgebungsvariablen PATH hinzu.The .NET Core SDK doesn't add this location automatically to the PATH environment variable. Zum Aufrufen eines Toolpfadtools müssen Sie sicherstellen, dass der Befehl verfügbar ist, indem Sie eine der folgenden Methoden verwenden:To invoke a tool-path tool, you have to make sure the command is available by using one of the following methods:

  • Fügen Sie das Installationsverzeichnis der Umgebungsvariablen PATH hinzu.Add the installation directory to the PATH environment variable.
  • Geben Sie den vollständigen Pfad zum Tool an, wenn Sie es aufrufen.Specify the full path to the tool when you invoke it.
  • Rufen das Tool im Installationsverzeichnis auf.Invoke the tool from within the installation directory.

Installieren eines lokalen ToolsInstall a local tool

Gilt ab .NET Core 3.0 SDK.Applies to .NET Core 3.0 SDK and later.

Um ein Tool nur für den lokalen Zugriff (für das aktuelle Verzeichnis und Unterverzeichnisse) zu installieren, muss es der Manifestdatei des Tools hinzugefügt werden.To install a tool for local access only (for the current directory and subdirectories), it has to be added to a tool manifest file. Führen Sie den Befehl dotnet new tool-manifest aus, um eine Manifestdatei für das Tool zu erstellen:To create a tool manifest file, run the dotnet new tool-manifest command:

dotnet new tool-manifest

Mit diesem Befehl wird im Verzeichnis .config eine Manifestdatei mit dem Namen dotnet-tools.json erstellt.This command creates a manifest file named dotnet-tools.json under the .config directory. Um der Manifestdatei ein lokales Tool hinzuzufügen, verwenden Sie den Befehl dotnet tool install ohne die Optionen --global und --tool-path, wie im folgenden Beispiel gezeigt:To add a local tool to the manifest file, use the dotnet tool install command and omit the --global and --tool-path options, as shown in the following example:

dotnet tool install dotnetsay

Die Befehlsausgabe zeigt, in welcher Manifestdatei sich das neu installierte Tool befindet, ähnlich wie im folgenden Beispiel:The command output shows which manifest file the newly installed tool is in, similar to the following example:

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:The following example shows a manifest file with two local tools installed:

{
  "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.You typically add a local tool to the root directory of the repository. Nach dem Einchecken der Manifestdatei im Repository erhalten Entwickler, die Code aus dem Repository auschecken, die neueste Manifestdatei.After you check in the manifest file to the repository, developers who check out code from the repository get the latest manifest file. Um alle in der Manifestdatei aufgeführten Tools zu installieren, führen sie den Befehl dotnet tool restore aus:To install all of the tools listed in the manifest file, they run the dotnet tool restore command:

dotnet tool restore

Die Ausgabe gibt an, welche Tools wiederhergestellt wurden:The output indicates which tools were restored:

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 ToolversionInstall a specific tool version

Um eine Vorab- oder bestimmte Version eines Tools zu installieren, geben Sie die Versionsnummer mit der Option --version an, wie im folgenden Beispiel gezeigt:To install a pre-release version or a specific version of a tool, specify the version number by using the --version option, as shown in the following example:

dotnet tool install dotnetsay --version 2.1.3

Verwenden eines ToolsUse a tool

Der Befehl zum Aufrufen eines Tools kann sich vom Namen des Pakets, das Sie installieren, unterscheiden.The command that you use to invoke a tool may be different from the name of the package that you install. Um alle derzeit für den aktuellen Benutzer auf dem Computer installierten Tools anzuzeigen, führen Sie den Befehl dotnet tool list aus:To display all of the tools currently installed on the machine for the current user, use the dotnet tool list command:

dotnet tool list

Die Ausgabe zeigt die Version und den Befehl jedes Tools, ähnlich wie im folgenden Beispiel:The output shows each tool's version and command, similar to the following example:

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 in diesem Beispiel gezeigt, enthält die Liste lokale Tools.As shown in this example, the list shows local tools. Zum Anzeigen globaler Tools verwenden Sie die Option --global. Zum Anzeigen von Toolpfadtools wählen Sie die Option --tool-path.To see global tools, use the --global option, and to see tool-path tools, use the --tool-path option.

Aufrufen eines globalen ToolsInvoke a global tool

Verwenden Sie für globale Tools den Tool-Befehl eigenständig.For global tools, use the tool command by itself. Wenn der Befehl beispielsweise dotnetsay oder dotnet-doc lautet, verwenden Sie Folgendes, um den Befehl aufzurufen:For example, if the command is dotnetsay or dotnet-doc, that's what you use to invoke the command:

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.If the command begins with the prefix dotnet-, an alternative way to invoke the tool is to use the dotnet command and omit the tool command prefix. Wenn der Befehl z. B. dotnet-doc lautet, wird das Tool mit dem folgenden Befehl aufgerufen:For example, if the command is dotnet-doc, the following command invokes the tool:

dotnet doc

Im folgenden Szenario können Sie jedoch nicht den Befehl dotnet verwenden, um ein globales Tool aufzurufen:However, in the following scenario you can't use the dotnet command to invoke a global tool:

  • Für ein globales Tool und ein lokales Tool gilt der gleiche Befehl mit dem Präfix dotnet-.A global tool and a local tool have the same command prefixed by dotnet-.
  • Sie möchten das globale Tool in einem Verzeichnis aufrufen, das im Geltungsbereich des lokalen Tools liegt.You want to invoke the global tool from a directory that is in scope for the local tool.

In diesem Fall rufen dotnet doc und dotnet dotnet-doc das lokale Tool auf.In this scenario, dotnet doc and dotnet dotnet-doc invoke the local tool. Um das globale Tool aufzurufen, verwenden Sie den Befehl eigenständig:To invoke the global tool, use the command by itself:

dotnet-doc

Aufrufen eines ToolpfadtoolsInvoke a tool-path tool

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.To invoke a global tool that is installed by using the tool-path option, make sure the command is available, as explained earlier in this article.

Aufrufen eines lokalen ToolsInvoke a local tool

Um ein lokales Tool aufzurufen, müssen Sie im Installationsverzeichnis den Befehl dotnet ausführen.To invoke a local tool, you have to use the dotnet command from within the installation directory. Sie können die Langform (dotnet tool run <COMMAND_NAME>) oder Kurzform (dotnet <COMMAND_NAME>) verwenden, wie in den folgenden Beispielen gezeigt:You can use the long form (dotnet tool run <COMMAND_NAME>) or the short form (dotnet <COMMAND_NAME>), as shown in the following examples:

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.If the command is prefixed by dotnet-, you can include or omit the prefix when you invoke the tool. Wenn der Befehl z. B. dotnet-doc lautet, ruft eines der folgenden Beispiele das lokale Tool auf:For example, if the command is dotnet-doc, any of the following examples invokes the local tool:

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

Aktualisieren eines ToolsUpdate a tool

Das Aktualisieren eines Tools umfasst das Deinstallieren und Neuinstallieren mit der neuesten stabilen Version.Updating a tool involves uninstalling and reinstalling it with the latest stable version. Verwenden Sie zum Aktualisieren eines Tools den Befehl dotnet tool update mit derselben Option, die Sie auch zur Installation des Tools verwendet haben:To update a tool, use the dotnet tool update command with the same option that you used to install the tool:

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

Bei einem lokalen Tool findet das SDK die erste Manifestdatei, die die Paket-ID enthält, indem es im aktuellen Verzeichnis und den übergeordneten Verzeichnissen eine Suche durchführt.For a local tool, the SDK finds the first manifest file that contains the package ID by looking in the current directory and parent directories. Wenn es in keiner Manifestdatei keine solche Paket-ID gibt, fügt das SDK der nächstgelegenen Manifestdatei einen neuen Eintrag hinzu.If there is no such package ID in any manifest file, the SDK adds a new entry to the closest manifest file.

Deinstallieren eines ToolsUninstall a tool

Entfernen Sie ein Tool mit dem Befehl dotnet tool uninstall mit der gleichen Option, die Sie zur Installation des Tools verwendet haben:Remove a tool by using the dotnet tool uninstall command with the same option that you used to install the tool:

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

Bei einem lokalen Tool findet das SDK die erste Manifestdatei, die die Paket-ID enthält, indem es im aktuellen Verzeichnis und den übergeordneten Verzeichnissen eine Suche durchführt.For a local tool, the SDK finds the first manifest file that contains the package ID by looking in the current directory and parent directories.

Hilfe und ProblembehandlungGet help and troubleshoot

Zum Abrufen einer Liste der verfügbaren dotnet tool-Befehle geben Sie den folgenden Befehl ein:To get a list of available dotnet tool commands, enter the following command:

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:To get tool usage instructions, enter one of the following commands or see the tool's website:

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

Wenn ein Tool nicht installiert oder ausgeführt werden kann, finden Sie unter Behandlung von Problemen bei der Nutzung von .NET Core-Tools weitere Informationen.If a tool fails to install or run, see Troubleshoot .NET Core tool usage issues.

Siehe auchSee also