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

Web developers are used to installing tools via npm. For instance, you can install TypeScript with npm install -g TypeScript and use it directly from the command line. .NET Core 2.1 brings the same convenience to the .NET ecosystem, providing a simple way to create and share cross-platform console tools.

.NET tools are packaged as NuGet packages, so you can rely on a well-proven publishing process.

#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 update the project file to add the tool configuration. You need to add <PackAsTool> and <ToolCommandName>. The first property tells the SDK to produce a tool package instead of a library. The second sets the command name used to invoke your tool from the terminal.

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

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

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

</Project>

That's all you need to create a .NET Core global tool. Now you can publish it!

#Publish the tool on NuGet

A tool is just a NuGet package, so to make it available to everyone, you publish it the same way 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 install command is shown on the NuGet package page:

dotnet tool install --global MyDotNetCoreTool

Install the MyDotNetCoreTool using the command line

Then, you can invoke the tool by the name defined 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 will no longer be available from the command line. You can confirm it was uninstalled by running dotnet tool list -g.

#Test a tool without publishing it on NuGet

When creating a tool, you may want to test it locally without publishing to NuGet.org or any NuGet server. The install command allows you to specify a local folder as the package source:

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

If you want to test a new version, first uninstall the existing 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. They are easy to create, and I expect many more to appear in the coming months. Here are a few examples:

• 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!