Übersicht über globale .NET Core-Tools.NET Core Global Tools overview

Dieser Artikel gilt für: ✓ .NET Core 2.1 SDKThis article applies to: ✓ .NET Core 2.1 SDK

Ein globales .NET Core-Tool ist ein spezielles NuGet-Paket, das eine Konsolenanwendung enthält.A .NET Core Global Tool is a special NuGet package that contains a console application. Ein globales Tool kann an einem benutzerdefinierten Speicherort oder einem Standardspeicherort auf ihrem Computer installiert werden, der in der Umgebungsvariable „PATH“ enthalten ist.A Global Tool can be installed on your machine on a default location that is included in the PATH environment variable or on a custom location.

Wenn Sie ein globales .NET Core-Tool verwenden möchten:If you want to use a .NET Core Global Tool:

  • Erfahren Sie mehr über das Tool (in der Regel über eine Website oder GitHub-Seite).Find information about the tool (usually a website or GitHub page).
  • Überprüfen Sie den Autor und die Statistiken auf der Startseite des Feeds (in der Regel NuGet.org).Check the author and statistics in the home for the feed (usually NuGet.org).
  • Installieren Sie das Tool.Install the tool.
  • Rufen Sie das Tool auf.Call the tool.
  • Aktualisieren Sie das Tool.Update the tool.
  • Deinstallieren Sie das Tool.Uninstall the tool.

Wichtig

Globale .NET Core-Tools werden in Ihrem Pfad angezeigt und mit voller Vertrauenswürdigkeit ausgeführt..NET Core Global Tools appear on your path and run in full trust. Installieren Sie nur globale .NET Core-Tools von Autoren, denen Sie vertrauen.Do not install .NET Core Global Tools unless you trust the author.

Finden eines globalen .NET Core-ToolsFind a .NET Core Global Tool

Derzeit gibt es kein Suchfeature für globale Tools in der .NET Core-CLI (Befehlszeilenschnittstelle).Currently, there isn't a Global Tool search feature in the .NET Core Command-line Interface (CLI).

Sie können globale .NET Core-Tools auf NuGet finden.You can find .NET Core Global Tools on NuGet. Allerdings können Sie auf der NuGet-Website nicht spezifisch nach globalen .NET Core-Tools suchen.However, NuGet doesn't yet allow you to search specifically for .NET Core Global Tools.

Empfehlungen von Tools können Sie auch in Blogbeiträgen oder im GitHub-Repository natemcmaster/dotnet-tools finden.You may also find tool recommendations in blog posts or in the natemcmaster/dotnet-tools GitHub repository.

Sie können sich auch den Quellcode für die vom ASP.NET-Team erstellten globalen Tools im GitHub-Repository aspnet/DotNetTools ansehen.You can also see the source code for the Global Tools created by the ASP.NET team at the aspnet/DotNetTools GitHub repository.

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

Da globale .NET Core-Tools mit voller Vertrauenswürdigkeit ausgeführt und in der Regel auf Ihrem Pfad installiert werden, können sie sehr nützlich sein.Since .NET Core Global Tools run in full trust and are generally installed on your path, 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

Verwenden Sie den .NET Core-CLI-Befehl dotnet tool install, um ein globales Tool zu installieren.To install a Global Tool, you use the dotnet tool install .NET Core CLI command. Im folgenden Beispiel wird gezeigt, wie ein globales Tool am Standardspeicherort installiert wird:The following example shows how to install a Global Tool in the default location:

dotnet tool install -g dotnetsay

Wenn das Tool nicht installiert werden kann, werden Fehlermeldungen angezeigt.If the tool can't be installed, error messages are displayed. Stellen Sie sicher, dass die erwarteten Feeds überprüft werden.Check that the feeds you expected are being checked.

Wenn Sie versuchen, eine Vorabversion oder eine spezifische Version des Tools zu installieren, können Sie die Versionsnummer im folgenden Format angeben:If you're trying to install a pre-release version or a specific version of the tool, you can specify the version number using the following format:

dotnet tool install -g <package-name> --version <version-number>

Wenn die Installation erfolgreich abgeschlossen wurde, wird eine Meldung angezeigt, die den Befehl zum Aufrufen des Tools und die installierte Version ähnlich wie im folgenden Beispiel anzeigt:If installation is successful, a message is displayed showing the command used to call 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.0.0') was successfully installed.

Globale Tools können im Standardverzeichnis oder an einem spezifischen Speicherort installiert werden.Global Tools can be installed in the default directory or in a specific location. Die Standardverzeichnisse sind:The default directories are:

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

