教學課程：使用 .NET CLI 安裝並使用 .NET 本機工具

發行項
02/27/2024

本文適用於： ✔️ .NET Core 3.0 SDK 與更新版本

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

必要條件

完成此系列的第一個教學課程。
安裝 .NET Core 2.1 執行階段。

在此教學課程中，您會安裝並使用以 .NET Core 2.1 為目標的工具，因此您必須在機器上安裝該執行階段。若要安裝 2.1 執行階段，請移至 .NET Core 2.1 下載頁面 (英文)，然後在 [執行應用程式 - 執行階段] 資料行中尋找執行階段安裝連結。

建立資訊清單檔

若要安裝僅限本機存取的工具 (針對當前目錄和子目錄)，則必須將它新增至資訊清單檔。

從 microsoft.botsay 資料夾，向上瀏覽一個層級至 repository 資料夾：

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 的資訊清單檔時結束。

將 botsay 安裝為本機工具

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

dotnet tool install --add-source ./microsoft.botsay/nupkg microsoft.botsay

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

You can invoke the tool from this directory using the following command:
'dotnet tool run botsay' or 'dotnet botsay'
Tool 'microsoft.botsay' (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": {
    "microsoft.botsay": {
      "version": "1.0.0",
      "commands": [
        "botsay"
      ]
    }
  }
}

使用工具

從 repository 資料夾中執行 dotnet tool run 命令來叫用工具：

dotnet tool run botsay hello from the bot

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

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

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

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

儲存變更。

進行此變更相當於在其他人針對專案目錄安裝 dotnetsay 套件之後，從存放庫中取得最新版本。

執行 dotnet tool restore 命令。

dotnet tool restore

此命令會產生類似下列範例的輸出：

Tool 'microsoft.botsay' (version '1.0.0') was restored. Available commands: botsay
Tool 'dotnetsay' (version '2.1.3') was restored. Available commands: dotnetsay
Restore was successful.

確認工具可供使用：

dotnet tool list

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

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

測試工具：

dotnet tool run dotnetsay hello from dotnetsay
dotnet tool run botsay hello from botsay

更新本機工具

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

dotnet tool update dotnetsay

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

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

更新命令會尋找包含套件識別碼的第一個資訊清單檔，並加以更新。如果在位於搜尋範圍內的任何資訊清單檔中都沒有這類套件識別碼，SDK 就會將新項目新增到最接近的資訊清單檔。搜尋範圍會向上擴大至父目錄，直到找到具有 isRoot = true 的資訊清單檔為止。

移除本機工具

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

dotnet tool uninstall microsoft.botsay

dotnet tool uninstall dotnetsay

疑難排解

如果您在依照教學課程進行時收到錯誤訊息，請參閱針對 .NET 工具使用方式問題進行疑難排解 (部分機器翻譯)。

另請參閱

如需詳細資訊，請參閱 .NET 工具 (部分機器翻譯)

共用方式為