Using dotnet tools
Tags: dotnet, tooling
Published: 2022-04-12 17:03:44

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](https://www.nuget.org/packages?packagetype=dotnettool).

The following article will help you get started with the tools using the [Swagger CLI](https://www.nuget.org/packages/Swashbuckle.AspNetCore.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:

```json
{
  "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:
```json
  "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
```


## Restore tools
Since the manifest file keeps track of the tools, they can easily be restored on a new machine by running `dotnet tool restore`.


## Uninstall tools
`dotnet tool uninstall swashbuckle.aspnetcore.cli` will uninstall the Swagger CLI. 


# Summary
There you have it! Explore the [available tools](https://www.nuget.org/packages?packagetype=dotnettool), there's probably a tool out there which will enhance your development experience.