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

本文適用於: ✔️ .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 命令。

  1. 開啟 .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"
          ]
        }
      }
    }
    
  2. 儲存變更。

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

  3. 執行 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.
    
  4. 確認工具可供使用:

    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
    
  5. 測試工具:

    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 工具 (部分機器翻譯)