教程:使用 .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>net8.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 工具使用问题

后续步骤

在本教程中,你创建了一个控制台应用程序并将其打包为工具。 若要了解如何使用该工具作为全局工具,请转到下一教程。

如果需要,可以跳过全局工具教程,直接转到本地工具教程。