如何管理 .NET 工具

本文適用于： ✔️.NET Core 2.1 SDK 和更新版本。

.NET 工具是包含主控台應用程式的特殊 NuGet 套件。 您可以透過下列方式在電腦上安裝工具：

• 做為全域工具。

  工具二進位檔會安裝在新增至 PATH 環境變數的預設目錄中。 您可以從機器上的任何目錄叫用工具，而不需指定其位置。 機器上所有目錄都會使用一個工具版本。

• 作為自訂位置中的全域工具， (也稱為工具路徑工具) 。

  工具二進位檔會安裝在您指定的位置。 您可以藉由提供目錄的命令名稱，或將目錄新增至 PATH 環境變數，從安裝目錄叫用工具。 機器上所有目錄都會使用一個工具版本。

• 本機工具 (適用于 .NET Core SDK 3.0 和更新版本) 。

  工具二進位檔會安裝在預設目錄中。 您可以從安裝目錄或任何其子目錄叫用工具。 不同的目錄可以使用相同工具的不同版本。

  .NET CLI 會使用資訊清單檔來追蹤安裝為目錄本機的工具。 當資訊清單檔儲存在原始程式碼存放庫的根目錄中時，參與者可以複製存放庫，並叫用單一 .NET CLI 命令來安裝資訊清單檔中列出的所有工具。

重要

.NET 工具會完全信任執行。 除非您信任作者，否則請勿安裝 .NET 工具。

如果 .NET 是 透過 Snap 安裝，.NET 工具可能無法正常運作。

尋找工具

以下是尋找工具的一些方式：

• 使用 dotnet 工具搜尋 命令來尋找發佈至 NuGet.org 的工具。
• 使用 「.NET 工具」 套件類型篩選來搜尋 NuGet 網站。 如需詳細資訊，請參閱尋找及選擇套件。
• 請參閱 ASP.NET Core小組在dotnet/aspnetcore GitHub 存放庫的 [工具] 目錄中建立之工具的原始程式碼。
• 瞭解 .NET 診斷工具的診斷工具。

檢查作者和統計資料

.NET 工具可能很強大，因為它們會完全信任執行，而且全域工具會新增至 PATH 環境變數。 請不要下載來自不信任人員的工具。

如果此工具裝載在 NuGet 上，您可以搜尋工具來檢查作者和統計資料。

安裝全域工具

若要將工具安裝為全域工具，請使用 -gdotnet 工具安裝的或 --global 選項，如下列範例所示：

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 時，此位置會新增至使用者的路徑。 因此，全域工具可以從任何目錄叫用，而不需要指定工具位置。

工具存取是使用者特定的，而非電腦全域。 全域工具僅適用于安裝此工具的使用者。

在自訂位置安裝全域工具

若要在自訂位置中將工具安裝為全域工具，請使用 --tool-pathdotnet 工具安裝的選項，如下列範例所示：

在 Windows 上：

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

在 Linux 或 macOS 上：

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

.NET 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

若要安裝工具的發行前版本，而不指定確切的版本號碼，請使用 --version 選項並提供萬用字元，如下列範例所示：

dotnet tool install --global dotnetsay --version "*-rc*"

使用工具

您用來叫用工具的命令可能與您所安裝的套件名稱不同。 若要顯示目前使用者電腦上目前安裝的所有工具，請使用 dotnet 工具清單 命令：

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 會尋找目前目錄和父目錄，以尋找包含套件識別碼的第一個資訊清單檔。 如果任何資訊清單檔案中沒有任何這類套件識別碼，SDK 會將新專案新增至最接近的資訊清單檔。

卸載工具

使用 dotnet tool uninstall 命令搭配您用來安裝此工具的相同選項來卸載工具：

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

針對本機工具，SDK 會尋找目前目錄和父目錄，以尋找包含套件識別碼的第一個資訊清單檔。

取得說明和疑難排解

如果工具無法安裝或執行，請參閱 針對 .NET 工具使用問題進行疑難排解。 您可以使用 參數來取得可用 dotnet tool 命令和參數 --help 的清單：

dotnet tool --help

若要取得工具使用指示，請輸入下列其中一個命令，或查看工具的網站：

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

另請參閱

• 教學課程：使用 .NET CLI 建立 .NET 工具
• 教學課程：使用 .NET CLI 安裝和使用 .NET 全域工具
• 教學課程：使用 .NET CLI 安裝和使用 .NET 本機工具