Diese Speicherorte werden dem Pfad des Benutzers hinzugefügt, wenn das SDK zum ersten Mal ausgeführt wird, damit dort installierte globale Tools direkt aufgerufen werden können.These locations are added to the user's path when the SDK is first run, so Global Tools installed there can be called directly.

Beachten Sie, dass die globalen Tools benutzerspezifisch gespeichert werden und nicht global auf dem Computer.Note that the Global Tools are user-specific, not machine global. Deshalb können Sie kein globales Tool installieren, das für alle Benutzer auf dem Computer verfügbar ist.Being user-specific means you cannot install a Global Tool that is available to all users of the machine. Das Tool ist nur für jedes Benutzerprofil verfügbar, auf denen das Tool installiert wurde.The tool is only available for each user profile where the tool was installed.

Globale Tools können auch in einem spezifischen Verzeichnis installiert werden.Global Tools can also be installed in a specific directory. Wenn sie in einem spezifischen Verzeichnis installiert werden, muss der Benutzer sicherstellen, dass der Befehl verfügbar ist, indem das Verzeichnis in den Pfad eingefügt, der Befehl mit dem angegebenen Verzeichnis aufgerufen oder das Tool aus dem angegebenen Verzeichnis aufgerufen wird.When installed in a specific directory, the user must ensure the command is available, by including that directory in the path, by calling the command with the directory specified, or calling the tool from within the specified directory. In diesem Fall fügt die .NET Core-CLI diesen Speicherort nicht automatisch der Umgebungsvariable „PATH“ hinzu.In this case, the .NET Core CLI doesn't add this location automatically to the PATH environment variable.

Verwenden des ToolsUse the tool

Nachdem das Tool installiert wurde, können Sie es mit dem entsprechenden Befehl aufrufen.Once the tool is installed, you can call it by using its command. Beachten Sie, dass der Befehl möglicherweise nicht mit dem Paketnamen übereinstimmt.Note that the command may not be the same as the package name.

Wenn der Befehl dotnetsay ist, rufen Sie ihn wie folgt auf:If the command is dotnetsay, you call it with:

dotnetsay

Wenn der Autor des Tools das Tool im Kontext der dotnet-Eingabeaufforderung anzeigen wollte, ist es möglicherweise so geschrieben, dass Sie es als dotnet <command> aufrufen, zum Beispiel:If the tool author wanted the tool to appear in the context of the dotnet prompt, they may have written it in a way that you call it as dotnet <command>, such as:

dotnet doc

Sie können herausfinden, welche Tools in einem installierten Paket globaler Tools enthalten sind, indem Sie den Befehl dotnet tool list verwenden.You can find which tools are included in an installed Global Tool package by listing the installed packages using the dotnet tool list command.

Darüber hinaus können Sie sich die Anweisungen auf der Website zum Tool ansehen oder einen der folgenden Befehle eingeben:You can also look for usage instructions at the tool's website or by typing one of the following commands:

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

Was kann schief gehenWhat could go wrong

Globale Tools sind Framework-abhängige Anwendungen, d.h. sie sind von der auf Ihrem Computer installierten .NET Core-Runtime abhängig.Global Tools are framework-dependent applications, which means they rely on a .NET Core runtime installed on your machine. Wenn die erwartete Runtime nicht gefunden wurde, orientieren sie sich an den normalen Regeln für das Rollforward der .NET Core-Runtime, zum Beispiel:If the expected runtime is not found, they follow normal .NET Core runtime roll-forward rules such as:

  • Eine Anwendung wird auf das neueste Patchrelease der angegebenen Haupt- und Nebenversion gebracht.An application rolls forward to the highest patch release of the specified major and minor version.
  • Wenn keine übereinstimmende Runtime mit einer übereinstimmenden Haupt- und Nebenversion vorhanden ist, wird die nächsthöhere Nebenversion verwendet.If there is no matching runtime with a matching major and minor version number, the next higher minor version is used.
  • Ein Rollforward findet nicht zwischen Vorschauversionen der Runtime oder Vorschauversionen und Releaseversionen statt.Roll forward doesn't occur between preview versions of the runtime or between preview versions and release versions. Daher müssen globale Tools, die mit Vorschauversionen erstellt wurden, vom Autor neu erstellt, veröffentlicht und installiert werden.Thus, Global Tools created using preview versions must be rebuilt and republished by the author and reinstalled.
  • Mit globalen Tools, die in .NET Core 2.1 Vorschau 1 erstellt wurden, können weitere Fehler auftreten.Additional issues can occur with Global Tools created in .NET Core 2.1 Preview 1. Weitere Informationen finden Sie unter .NET Core 2.1 Preview 2 Known Issues (Bekannte Probleme mit .NET Core 2.1 Vorschau 2).For more information, see .NET Core 2.1 Preview 2 Known Issues.

