.NET Core 通用工具概觀.NET Core Global Tools overview

本文適用於:✓ .NET Core 2.1 SDKThis article applies to: ✓ .NET Core 2.1 SDK

.NET Core 通用工具是包含主控台應用程式的特殊 NuGet 套件。A .NET Core Global Tool is a special NuGet package that contains a console application. 通用工具可以安裝在您電腦上的預設位置 (其包含在 PATH 環境變數中) 或自訂位置。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.

如果您想要使用 .NET Core 通用工具:If you want to use a .NET Core Global Tool:

  • 尋找工具的相關資訊 (通常是網站或 GitHub 網頁)。Find information about the tool (usually a website or GitHub page).
  • 檢查首頁中作者和統計資料的摘要 (通常是 NuGet.org)。Check the author and statistics in the home for the feed (usually NuGet.org).
  • 安裝工具。Install the tool.
  • 呼叫工具。Call the tool.
  • 更新工具。Update the tool.
  • 解除安裝工具。Uninstall the tool.

重要

.NET Core 通用工具會顯示在您的路徑中,並且在完全信任環境下執行。.NET Core Global Tools appear on your path and run in full trust. 除非您信任作者,否則請勿安裝 .NET Core 通用工具。Do not install .NET Core Global Tools unless you trust the author.

尋找 .NET Core 通用工具Find a .NET Core Global Tool

目前,.NET Core 命令列介面 (CLI) 中沒有通用工具搜尋功能。Currently, there isn't a Global Tool search feature in the .NET Core Command-line Interface (CLI).

您可以在 NuGet 上找到 .NET Core 通用工具。You can find .NET Core Global Tools on NuGet. 不過,NuGet 尚未允許您專門搜尋 .NET Core 通用工具。However, NuGet doesn't yet allow you to search specifically for .NET Core Global Tools.

您也可以在部落格文章或 natemcmaster/dotnet-tools GitHub 存放庫中找到工具建議。You may also find tool recommendations in blog posts or in the natemcmaster/dotnet-tools GitHub repository.

還可以在 aspnet/DotNetTools GitHub 存放庫中看到 ASP.NET 小組所建立之通用工具的原始程式碼。You can also see the source code for the Global Tools created by the ASP.NET team at the aspnet/DotNetTools GitHub repository.

檢查作者和統計資料Check the author and statistics

由於 .NET Core 通用工具在完全信任環境下執行,而且通常是安裝在您的路徑上,它們可以發揮極為強大的功能。Since .NET Core Global Tools run in full trust and are generally installed on your path, they can be very powerful. 請不要下載來自不信任人員的工具。Don't download tools from people you don't trust.

如果此工具裝載在 NuGet 上,您可以搜尋工具來檢查作者和統計資料。If the tool is hosted on NuGet, you can check the author and statistics by searching for the tool.

安裝通用工具Install a Global Tool

若要安裝通用工具,您可以使用 dotnet tool install .NET Core CLI 命令。To install a Global Tool, you use the dotnet tool install .NET Core CLI command. 下列範例會示範如何在預設位置安裝通用工具:The following example shows how to install a Global Tool in the default location:

dotnet tool install -g dotnetsay

如果無法安裝此工具,則會顯示錯誤訊息。If the tool can't be installed, error messages are displayed. 請確認正在檢查您所預期的摘要。Check that the feeds you expected are being checked.

如果您要嘗試安裝發行前版本或特定版本的工具,可以使用下列格式指定版本號碼: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>

如果安裝成功,則會顯示一則訊息,其中顯示用來呼叫此工具的命令以及安裝的版本,類似於下例範例: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.

通用工具可以安裝在預設目錄或特定位置中。Global Tools can be installed in the default directory or in a specific location. 預設目錄如下:The default directories are:

作業系統OS 路徑Path
Linux/macOSLinux/macOS $HOME/.dotnet/tools
WindowsWindows %USERPROFILE%\.dotnet\tools

第一次執行 SDK 時,這些位置會新增至使用者的路徑,因此可以直接呼叫安裝在該處的通用工具。These locations are added to the user's path when the SDK is first run, so Global Tools installed there can be called directly.

請注意,通用工具是使用者特定工具,而不是電腦全域工具。Note that the Global Tools are user-specific, not machine global. 使用者特定表示您無法安裝可供電腦上所有使用者使用的通用工具。Being user-specific means you cannot install a Global Tool that is available to all users of the machine. 此工具只適用於已安裝工具的每個使用者設定檔。The tool is only available for each user profile where the tool was installed.

通用工具也可以安裝在特定目錄中。Global Tools can also be installed in a specific directory. 安裝在特定目錄時,使用者必須確保命令可用,方法是在路徑中包含該目錄、使用指定的目錄呼叫命令,或從指定的目錄中呼叫工具。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. 在此情況下,.NET Core CLI 不會將這個位置自動新增至 PATH 環境變數。In this case, the .NET Core CLI doesn't add this location automatically to the PATH environment variable.

使用工具Use the tool

