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

本文適用于: ✔️.NET Core 2.1 SDK 和更新版本

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

您將建立的工具是一種主控台應用程式,可接受訊息作為輸入,並顯示建立機器人映像的訊息以及文字行。

這是三個教學課程系列中的第一個。 在此教學課程中,您要建立並封裝工具。 在接下來的兩個教學課程中,您要使用此工具作為全域工具,並使用此工具作為本機工具。 不論您是將其當作全域工具還是本機工具使用,建立工具的程序都相同。

必要條件

  • .NET SDK 6.0.100 或更新版本。

    本教學課程使用 .NET SDK 6.0,但全域工具可從 .NET Core SDK 2.1 開始提供。 本機工具可從 .NET Core SDK 3.0 開始取得。

  • 您偏好的文字編輯器或程式碼編輯器。

建立專案

  1. 開啟命令提示字元,並建立名為 repository 的資料夾。

  2. 瀏覽至 repository 資料夾並輸入下列命令︰

    dotnet new console -n microsoft.botsay -f net6.0
    

    此命令會在 repository 資料夾下,建立名為 microsoft.botsay 的新資料夾。

    注意

    在本教學課程中,您會建立以 .NET 6.0 為目標的工具。 若要以不同的架構為目標,請變更 -f|--framework 選項。 若要以多個架構為目標,請將 TargetFramework 元素變更為專案檔中的 TargetFrameworks 元素,如下列範例所示:

    <Project Sdk="Microsoft.NET.Sdk">
      <PropertyGroup>
        <OutputType>Exe</OutputType>
        <TargetFrameworks>netcoreapp3.1;net5.0;net6.0</TargetFrameworks>
      </PropertyGroup>
    </Project>
    
  3. 瀏覽至 microsoft.botsay 資料夾。

    cd microsoft.botsay
    

新增程式碼

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

  2. Program.cs 中的程式碼取代為下列程式碼:

    using System.Reflection;
    
    namespace microsoft.botsay;
    
    internal class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Hello World!");
        }
    }
    

    using System.Reflection;您在下一個步驟中新增的程式碼需要 指示詞。

  3. 使用下列程式碼取代 Main 方法,以處理應用程式的命令列引數。

    static void Main(string[] args)
    {
        if (args.Length == 0)
        {
            var versionString = Assembly.GetEntryAssembly()?
                                    .GetCustomAttribute<AssemblyInformationalVersionAttribute>()?
                                    .InformationalVersion
                                    .ToString();
    
            Console.WriteLine($"botsay v{versionString}");
            Console.WriteLine("-------------");
            Console.WriteLine("\nUsage:");
            Console.WriteLine("  botsay <message>");
            return;
        }
    
        ShowBot(string.Join(' ', args));
    }
    

    如果未傳遞任何引數,則會顯示簡短的說明訊息。 否則,所有引數都會串連成單一字串,並透過呼叫您在下一個步驟中建立的 ShowBot 方法來列印。

  4. 新增名為 ShowBot 並採用字串參數的新方法。 此方法會使用幾行文字列印出機器人的訊息和映像。

    static void ShowBot(string message)
    {
        string bot = $"\n        {message}";
        bot += @"
        __________________
                          \
                           \
                              ....
                              ....'
                               ....
                            ..........
                        .............'..'..
                     ................'..'.....
                   .......'..........'..'..'....
                  ........'..........'..'..'.....
                 .'....'..'..........'..'.......'.
                 .'..................'...   ......
                 .  ......'.........         .....
                 .    _            __        ......
                ..    #            ##        ......
               ....       .                 .......
               ......  .......          ............
                ................  ......................
                ........................'................
               ......................'..'......    .......
            .........................'..'.....       .......
         ........    ..'.............'..'....      ..........
       ..'..'...      ...............'.......      ..........
      ...'......     ...... ..........  ......         .......
     ...........   .......              ........        ......
    .......        '...'.'.              '.'.'.'         ....
    .......       .....'..               ..'.....
       ..       ..........               ..'........
              ............               ..............
             .............               '..............
            ...........'..              .'.'............
           ...............              .'.'.............
          .............'..               ..'..'...........
          ...............                 .'..............
           .........                        ..............
            .....
    ";
        Console.WriteLine(bot);
    }
    
  5. 儲存變更。

測試應用程式

執行專案,並查看輸出結果。 請在命令列嘗試這些變化,以查看不同的結果:

dotnet run
dotnet run -- "Hello from the bot"
dotnet run -- Hello from the bot

-- 分隔符號之後的所有引數會傳遞至您的應用程式。

封裝工具

在您可以封裝應用程式並將其當作工具散佈之前,您應該修改專案檔。

  1. 開啟 microsoft.botsay.csproj 檔案,並將三個新的 XML 節點新增至 <PropertyGroup> 節點的結尾:

    <PackAsTool>true</PackAsTool>
    <ToolCommandName>botsay</ToolCommandName>
    <PackageOutputPath>./nupkg</PackageOutputPath>
    

    <ToolCommandName> 是一個選擇性元素,可指定在安裝工具之後叫用工具的命令。 如果未提供這個專案,工具的命令名稱就是元件名稱,通常是沒有 .csproj 副檔名的專案檔名稱。

    <PackageOutputPath> 是一個選擇性元素,可決定要產生 NuGet 套件的位置。 NuGet 套件是 .NET CLI 用來安裝工具的內容。

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

    <Project Sdk="Microsoft.NET.Sdk">
    
      <PropertyGroup>
    
        <OutputType>Exe</OutputType>
        <TargetFramework>net6.0</TargetFramework>
    
        <PackAsTool>true</PackAsTool>
        <ToolCommandName>botsay</ToolCommandName>
        <PackageOutputPath>./nupkg</PackageOutputPath>
    
      </PropertyGroup>
    
    </Project>
    
  2. 執行 dotnet pack 命令以建立 NuGet 套件:

    dotnet pack
    

    microsoft.botsay.1.0.0.nupkg 檔案隨即在資料夾中建立,此資料夾是以 microsoft.botsay.csproj 檔案中的 <PackageOutputPath> 值識別,在此範例中為 ./nupkg 資料夾。

    當您想要公開發行工具時,您可以將其上傳至 https://www.nuget.org。 當該工具可在 NuGet 上取得之後,開發人員就可以使用 dotnet tool install 命令安裝該工具。 在此教學課程中,您要直接從本機 nupkg 資料夾安裝套件,因此不需要將套件上傳至 NuGet。

疑難排解

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

下一步

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

如果需要,您可以略過全域工具教學課程,並直接前往本機工具教學課程。