How to publish a dotnet global tool with .NET Core 2.1

People doing web development are used to install tools using npm. For instance, you can install TypeScript using npm install -g TypeScript. Then you can use TypeScript directly from the command line. This is very convenient. .NET Core 2.1 allows creating tools that can be installed the same way as Node.js. This feature provides a simple way to create and share cross-platform console tools.

.NET tools are packaged as NuGet packages, so you rely on processes that are well proven!

#Create the project

First, you need to download .NET Core 2.1 SDK. Then you need to create a console application that targets .NET Core 2.1. You can use the command line or Visual Studio. Let's use the command line (it's very easy):

dotnet new console

This creates a basic console project that prints "Hello world" to the console.

Now, let's modify the project file to add the tool configuration. You need to add <PackAsTool> and ToolCommandName. The first one indicates that the NuGet package to create is not a library but a tool. The second one indicates the name of the command to run your tool from the command line.

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

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

    <PackAsTool>true</PackAsTool>
    <ToolCommandName>MyDotNetCoreTool</ToolCommandName>
  </PropertyGroup>

</Project>

That all you need to create a .NET Core global tool, now we can publish it!

#Publish the tool on NuGet

A tool is just a package NuGet, so to publish the tool and make it available to everyone, you just need to publish the NuGet package as any other NuGet package.

First, you need to get an API key on nuget.org: https://www.nuget.org/account/apikeys.

Create NuGet API key on nuget.org

Copy the generated NuGet API key

Then, you can create the package and publish it to NuGet:

dotnet pack --configuration Release
dotnet nuget push .\bin\release\MyDotNetCoreTool.1.0.0.nupkg --source https://api.nuget.org/v3/index.json --api-key <Your NuGet API key>

It will take a few minutes for the package to be indexed and become available.

Package on NuGet.org

#Install the tool

The command line to install the tool is visible on NuGet, so the following command is not a surprise 😉

dotnet tool install --global MyDotNetCoreTool

Install the MyDotNetCoreTool using the command line

Then, you can use the tool using the name set in <ToolCommandName>:

MyDotNetCoreTool

Run MyDotNetCoreTool from the command line

#List the .NET Core global tools installed on the machine

If you don't remember the tools you installed, you can run the following command to get the full list:

dotnet tool list -g

List of globally installed .NET tools

#Update the tool

If you want to update the tool, you must publish a newer version of the NuGet package. You can set the version of the generated NuGet package in the csproj file using the <Version> element:

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

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

    <PackAsTool>true</PackAsTool>
    <ToolCommandName>MyDotNetCoreTool</ToolCommandName>
    <Version>2.0.0</Version>
  </PropertyGroup>

</Project>

Then, you can use the same commands as to publish the first NuGet package:

dotnet pack --configuration Release
dotnet nuget push .\bin\release\MyDotNetCoreTool.2.0.0.nupkg --source https://api.nuget.org/v3/index.json --api-key <Your NuGet API key>

There is no auto-update functionality, so the users of your tool must update it manually when needed.

dotnet tool update --global MyDotNetCoreTool

#Uninstall the tool

You can uninstall a tool using the following command:

dotnet tool uninstall --global MyDotNetCoreTool

The tool won't be available from the command line anymore. You can check the tool is well uninstall by running dotnet tool list -g

#Test a tool without publishing it on NuGet

When you create a tool, you may want to test it on your computer without publishing it on NuGet.org or any NuGet server. The command line allows to specify the feed source. This source can be a local repository. So, you can use the following command lines:

dotnet pack --output ./
dotnet tool install -g MyDotNetCoreTool --add-source ./

If you want to try a new version, you first need to uninstall the tool or update it

dotnet tool uninstall -g MyDotNetCoreTool
dotnet tool install -g MyDotNetCoreTool --add-source ./

or

dotnet tool update -g MyDotNetCoreTool --add-source ./

#Conclusion

.NET Core global tools provide a simple way to create and share cross-platform console tools. There are so easy to create. I think many tools will be created in the next months. Here are some tools:

• https://github.com/natemcmaster/dotnet-serve/
• https://github.com/meziantou/UnlockFile
• https://github.com/meziantou/Recompress

Do you have a question or a suggestion about this post? Contact me!