Wenn eine Anwendung keine entsprechende Runtime finden kann, schlägt die Ausführung fehl, und ein Fehler wird gemeldet.If an application cannot find an appropriate runtime, it fails to run and reports an error.

Ein weiteres Problem kann darin bestehen, dass ein globales Tool, das in einer vorherigen Vorschauversion erstellt wurde, möglicherweise nicht mit Ihren aktuell installierten .NET Core-Runtimes ausgeführt werden kann.Another issue that might happen is that a Global Tool that was created during an earlier preview may not run with your currently installed .NET Core runtimes. Sie können die auf Ihrem Computer installierten Runtimes mit dem folgenden Befehl anzeigen:You can see which runtimes are installed on your machine using the following command:

dotnet --list-runtimes

Wenden Sie sich an den Autor des globalen Tools, und finden Sie heraus, ob sie das Toolpaket mit einer aktualisierten Versionsnummer neu kompilieren und auf NuGet veröffentlichen können.Contact the author of the Global Tool and see if they can recompile and republish their tool package to NuGet with an updated version number. Wenn sie das Paket auf NuGet aktualisiert haben, können Sie Ihre Kopie aktualisieren.Once they have updated the package on NuGet, you can update your copy.

Die .NET Core-CLI versucht bei der ersten Verwendung, die Standardspeicherorte der Umgebungsvariable „PATH“ hinzuzufügen.The .NET Core CLI tries to add the default locations to the PATH environment variable on its first usage. Es gibt jedoch einige Szenarios, in denen der Speicherort nicht automatisch dem Pfad hinzugefügt werden kann, zum Beispiel:However, there are a couple of scenarios where the location might not be added to PATH automatically, such as:

  • Wenn Sie die Umgebungsvariable DOTNET_SKIP_FIRST_TIME_EXPERIENCE festgelegt haben.If you've set the DOTNET_SKIP_FIRST_TIME_EXPERIENCE environment variable.
  • Wenn Sie das .NET Core SDK mit TAR.GZ-Dateien anstelle von PKG-Dateien auf macOS installiert haben.On macOS, if you've installed the .NET Core SDK using .tar.gz files and not .pkg.
  • Wenn Sie die Shellumgebungsdatei unter Linux bearbeiten müssen, um den Pfad zu konfigurieren.On Linux, you need to edit the shell environment file to configure the PATH.

Andere CLI-BefehleOther CLI commands

Das .NET Core SDK enthält andere Befehle, die globale .NET Core-Tools unterstützen.The .NET Core SDK contains other commands that support .NET Core Global Tools. Verwenden Sie einen beliebigen dotnet tool-Befehl mit einer der folgenden Optionen:Use any of the dotnet tool commands with one of the following options:

  • --global oder -g gibt an, dass der Befehl für benutzerweite globale Tools anwendbar ist.--global or -g specifies that the command is applicable to user-wide Global Tools.
  • --tool-path legt einen benutzerdefinierten Speicherort für globale Tools fest.--tool-path specifies a custom location for Global Tools.

So finden Sie heraus, welche Befehle für globale Tools verfügbar sind:To find out which commands are available for Global Tools:

dotnet tool --help

Das Aktualisieren eines globalen Tools umfasst das Deinstallieren und Neuinstallieren mit der neuesten stabilen Version.Updating a Global Tool involves uninstalling and reinstalling it with the latest stable version. Verwenden Sie den Befehl dotnet tool update, um ein globales Tool zu aktualisieren:To update a Global Tool, use the dotnet tool update command:

dotnet tool update -g <packagename>

Entfernen Sie ein globales Tool mit dotnet tool uninstall:Remove a Global Tool using the dotnet tool uninstall:

dotnet tool uninstall -g <packagename>

Verwenden Sie den Befehl dotnet tool list, um alle derzeit auf dem Computer installierten globalen Tools mit ihren Versionen und Befehlen anzuzeigen:To display all of the Global Tools currently installed on the machine, along with their version and commands, use the dotnet tool list command:

dotnet tool list -g