使用 .NET Core CLI 创建 .NET Core 全局工具Create a .NET Core Global Tool using the .NET Core CLI

本文内容

本文介绍如何创建和打包 .NET Core 全局工具。使用 .NET Core CLI，可以创建一个控制台应用程序作为全局工具，便于其他人轻松地安装并运行。.NET core 全局工具是从 .NET Core CLI 安装的 NuGet 包。有关全局工具的详细信息，请参阅 .NET Core 全局工具概述。

本文适用于：✓ .NET Core 2.1 SDK

创建项目Create a project

本文使用 .NET Core CLI 创建和管理项目。

我们的示例工具是一个可以生成 ASCII 自动程序并打印消息的控制台应用程序。首先，创建新的 .NET Core 控制台应用程序。

  1. dotnet new console -o botsay

导航到由先前命令创建的 botsay 目录。

添加代码Add the code

使用喜欢的文本编辑器（如 vim 或 Visual Studio Code）打开 Program.cs 文件。

将以下 using 指令添加到文件顶部，这有助于缩短代码以显示应用程序的版本信息。

  1. using System.Reflection;

接下来，向下移动到 Main 方法。将方法替换为以下代码，以便处理应用程序的命令行参数。如果未传递任何参数，将显示简短的帮助消息。否则，所有这些参数都将转换为字符串并使用自动程序打印。

  1. static void Main(string[] args)
  2. {
  3.     if (args.Length == 0)
  4.     {
  5.         var versionString = Assembly.GetEntryAssembly()
  6.                                 .GetCustomAttribute<AssemblyInformationalVersionAttribute>()
  7.                                 .InformationalVersion
  8.                                 .ToString();
  10.         Console.WriteLine($"botsay v{versionString}");
  11.         Console.WriteLine("-------------");
  12.         Console.WriteLine("\nUsage:");
  13.         Console.WriteLine("  botsay <message>");
  14.         return;
  15.     }
  17.     ShowBot(string.Join(' ', args));
  18. }

创建自动程序Create the bot

接下来，添加一个名为 ShowBot 的新方法，该方法采用一个字符串参数。此方法将输出消息和 ASCII 自动程序。ASCII 自动程序代码摘自 dotnetbot 示例。

  1. static void ShowBot(string message)
  2. {
  3.     string bot = $"\n        {message}";
  4.     bot += @"
  5.     __________________
  6.                       \
  7.                        \
  8.                           ....
  9.                           ....'
  10.                            ....
  11.                         ..........
  12.                     .............'..'..
  13.                  ................'..'.....
  14.                .......'..........'..'..'....
  15.               ........'..........'..'..'.....
  16.              .'....'..'..........'..'.......'.
  17.              .'..................'...   ......
  18.              .  ......'.........         .....
  19.              .    _            __        ......
  20.             ..    #            ##        ......
  21.            ....       .                 .......
  22.            ......  .......          ............
  23.             ................  ......................
  24.             ........................'................
  25.            ......................'..'......    .......
  26.         .........................'..'.....       .......
  27.      ........    ..'.............'..'....      ..........
  28.    ..'..'...      ...............'.......      ..........
  29.   ...'......     ...... ..........  ......         .......
  30.  ...........   .......              ........        ......
  31. .......        '...'.'.              '.'.'.'         ....
  32. .......       .....'..               ..'.....
  33.    ..       ..........               ..'........
  34.           ............               ..............
  35.          .............               '..............
  36.         ...........'..              .'.'............
  37.        ...............              .'.'.............
  38.       .............'..               ..'..'...........
  39.       ...............                 .'..............
  40.        .........                        ..............
  41.         .....
  42. ";
  43.     Console.WriteLine(bot);
  44. }

测试工具Test the tool

运行项目并观察输出。尝试使用命令行的这些变体来查看不同的结果：

  1. dotnet run
  2. dotnet run -- "Hello from the bot"
  3. dotnet run -- hello from the bot

位于 — 分隔符后的所有参数均会传递给应用程序。

安装全局工具Setup the global tool

在将应用程序作为全局工具打包并分发之前，你需要修改项目文件。打开 botsay.csproj 文件，并向 <Project><PropertyGroup> 节点添加三个新的 XML 节点：

  • <PackAsTool>[必需] 表示将打包应用程序以作为全局工具进行安装。

  • <ToolCommandName>[可选] 工具的替代名称，否则工具的命令名称将以项目文件命名。一个包中可以有多个工具，选择一个唯一且友好的名称有助于与同一包中的其他工具区别开来。

  • <PackageOutputPath>[可选] 将生成 NuGet 包的位置。NuGet 包是.NET Core CLI 全局工具用于安装你的工具的包。

  1. <Project Sdk="Microsoft.NET.Sdk">
  3.   <PropertyGroup>
  4.     <OutputType>Exe</OutputType>
  5.     <TargetFramework>netcoreapp2.1</TargetFramework>
  7.     <PackAsTool>true</PackAsTool>
  8.     <ToolCommandName>botsay</ToolCommandName>
  9.     <PackageOutputPath>./nupkg</PackageOutputPath>
  11.   </PropertyGroup>
  13. </Project>

虽然 <PackageOutputPath> 不是必选的，请在本示例中使用它。请务必将其设置为：<PackageOutputPath>./nupkg</PackageOutputPath>。

接下来，创建应用程序的 NuGet 包。

  1. dotnet pack

botsay.1.0.0.nupkg 文件在由 botsay.csproj 文件的 <PackageOutputPath> XML 值标识的文件夹中创建，在本示例中为 ./nupkg 文件夹。这样，就可以轻松地安装和测试了。如果想要公开发布一个工具，请将其上传到 https://www.nuget.org。该工具在 NuGet 上可用后，开发人员就可以使用 dotnet tool install 命令的 —global 选项在用户范围内安装该工具。

现在你已有一个包，请通过该包安装工具：

  1. dotnet tool install --global --add-source ./nupkg botsay

—add-source 参数指示 .NET Core CLI 临时使用 ./nupkg 文件夹（我们的 <PackageOutputPath> 文件夹）作为 NuGet 包的附加源数据源。有关安装全局工具的详细信息，请参阅 .NET Core 全局工具概述。

如果安装成功，会出现一条消息，显示用于调用工具的命令以及所安装的版本，类似于以下示例：

  1. You can invoke the tool using the following command: botsay
  2. Tool 'botsay' (version '1.0.0') was successfully installed.

现在应能够键入 botsay，并获得来自工具的响应。

备注

如果安装已成功，但无法使用 botsay 命令，可能需要打开新的终端来刷新 PATH。

删除工具Remove the tool

完成工具的试验后，可以使用以下命令将其删除：

  1. dotnet tool uninstall -g botsay