如何管理 .NET Core 工具

本文適用於： ✔️ .NET Core 2.1 SDK 及更高版本

.NET Core 工具是一種特殊的 NuGet 包，其中包含控制檯應用程序。 可以通過以下方式在計算機上安裝該工具：

• 作爲全局工具。

  工具二進制文件安裝在添加到 PATH 環境變量的默認目錄中。 無需指定工具位置即可從計算機上的任何目錄調用該工具。 工具的一個版本用於計算機上的所有目錄。

• 作爲自定義位置中的全局工具（也稱爲工具路徑工具）。

  工具二進制文件安裝在你指定的位置中。 可以從安裝目錄調用該工具，也可以通過提供具有命令名稱的目錄或將目錄添加到 PATH 環境變量來調用該工具。 工具的一個版本用於計算機上的所有目錄。

• 作爲本地工具（適用於 .NET Core SDK 3.0 及更高版本）。

  工具二進制文件安裝在默認目錄中。 可以從安裝目錄或其任何子目錄調用該工具。 不同目錄可以使用同一工具的不同版本。

  .NET CLI 使用清單文件跟蹤哪些工具作爲本地工具安裝到目錄。 將清單文件保存到源代碼存儲庫的根目錄中後，參與者可以克隆存儲庫並調用用於安裝清單文件中列出的所有工具的單個 .NET Core CLI 命令。

.NET Core 工具在完全信任環境中運行。 除非你信任工具作者，否則請勿安裝 .NET Core 工具。

查找工具

目前，.NET Core 沒有工具搜索功能。 以下是查找工具的一些方法：

• 請參閱 natemcmaster/dotnet-tools GitHub 存儲庫中的工具列表。
• 使用 ToolGet 搜索 .NET 工具。
• 在 dotnet/aspnetcore GitHub 存儲庫的工具目錄中查看 ASP.NET Core 團隊創建的工具的源代碼。
• 在 .NET Core dotnet 診斷工具中瞭解診斷工具。
• 搜索 NuGet 網站。 但是，NuGet 網站尚無可用於僅搜索工具包的功能。

查看作者和統計信息

由於 .NET Core 工具在完全信任環境中運行，並且全局工具已添加到 PATH 環境變量，因此它們的功能非常強大。 請勿下載不信任的人提供的工具。

如果該工具在 NuGet 中託管，可以通過搜索該工具來查看作者和統計信息。

安裝全局工具

若要將工具作爲全局工具安裝，請使用 dotnet tool install 的 -g 或 --global 選項，如以下示例中所示：

.NET Core CLI

dotnet tool install -g dotnetsay

輸出顯示用於調用該工具和已安裝的版本的命令，類似於以下示例：

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

工具二進制文件的默認位置取決於操作系統：

(OS)	路徑
Linux/macOS	$HOME/.dotnet/tools
Windows	%USERPROFILE%\.dotnet\tools

首次運行 SDK 時，會將此位置添加到用戶的路徑，因此，無需指定工具位置即可從任何目錄調用全局工具。

工具訪問特定於用戶，而不針對計算機全局。 全局工具僅適用於安裝了該工具的用戶。

安裝自定義位置中的全局工具

若要將工具作爲自定義位置中的全局工具安裝，請使用 dotnet tool install 的 --tool-path 選項，如以下示例中所示。

在 Windows 上：

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

在 Linux 或 macOS 上：

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

.NET Core SDK 不將此位置自動添加至 PATH 環境變量。 若要調用工具路徑工具，必須確保可使用以下方法之一來調用命令：

• 將安裝目錄添加到 PATH 環境變量。
• 調用該工具時，指定該工具的完整路徑。
• 從安裝目錄調用該工具。

安裝本地工具

適用於 .NET Core 3.0 SDK 及更高版本。

若要安裝僅用於本地訪問的工具（對於當前目錄和子目錄），必須將其添加到工具清單文件。 若要創建工具清單文件，請運行 dotnet new tool-manifest 命令：

dotnet new tool-manifest

