Dotnet tools are applications that can assist you with various tasks and functionality. There are tools for checking test coverage, deploying to certain cloud services, code formatting, etc... Nuget has a list here.

The following article will help you get started with the tools using the Swagger CLI, called Swashbuckle.AspNetCore.Cli, as an example.

The cheatsheet

dotnet new tool-manifest # Create a tool manifest file

dotnet tool list # List installed tools

dotnet tool install ToolName # Install a tool

dotnet tool restore # Install the tools in the manifest file

dotnet tool update ToolName # Update a tool

dotnet tool uninstall ToolName # Uninstall a tool

dotnet ToolName # Run a tool

The walkthrough

Local and global tools

Tools can be installed locally or globally. Locally installed tools only work for the specific project, but can leverage the tool manifest file which make the tool setup more portable.

Globally installed tools are available everywhere. The commands for global tools are the same, but the --global flag must be passed on.

The tool manifest file

The command dotnet new tool-manifest will create a file .config/dotnet-tools.json. It is a file that contains a list of the installed tools and which version. If you are familiar with the package.json file in npm, this file has the same purpose. The empty file looks like this:

{
  "version": 1,
  "isRoot": true,
  "tools": {}
}

When tools are installed, the tools object will be populated with data about the tools.

Install a tool

dotnet tool install Swashbuckle.AspNetCore.Cli will install the Swagger CLI and add it to the manifest file. If you want a specific version, add --version x.y.z. If you have multiple Nuget sources added, the installation might fail since the installer will look in the wrong source first. Add --ignore-failed-sources to circumvent this.

This is the manifest file with the tool installed:

  "tools": {
    "swashbuckle.aspnetcore.cli": {
      "version": "5.5.1",
      "commands": [
        "swagger"
      ]
    }
  }

Run a tool

From the manifest file, we can see that the Swagger CLI comes with the command swagger. This means it can be executed with dotnet swagger.

The Swagger CLI generates the Swagger documentation. It only has one command, tofile and takes two required arguments, the path to the compiled .dll file and which version of the API that should be exported.

dotnet swagger tofile bin/debug/net.../something.dll 1

List tools

Run dotnet tool list to see installed tools. This command is especially useful when listing global tools, since no manifest file exists for these.

➜ dotnet tool list
Package Id                   Version   Commands   Manifest
-------------------------------------------------------------------------------------
swashbuckle.aspnetcore.cli   5.5.1     swagger    ...tools/.config/dotnet-tools.json