Create a .NET Core Global Tool using the .NET Core CLI

This article teaches you how to create and package a .NET Core Global Tool. The .NET Core CLI allows you to create a console application as a Global Tool, which others can easily install and run. .NET Core Global Tools are NuGet packages that are installed from the .NET Core CLI. For more information about Global Tools, see .NET Core Global Tools overview.

This topic applies to: ✓ .NET Core SDK 2.1.300 and later versions

Create a project

This article uses the .NET Core CLI to create and manage a project.

Our example tool will be a console application that generates an ASCII bot and prints a message. First, create a new .NET Core Console Application.

dotnet new console -o botsay

Navigate to the botsay directory created by the previous command.

Add the code

Open the Program.cs file with your favorite text editor, such as vim or Visual Studio Code.

Add the following using directive to the top of the file, this helps shorten the code to display the version information of the application.

using System.Reflection;

Next, move down to the Main method. Replace the method with the following code to process the command-line arguments for your application. If no arguments were passed, a short help message is displayed. Otherwise, all of those arguments are transformed into a string and printed with the bot.

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));
}

Create the bot

Next, add a new method named ShowBot that takes a string parameter. This method prints out the message and the ASCII bot. The ASCII bot code was taken from the dotnetbot sample.

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

Test the tool

Run the project and see the output. Try these variations of the command-line to see different results:

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

All arguments after the -- delimiter are passed to your application.

Setup the global tool

Before you can pack and distribute the application as a Global Tool, you need to modify the project file. Open the botsay.csproj file and add three new XML nodes to the <Project><PropertyGroup> node:

  • <PackAsTool>
    [REQUIRED] Indicates that the application will be packaged for install as a Global Tool.

  • <ToolCommandName>
    [OPTIONAL] An alternative name for the tool, otherwise the command name for the tool will be named after the project file. You can have multiple tools in a package, choosing a unique and friendly name helps differentiate from other tools in the same package.

  • <PackageOutputPath>
    [OPTIONAL] Where the NuGet package will be produced. The NuGet package is what the .NET Core CLI Global Tools uses to install your tool.

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp2.1</TargetFramework>

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

  </PropertyGroup>

</Project>

Even though <PackageOutputPath> is optional, use it in this example. Make sure you set it: <PackageOutputPath>./nupkg</PackageOutputPath>.

Next, create a NuGet package for your application.

dotnet pack

The botsay.1.0.0.nupkg file is created in the folder identified by the <PackageOutputPath> XML value from the botsay.csproj file, which in this example is the ./nupkg folder. This makes it easy to install and test. When you want to release a tool publicly, upload it to https://www.nuget.org.

Now that you have a package, install the tool from that package:

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

The --add-source parameter tells the .NET Core CLI to temporarily use the ./nupkg folder (our <PackageOutputPath> folder) as an additional source feed for NuGet packages. For more information about installing Global Tools, see .NET Core Global Tools overview.

If installation is successful, a message is displayed showing the command used to call the tool and the version installed, similar to the following example:

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

You should now be able to type botsay and get a response from the tool.

Note

If the install was successful, but you cannot use the botsay command, you may need to open a new terminal to refresh the PATH.

Remove the tool

Once you're done experimenting with the tool, you can remove it with the following commnand:

dotnet tool uninstall -g botsay