此命令在“.config” 目錄下創建一個名爲“dotnet-tools.json” 的清單文件。 若要將本地工具添加到清單文件，請使用 dotnet tool install 命令並省略 --global 和 --tool-path 選項，如以下示例中所示 ：

dotnet tool install dotnetsay

命令輸出顯示新安裝的工具所在的清單文件，類似於以下示例：

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.

以下示例顯示安裝了兩個本地工具的清單文件：

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

通常將本地工具添加到存儲庫的根目錄。 將清單文件簽入到存儲庫後，從存儲庫中籤出代碼的開發人員會獲得最新的清單文件。 若要安裝清單文件中列出的所有工具，請運行 dotnet tool restore 命令：

dotnet tool restore

輸出表明還原了哪些工具：

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.

安裝特定工具版本

若要安裝工具的預發佈版本或特定版本，請使用 --version 選項指定版本號，如以下示例中所示：

dotnet tool install dotnetsay --version 2.1.3

使用工具

用於調用工具的命令可能不同於安裝的包的名稱。 若要顯示計算機上目前安裝的所有工具，請使用 dotnet tool list 命令：

dotnet tool list

輸出顯示每個工具的版本和命令，類似於以下示例：

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

如本示例中所示，列表顯示了本地工具。 若要查看全局工具，請使用 --global 選項，若要查看工具路徑工具，請使用 --tool-path 選項。

調用全局工具

對於全局工具，請單獨使用工具命令。 例如，如果命令爲 dotnetsay 或 dotnet-doc，則可以使用以下命令調用該工具：

dotnetsay
dotnet-doc

如果命令以前綴 dotnet- 開頭，則調用該工具的另一種方法是使用 dotnet 命令並省略工具命令前綴。 例如，如果命令爲 dotnet-doc，則可以使用以下命令調用該工具：

dotnet doc

但是，在以下情況下，不能使用 dotnet 命令來調用全局工具：

• 全局工具和本地工具具有以 dotnet- 爲前綴的相同命令。
• 你希望從本地工具範圍內的目錄調用全局工具。

在這種情況下，dotnet doc 和 dotnet dotnet-doc 調用本地工具。 若要調用全局工具，請單獨使用命令：

dotnet doc

調用工具路徑工具

若要調用使用 tool-path 選項安裝的全局工具，請確保該命令可用，如本文前面所述。

調用本地工具

若要調用本地工具，必須從安裝目錄使用 dotnet 命令。 可以使用長格式 (dotnet tool run <COMMAND_NAME>) 或短格式 (dotnet <COMMAND_NAME>)，如以下示例中所示：

dotnet tool run dotnetsay
dotnet dotnetsay

如果命令以 dotnet- 爲前綴，則可以在調用該工具時包括或省略前綴。 例如，如果命令爲 dotnet-doc，則可以使用以下任何示例調用本地工具：

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

更新工具

更新工具涉及卸載該工具並重新安裝它的最新穩定版。 若要更新工具，請使用具有用於安裝該工具的相同選項的 dotnet tool update 命令：

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

對於本地工具，SDK 通過在當前目錄和父目錄中查找來查找包含包 ID 的第一個清單文件。 如果任何清單文件中都沒有此類包 ID，SDK 會將新條目添加到最近的清單文件。

卸載工具

使用具有用於安裝該工具的相同選項的 dotnet tool uninstall 命令刪除工具：

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

對於本地工具，SDK 通過在當前目錄和父目錄中查找來查找包含包 ID 的第一個清單文件。

獲取幫助和疑難解答

若要獲取可用 dotnet tool 命令的列表，請輸入以下命令：

dotnet tool --help

若要獲取工具使用說明，請輸入以下命令之一，或訪問工具的網站：

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

如果工具無法安裝或運行，請參閱排查 .NET Core 工具使用問題。

請參閱

• 教程：使用 .NET Core CLI 創建 .NET Core 工具
• 教程：使用 .NET Core CLI 安裝和使用 .NET Core 全局工具
• 教程：使用 .NET Core CLI 安裝和使用 .NET Core 本地工具