教學課程：使用 .NET CLI 建立 .NET 工具

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

本教學課程會教導您如何建立和封裝 .NET 工具。 .NET CLI 可讓您建立控制台應用程式做為工具，其他人可以安裝並執行。 .NET 工具是從 .NET CLI 安裝的 NuGet 套件。 如需工具的詳細資訊，請參閱 .NET 工具概觀。

你將建立的工具是一個主控台應用程式，會取得目前 .NET 環境的資訊並顯示，包括 .NET 版本、作業系統細節以及主要的環境變數設定。

這個教學是三集教學系列中的第一篇。 在本教學課程中，您會建立並封裝工具。 在接下來的兩個教學中，你會 把工具當作全域工具使用 ，並 把工具當作本地工具使用。 建立工具的程序無論是作為全域工具還是本機工具都是相同的。

先決條件

• .NET SDK 10.0 或更新版本。

  本教學使用 .NET SDK 10.0，但本指南適用於 .NET 8.0 及更新版本。

• 選擇您喜好的文字編輯器或程式碼編輯器

建立專案

1. 開啟命令提示字元，並建立名為 存放庫的資料夾。

2. 瀏覽至存放 庫 資料夾，然後輸入下列命令：

   dotnet new console -n dotnet-env
   

   指令會在 repository 資料夾下方建立一個名為 dotnet-env 的新資料夾。

3. 進入 dotnet-env 資料夾。

   cd dotnet-env
   

新增程式碼

1. 使用程式代碼編輯器開啟 Program.cs 檔案。

2. 請將內容替換為以下代碼：

   using System.Reflection;
   using System.Runtime.InteropServices;
   
   var versionString = Assembly.GetEntryAssembly()?
                           .GetCustomAttribute<AssemblyInformationalVersionAttribute>()?
                           .InformationalVersion
                           .ToString();
   
   Console.WriteLine($"dotnet-env v{versionString}");
   Console.WriteLine(new string('-', 40));
   
   Console.WriteLine();
   Console.WriteLine("Runtime");
   Console.WriteLine($"  .NET Version          {Environment.Version}");
   Console.WriteLine($"  Framework             {RuntimeInformation.FrameworkDescription}");
   Console.WriteLine($"  Runtime Identifier    {RuntimeInformation.RuntimeIdentifier}");
   
   Console.WriteLine();
   Console.WriteLine("System");
   Console.WriteLine($"  OS                    {RuntimeInformation.OSDescription}");
   Console.WriteLine($"  Architecture          {RuntimeInformation.OSArchitecture}");
   Console.WriteLine($"  Machine Name          {Environment.MachineName}");
   Console.WriteLine($"  Processor Count       {Environment.ProcessorCount}");
   
   Console.WriteLine();
   Console.WriteLine("Environment Variables");
   string[] envVars = { "DOTNET_ROOT", "DOTNET_HOST_PATH",
                           "DOTNET_CLI_HOME", "DOTNET_NOLOGO",
                           "NUGET_PACKAGES", "DOTNET_ENVIRONMENT" };
   
   foreach (string name in envVars)
   {
       string? value = Environment.GetEnvironmentVariable(name);
       Console.WriteLine($"  {name,-24}{value ?? "(not set)"}");
   }
   

   程式使用頂層語句讀取程序集的資訊版本，然後使用Assembly.GetEntryAssembly()和AssemblyInformationalVersionAttribute，然後列出應用程式名稱與分隔符行，然後顯示三個資訊區塊：

   • Runtime — .NET版本、框架描述及執行時識別碼，使用Environment.Version 和 RuntimeInformation。
   • 系統 — 作業系統描述、架構、機器名稱及處理器數量。
   • 環境變數 — 六個關鍵的.NET相關變數（DOTNET_ROOT、DOTNET_HOST_PATH、DOTNET_CLI_HOME、DOTNET_NOLOGO、NUGET_PACKAGES 和 DOTNET_ENVIRONMENT），顯示未設定的變數為(not set)。

   using System.Reflection指令是對 Assembly.GetEntryAssembly() 和 AssemblyInformationalVersionAttribute所必需的。 using System.Runtime.InteropServices 指令是 RuntimeInformation 的必要條件。

3. 儲存您的變更。

測試應用程式

執行專案並查看輸出：

dotnet run

輸出看起來類似下列範例：

dotnet-env v1.0.0
----------------------------------------

Runtime
  .NET Version          10.0.4
  Framework             .NET 10.0.4
  Runtime Identifier    win-x64

System
  OS                    Microsoft Windows 10.0.22631
  Architecture          X64
  Machine Name          MY-MACHINE
  Processor Count       16

Environment Variables
  DOTNET_ROOT             (not set)
  DOTNET_HOST_PATH        (not set)
  DOTNET_CLI_HOME         (not set)
  DOTNET_NOLOGO           (not set)
  NUGET_PACKAGES          (not set)
  DOTNET_ENVIRONMENT      (not set)

封裝工具

若要將應用程式打包並分發為工具，請修改專案檔案。

1. 打開 dotnet-env.csproj 檔案，並在節點末端 <PropertyGroup> 新增三個 XML 節點：

   <PackAsTool>true</PackAsTool>
   <ToolCommandName>dotnet-env</ToolCommandName>
   <PackageOutputPath>./nupkg</PackageOutputPath>
   

   <ToolCommandName> 是一個可選元素，用來指定安裝後呼叫工具的指令。 如果未提供這個元素，工具的命令名稱就是組件名稱，通常是沒有 .csproj 擴展名的項目檔名稱。

   備註

   為 <ToolCommandName>選擇唯一值。 避免使用副檔名（例如 .exe 或 .cmd），因為這個工具是安裝在應用程式主機上，指令不應該包含副檔名。 這有助於防止與現有命令發生衝突，並確保安裝體驗順暢。

   <PackageOutputPath> 是一個可選元素，決定 .NET 在哪裡產生 NuGet 套件。 .NET CLI 使用 NuGet 套件來安裝你的工具。

   專案檔現在看起來像下列範例：

   <Project Sdk="Microsoft.NET.Sdk">
   
     <PropertyGroup>
   
       <OutputType>Exe</OutputType>
       <TargetFramework>net10.0</TargetFramework>
       <ImplicitUsings>enable</ImplicitUsings>
       <Nullable>enable</Nullable>
   
       <PackAsTool>true</PackAsTool>
       <ToolCommandName>dotnet-env</ToolCommandName>
       <PackageOutputPath>./nupkg</PackageOutputPath>
   
     </PropertyGroup>
   
   </Project>
   

2. 執行 dotnet pack 命令來建立 NuGet 套件：

   dotnet pack
   

   dotnet-env.1.0.0.nupkg 檔案建立於以 <PackageOutputPath>dotnet-env.csproj 檔案值識別的資料夾中，該資料夾在此範例中為 ./nupkg 資料夾。

   若要公開釋出工具，請將其上傳至 https://www.nuget.org。 當工具在 NuGet 上架後，開發者可以使用 dotnet tool install 指令安裝。 在本教學課程中，您會直接從本機 nupkg 資料夾安裝套件，因此不需要將套件上傳至 NuGet。

Troubleshoot

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

後續步驟

在本教學課程中，您已建立控制台應用程式，並將其封裝為工具。 若要瞭解如何使用此工具作為全域工具，請繼續進行下一個教學課程。

如果您想要的話，您可以略過全域工具教學課程，並直接移至本機工具教學課程。

另請參閱

• 建立專門針對 RID 及 AOT .NET 的工具