Create your own "dotnet new" project templates

In case you haven't heard, Visual Studio 2017 RTM was officially released this week. With this exciting news, came the launch of the final 1.0 release of the .NET Core Tools. You can use this tooling to create .NET applications for cross platform use.

dotnet new

Jumping right in - Using the CLI, it's really easy to quickly bootstrap your application based on pre-defined templates.

From your favorite command line interface, execute dotnet new

$ dotnet new
Template Instantiation Commands for .NET Core CLI.

Usage: dotnet new [arguments] [options]

Arguments:  
  template  The template to instantiate.

Options:  
  -l|--list         List templates containing the specified name.
  -lang|--language  Specifies the language of the template to create
  -n|--name         The name for the output being created. If no name is specified, the name of the current directory is used.
  -o|--output       Location to place the generated output.
  -h|--help         Displays help for this command.
  -all|--show-all   Shows all templates


Templates                 Short Name      Language      Tags  
----------------------------------------------------------------------
Console Application       console         [C#], F#      Common/Console  
Class library             classlib        [C#], F#      Common/Library  
Unit Test Project         mstest          [C#], F#      Test/MSTest  
xUnit Test Project        xunit           [C#], F#      Test/xUnit  
ASP.NET Core Empty        web             [C#]          Web/Empty  
ASP.NET Core Web App      mvc             [C#], F#      Web/MVC  
ASP.NET Core Web API      webapi          [C#]          Web/WebAPI  
Solution File             sln                           Solution

Examples:  
    dotnet new mvc --auth None --framework netcoreapp1.1
    dotnet new mstest --framework netcoreapp1.1
    dotnet new --help

As you can see, it comes with standard templates out of the box for creating web apps, console apps, libraries and test projects.

Creating a custom template

We will be creating a new template called "Awesome Sauce" that simply scaffolds a new Console application that writes something to the output.

We start of by creating a folder called AwesomeSauce somewhere on disk. Inside it, create another folder called .template.config, followed by a new file template.json inside it:

--AwesomeSauce
  `--.template.config
      `--template.json

Inside the template.json we define the metadata for the template. For simplicity let's just add the required fields to the file:

{
  "author": "Fanie Reynders",
  "classifications": [ "Console", "Awesome Sauce" ],
  "name": "This creates a new Awesome Console App",
  "tags": {
    "language": "C#"
  },
  "identity": "FanieReynders.AwesomeSauce",
  "shortName": "awesomesauce",
  "sourceName": "_AwesomeSauce"
}

Now we're ready to build the content of the template. Inside the AwesomeSauce folder, we create two files:

_AwesomeSauce.csproj

<Project Sdk="Microsoft.NET.Sdk">  
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFramework>netcoreapp1.1</TargetFramework>
  </PropertyGroup>
</Project>  

Program.cs

using System;  
namespace _AwesomeSauce  
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Greetings from _AwesomeSauce!");
        }
    }
}

It is important to point out that the value of the  sourceName field inside the template.json file will be used as a marker to replace all occurances of "_AwesomeSauce" to the name of the newly created project when the template executes.

Installing the new template

It is possible to install templates from disk or from Nuget. In this example we will just simply grab the template from disk.

From the CLI execute dotnet new specifying the source directory of the template for the -i parameter:

$ dotnet new -i c:\sandbox\AwesomeSauce

Now if we execute dotnet new -l we will see the newly added template awesomesauce in the list.

Trying it out

Let's test our template! From the CLI, we execute the template giving the new project the name of "Foo":

$ dotnet new awesomesauce -n Foo

When it executes we notice that the files Foo.csproj and Program.cs are created and here's the contents of Program.cs:

namespace Foo  
{
    class Program
    {
        static void Main(string[] args)
        {
            Console.WriteLine("Greetings from Foo!");
        }
    }
}

As expected, all occurences of _AwesomeSauce is now replaced with Foo.

Happy templating on .NET Core!