Cake.DotNetLocalTools.Module

A Cake Module that extends Cake with functionality to install tools from a .NET tool manifest.

The major version and target framework of the package tracks the version of Cake it was built for. Currently, version 3.* of Cake.DotNetLocalTools.Module is built for Cake 3.0 and support .NET 6 and .NET 7.

Overview

Cake allows installing .NET CLI Tools through the #tool preprocessor directies and Cake.Frosting's InstallTool method (see Installing and using tools for details).

.NET Core 3.1 introduced the concept of "local tools". Local tools are listed in a "tool manifest" (dotnet-tools.json) and run through the dotnet command.

Cake.DotNetLocalTools.Module brings these two concepts together. It reads a list of tools from one or more tool manifests and installs them through Cake's tool infrastructure. This way, you can easily use the tools from Cake while still having the tools and their versions described in a common format.

Usage

Cake Script

To use the module in a Cake script file, perform the following steps d

1. Add the preprocessor directive to install the module

   #module nuget:?package=Cake.DotNetLocalTools.Module&version=VERSION

2. Install tools using the #tool preprocessor directive and a uri scheme of toolmanifest:

   #tool "toolmanifest:?package=.config/dotnet-tools.json"

Cake.Frosting

To use the module in a Cake.Frosting project, perform the following steps.

1. Install the module package by adding a package reference to your project

   <PackageReference Include="Cake.DotNetLocalTools.Module" Version="VERSION" /> 

2. Register LocalToolsModule with the Cake Host:

   using Cake.DotNetLocalTools.Module;
   
   public static int Main(string[] args)
   {
       return new CakeHost()
           // Register LocalToolsModule
           .UseModule<LocalToolsModule>()        
           // Continue with the standard setup of a Cake.Frosting project
           .UseContext<BuildContext>()
           .Run(args);
   }

3. You can not install tools using either the InstallToolsFromManifest() method or using InstallTools() with a uri scheme of toolmanifest:

   using Cake.DotNetLocalTools.Module;
   
   public static int Main(string[] args)
   {
       return new CakeHost()
           // Register LocalToolsModule
           .UseModule<LocalToolsModule>() 
           // Install Tools (both install options are equivalent)
           .InstallToolsFromManifest(".config/dotnet-tools.json")       
           .InstallTools(new Uri("tool-manifest:?package=.config/dotnet-tools.json"))       
           // Continue with the standard setup of a Cake.Frosting project
           .UseContext<BuildContext>()
           .Run(args);
   }

Example

Installing tools from a tool manifest is equivalent to installing the tools listed in the manifest using a #tool preprocessor directive or through InstallTool().

For example, a tool manifest at .config/dotnet-tools.json could look like this:

{
  "version": 1,
  "isRoot": true,
  "tools": {
    "nbgv": {
      "version": "3.4.231",
      "commands": [
        "nbgv"
      ]
    },
    "dotnet-format": {
      "version": "5.1.225507",
      "commands": [
        "dotnet-format"
      ]
    },
    "dotnet-reportgenerator-globaltool": {
      "version": "4.8.12",
      "commands": [
        "reportgenerator"
      ]
    }
  }
}

Tools from the manifest can be installed using

#tool "toolmanifest:?package=.config/dotnet-tools.json"

This is equivalent to installing each tool individually:

#tool "dotnet:?package=nbgv&version=3.4.231"
#tool "dotnet:?package=dotnet-format&version=5.1.225507"
#tool "dotnet:?package=dotnet-reportgenerator-globaltool&version=4.8.12"

Building from source

Note: This repository uses git submodules, so please use git clone --recursive to also clone the submodules.

Building the project from source requires the .NET 7 SDK (version 7.0.100 as specified in global.json).

To build the project, run

.\build.ps1

This will

• Download the required version of the .NET SDK
• Build the project
• Run all tests
• Pack the NuGet package.

Versioning and Branching

The version of the library is automatically derived from git and the information in version.json using Nerdbank.GitVersioning:

• The master branch always contains the latest version. Packages produced from master are always marked as pre-release versions (using the -pre suffix).
• Stable versions are built from release branches. Build from release branches will have no -pre suffix
• Builds from any other branch will have both the -pre prerelease tag and the git commit hash included in the version string

To create a new release branch use the nbgv tool:

dotnet tool install --global nbgv
nbgv prepare-release