教程：使用 .NET CLI 安裝和使用 .NET 本機工具

本文適用於： ✔️ .NET 8 SDK 及後續版本

本教學課程會教導您如何安裝和使用本機工具。 您可以使用您在本系列的第一個教學課程 中建立的工具，。

先決條件

  • 完成本系列 的第一個教學課程。
  • .NET 10.0.100 SDK 或更新版本 （適用於 dnx） - 選擇性，但建議使用。

建立清單檔案

若要安裝僅供本機存取的工具（限於目前目錄及其子目錄），必須將其新增至清單檔案。

從 dotnet-env 資料夾，往上一層移動到 儲存庫 資料夾：

cd ..

執行 dotnet new 命令以建立清單檔案：

dotnet new tool-manifest

輸出表示成功建立檔案。

The template "Dotnet local tool manifest file" was created successfully.

.config/dotnet-tools.json 檔案中還沒有工具：

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

宣告檔中列出的工具可供目前目錄及其子目錄使用。 目前的目錄是包含 .config 目錄（該目錄中有指令清單檔）的目錄。

當您使用參考本機工具的 CLI 命令時，SDK 會在目前目錄和父目錄中搜尋指令清單檔。 如果找到清單檔，但檔案不包含所參考的工具，它會繼續在父目錄中搜尋。 搜尋會在找到參考的工具時結束，或者找到 isRoot 已設定為 true的指令清單檔案時結束。

將 dotnet-env 安裝為本地工具（傳統方法

從您在第一個教學中建立的套件安裝這個工具：

dotnet tool install --add-source ./dotnet-env/nupkg dotnet-env

此命令會將工具新增至您在上一個步驟中建立的指令清單檔案。 命令輸出會顯示新安裝工具所在的指令清單檔：

You can invoke the tool from this directory using the following command:
'dotnet tool run dotnet-env' or 'dotnet dotnet-env'
Tool 'dotnet-env' (version '1.0.0') was successfully installed.
Entry is added to the manifest file /home/name/repository/.config/dotnet-tools.json

.config/dotnet-tools.json 檔案現在有一個工具：

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "dotnet-env": {
      "version": "1.0.0",
      "commands": [
        "dotnet-env"
      ]
    }
  }
}

使用已安裝的本機工具

安裝為本機工具後，您可以透過多種方式呼叫它：

  • 直接使用 dnx 執行工具：

    dnx dotnet-env --add-source ./nupkg

    備註

    將 dnx 與本機工具資訊清單搭配使用時，它會自動使用資訊清單中指定的版本。

  • 使用 dotnet dotnet-env：

    dotnet dotnet-env

  • 使用 dotnet tool run

    dotnet tool run dotnet-env

還原其他人安裝的本機工具

您通常會在存放庫的根目錄中安裝本機工具。 將指令清單檔案簽入存放庫之後，其他開發人員可以取得最新的指令清單檔案。 若要安裝指令清單檔中列出的所有工具，他們可以執行單一 dotnet tool restore 命令。

  1. 開啟 .config/dotnet-tools.json 檔案，並以下列 JSON 取代內容：

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

  2. 儲存您的變更。

    進行這項變更與從存放庫取得最新版本相同，因為其他人已安裝專案目錄的套件 dotnetsay。

  3. 執行 dotnet tool restore 命令。

    dotnet tool restore

    這個指令會產生類似下列範例的輸出：

    Tool 'dotnet-env' (version '1.0.0') was restored. Available commands: dotnet-env
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

  4. 確認工具可供使用：

    dotnet tool list

    輸出是套件和命令的清單，類似下列範例：

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

  5. 測試工具：

    dotnet tool run dotnetsay hello from dotnetsay
dotnet tool run dotnet-env

更新本機工具

已安裝的本機工具版本 dotnetsay 為 2.1.3。 使用 dotnet tool update 命令，將工具更新為最新版本。

dotnet tool update dotnetsay

輸出會指出新的版本號碼：

Tool 'dotnetsay' was successfully updated from version '2.1.3' to version '3.0.3'
(manifest file /home/name/repository/.config/dotnet-tools.json).

update 命令會尋找包含套件識別碼並更新該宣告檔案的第一個檔案。 如果在搜尋範圍內的任何指令清單檔案中沒有這類套件標識符，SDK 會將新專案新增至最接近的指令清單檔。 搜尋範圍是向上遍歷父目錄，直到找到具有 isRoot = true 的清單檔為止。

移除本地工具

執行 dotnet tool uninstall 命令來移除已安裝的工具：

dotnet tool uninstall dotnet-env

dotnet tool uninstall dotnetsay

疑難排解

如果您在遵循教學課程時收到錯誤訊息，請參閱 針對 .NET 工具使用問題進行疑難解答。

另請參閱

如需詳細資訊，請參閱 .NET 工具。

  • Last updated on