How to publish a dotnet global tool with .NET Core 2.1
- Gérald Barré
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
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.
#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
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
<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 ./
dotnet tool update -g MyDotNetCoreTool --add-source ./
.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:
Do you have a question or a suggestion about this post? Contact me!