dotnet new - Behind the Scenes

The `dotnet new` command

One of my favourite things about .NET Core is the dotnet command line tool. With dotnet new, you can quickly scaffold a new project of various types. For example dotnet new webapp creates an ASP.NET Core web app. And if you simply type dotnet new you can see a list of all of the available templates.

Templates               Short Name         Language        Tags
-------------------------------------------------------------------------
Console Application     console            [C#], F#, VB    Common/Console
Class library           classlib           [C#], F#, VB    Common/Library
Unit Test Project       mstest             [C#], F#, VB    Test/MSTest
NUnit 3 Test Project    nunit              [C#], F#, VB    Test/NUnit
NUnit 3 Test Item       nunit-test         [C#], F#, VB    Test/NUnit
xUnit Test Project      xunit              [C#], F#, VB    Test/xUnit
Razor Component         razorcomponent     [C#]            Web/ASP.NET
Razor Page              page               [C#]            Web/ASP.NET
MVC ViewImports         viewimports        [C#]            Web/ASP.NET

Installing templates

Of course, there may not be templates available out of the box that meet your needs, but it's very easy to install additional templates. For example, if you want to create a Vue.js project, you can install a new template pack with dotnet new --install "Microsoft.AspNetCore.SpaTemplates" and then create a new project with dotnet new vue.

Questions

Now as cool as this feature is, it left me with a bunch of questions. Where are all these templates coming from? If I install a template pack, how do I keep it up to date? How do I find out what other template packs are available? If I wanted to make my own template, how would I do that? So I did a bit of digging, and here's what I found.

Templates are stored in NuGet packages

Templates are distributed as NuGet packages (.nupkg), typically hosted on NuGet.org, but you can install them from any NuGet server. The Vue.js template pack I mentioned earlier can be found here. Knowing this is very handy as it enables you to see whether the package is still being actively maintained, and whether there have been recent updates. Looks like this particular template pack hasn't been updated in a while.

How do I know what's available?

How can you find out what template packs are available? There are two main ways I know of.

First, there's this list maintained on GitHub containing many packages.

Second, there's a great searchable website at dotnetnew.azurewebsites.net. So if I'm looking for more up to date Vue.js templates, I can see that there is a very wide choice available.

How do I know what template versions I have?

This one took me a while to find, but I discovered that if you type dotnet new -u (the uninstall command) it gives you a really nice summary of each package installed, in this kind of format.

  Microsoft.AspNetCore.Blazor.Templates
    Details:
      NuGetPackageId: Microsoft.AspNetCore.Blazor.Templates
      Version: 0.7.0
      Author: Microsoft
    Templates:
      Blazor (hosted in ASP.NET server) (blazorhosted) C#
      Blazor Library (blazorlib) C#
      Blazor (Server-side in ASP.NET Core) (blazorserverside) C#
      Blazor (standalone) (blazor) C#
    Uninstall Command:
      dotnet new -u Microsoft.AspNetCore.Blazor.Templates

This command also conveniently shows the syntax to uninstall a template package.

How do I know when updates are available?

Of course, you don't want to have to constantly visit NuGet.org to check up on new versions of template packs, so how do you know when something updated is available? Well the good news is that there are a couple of helpful commands here for you.

First, to update a package to it's latest version, you can always simply install it again. So if I say dotnet new -i Microsoft.AspNetCore.Blazor.Templates, then I'll either install the Blazor templates, or update to the latest (non-prelease) version if they are already installed.

There are also a couple of new commands that perform an update check for you. dotnet new --update-check will check to see if there are new versions of any installed templates, and dotnet new --update-apply also updates them for you.

Note: I attempted to use this feature by deliberately installing an older version of a template, and then running the update check, but it reported that no updates were available. I don't know if that was because by explicitly specifying a version I had perhaps "pinned" to that version, or whether it was just a temporary glitch with the tool.

How do I install a specific template version?

Because templates are stored in NuGet packages, you might want to install a specific version (maybe a pre-release). For example, at the moment, to play with the new WebAssembly Blazor features, you need to install a pre-release of the Microsoft.AspNetCore.Blazor.Templates. That can easily be done by appending :: and the package number after the package name:

dotnet new -i Microsoft.AspNetCore.Blazor.Templates::3.0.0-preview9.19465.2

How can I create my own templates?

Finally, you might be wondering what it takes to create your own template. I'm not going to go into detail here, as there's a helpful tutorial on the Microsoft docs site. But it's relatively straightforward. You create the source files for the template, and a template.json that contains template metadata.

A great way to get a feel for what's possible is to use the excellent NuGet Package Explorer utility to take a look inside the contents of existing NuGet package templates.

Summary

dotnet new is a great productivity tool and once you know a little bit more about what's going on behind the scenes, you can confidently install and update additional template packs to greatly speed up your daily development tasks.

The dotnet new command