安裝此工具之後,您可以使用其命令進行呼叫。Once the tool is installed, you can call it by using its command. 請注意,命令可能無法與套件名稱相同。Note that the command may not be the same as the package name.

如果命令是 dotnetsay,呼叫時請使用:If the command is dotnetsay, you call it with:

dotnetsay

如果工具作者想要工具顯示在 dotnet 提示的內容中,他們可能會以稱為 dotnet <command> 的方式進行撰寫,例如: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

您可以藉由使用 dotnet tool list 命令列出已安裝的套件,了解已安裝的通用工具套件中包含哪些工具。You can find which tools are included in an installed Global Tool package by listing the installed packages using the dotnet tool list command.

您也可以在工具的網站中,或鍵入下列其中一個命令來尋找使用方式指示: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

可能會發生什麼問題What could go wrong

通用工具是與架構相依的應用程式,這表示它們會依賴電腦上安裝的 .NET Core 執行階段。Global Tools are framework-dependent applications, which means they rely on a .NET Core runtime installed on your machine. 如果找不到預期的執行階段,則會遵循一般的 .NET Core 執行階段向前復原規則,例如:If the expected runtime is not found, they follow normal .NET Core runtime roll-forward rules such as:

  • 應用程式會向前復原到指定的主要和次要版本的最高修補程式版本。An application rolls forward to the highest patch release of the specified major and minor version.
  • 如果沒有與符合的主要和次要版本號碼相符的執行階段,則會使用下一個較高的次要版本。If there is no matching runtime with a matching major and minor version number, the next higher minor version is used.
  • 預覽版本的執行階段之間或預覽版本和發行版本之間,不會進行向前復原。Roll forward doesn't occur between preview versions of the runtime or between preview versions and release versions. 因此,使用預覽版本所建立的通用工具必須重建、由作者重新發行,以及重新安裝。Thus, Global Tools created using preview versions must be rebuilt and republished by the author and reinstalled.
  • 在 .NET Core 2.1 Preview 1 中建立的通用工具可能會發生其他問題。Additional issues can occur with Global Tools created in .NET Core 2.1 Preview 1. 如需詳細資訊,請參閱 .NET Core 2.1 Preview 2 的已知問題For more information, see .NET Core 2.1 Preview 2 Known Issues.

如果應用程式找不到適當的執行階段,則無法執行,並且會報告錯誤。If an application cannot find an appropriate runtime, it fails to run and reports an error.

另一個可能發生的問題是:使用目前安裝的 .NET Core 執行階段,可能無法執行較早預覽期間所建立的通用工具。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. 您可以使用下列命令,查看您的電腦上安裝了哪些執行階段:You can see which runtimes are installed on your machine using the following command:

dotnet --list-runtimes

請連絡通用工具的作者,確認他們是否可以重新編譯其工具套件,並以更新的版本號碼重新發行至 NuGet。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. 一旦他們更新 NuGet 上的套件之後,您就可以更新您的複本。Once they have updated the package on NuGet, you can update your copy.

.NET Core CLI 會在第一次使用時,嘗試將預設位置新增至 PATH 環境變數。The .NET Core CLI tries to add the default locations to the PATH environment variable on its first usage. 不過,有幾種情況可能不會將位置自動新增至 PATH,例如:However, there are a couple of scenarios where the location might not be added to PATH automatically, such as:

  • 如果您已設定 DOTNET_SKIP_FIRST_TIME_EXPERIENCE 環境變數。If you've set the DOTNET_SKIP_FIRST_TIME_EXPERIENCE environment variable.
  • 在 macOS 上,如果您已使用 .tar.gz 檔案 (而非 .pkg) 安裝 .NET Core SDK。On macOS, if you've installed the .NET Core SDK using .tar.gz files and not .pkg.
  • 在 Linux 上,您需要編輯殼層環境檔案來設定 PATH。On Linux, you need to edit the shell environment file to configure the PATH.

其他 CLI 命令Other CLI commands

.NET Core SDK 包含其他支援 .NET Core 通用工具的命令。The .NET Core SDK contains other commands that support .NET Core Global Tools. 請使用任何 dotnet tool 命令搭配下列其中一個選項:Use any of the dotnet tool commands with one of the following options:

  • --global-g 指定命令適用於使用者範圍通用工具。--global or -g specifies that the command is applicable to user-wide Global Tools.
  • --tool-path 指定通用工具的自訂位置。--tool-path specifies a custom location for Global Tools.

若要查看哪些命令適用於通用工具:To find out which commands are available for Global Tools:

dotnet tool --help

更新通用工具需要解除安裝再使用最新的穩定版本重新安裝。Updating a Global Tool involves uninstalling and reinstalling it with the latest stable version. 若要更新通用工具,請使用 dotnet tool update 命令:To update a Global Tool, use the dotnet tool update command:

dotnet tool update -g <packagename>

使用 dotnet tool uninstall 移除通用工具:Remove a Global Tool using the dotnet tool uninstall:

dotnet tool uninstall -g <packagename>

若要顯示電腦上目前已安裝的所有通用工具,以及它們的版本和命令,請使用 dotnet tool list 命令: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