dotnet new - Behind the Scenes
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
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.
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.
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.