如何管理 .NET 工具

  • 發行項

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

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

  • 作為全域工具。

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

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

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

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

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

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

重要

.NET 工具會以完全信任的狀態執行。 除非您信任作者，否則請不要安裝 .NET 工具。

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

尋找工具

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

檢查作者和統計資料

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

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

安裝全域工具

若要將工具安裝為全域工具，請使用 dotnet tool install 的 -g 或 --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.

注意

根據預設，要安裝的 .NET 二進位檔架構代表目前執行的 OS 架構。 若要指定不同的 OS 架構，請參閱 dotnet tool install, --arch option。

工具二進位檔的預設位置取決於作業系統：

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 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 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 選項。

若要列出特定工具，請使用 dotnet tool list <PACKAGE_ID> 命令：

dotnet tool list dotnetsay

工具只有在安裝後才會列出於輸出中，如下列範例所示：

Package Id      Version      Commands       Manifest
-------------------------------------------------------------------------------------------
dotnetsay       2.1.3        dotnetsay      /home/name/repository/.config/dotnet-tools.json

叫用全域工具

針對全域工具，會自行使用工具命令。 例如，如果命令是 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 工具使用問題進行疑難排解。 您可以使用 --help 參數來取得可用 dotnet tool 命令和參數的清單：

dotnet tool --help

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

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

另請參閱