.NET Core’s Project Templating Engine

Today’s header image was created by Joe Ridley/Beth Martin, the original source for the image is available here

Today’s topic isn’t necessarily new, but that’s fine by me. In fact, Scott Hanselman wrote about today’s topic in February.

On his blog, obviously

What’s the topic, you ask? Templates.

well technically, it’s the new3 command

new3

One of the major new advancements in version 1.0.1 of the .NET Core SDK is the templating engine. In previous versions of the .NET SDK, when you issued the new command

dotnet new

the SDK would create a console application.

As we covered in the third post I wrote on .NET Core

If you wanted to specify a type of new project, you would have to use the -t switch. The following command would create a new xunit test class library

dotnet new -t xunittest

However, since the 1.0.1 update dropped

I’m currently running 1.0.1 on my Mac

the output of the new command is a little different

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 sln
dotnet new --help

As  you can see, we have support for templates now. But what are they?

Templates

Anyone who has used Visual Studio (or has worked in development for long enough) will know that most developers don’t have a huge amount of get up and go.

In fact, laziness one of the Three Virtues of Perl

As such we tend to get really bored of typing the same boiler plate code, over and over again. So much so that most development houses will have their own base templates, NuGet packages or something similar which most new projects are based on.

I know that I’d rather push a few buttons, kick back, and watch my tooling build the starting point for me. There’s just a little too much setup sometimes.

With that in mind, the ASP.NET Core team have done their level best o make starting new .NET Core projects even easier using their new templating engine.

The way it works is you download (or create) a selection of templates – most of them covering the initial set up of a new .NET Core project – and use them as you create new projects.

They’re accessed using the new command, which we’ve seen earlier.

Where Can I Get Templates?

I’d be pretty surprised if you couldn’t find them all over the place by now. The ASP.NET Core team have open sourced the engine, and written (pretty extensively) about how you can go about creating your own templates.

Some folks have even written on how they put theirs together.

I would recommend starting with the canonical set of templates which are offered by the ASP.NET Core team themselves. These templates are all related to SPAs

That’s Single Page Application, in case you didn’t know.

I mentioned, earlier, that the templating engine was a part of the 1.0.1 release of the .NET Core SDK. Whilst that’s true, it’s not the earliest version of the SDK to include the templating engine. The first (publicly available) version to include the templating engine was RC4 of 1.0.

Node is also required

of course it is 😛

version 6.0 or above, to be exact.

If your development machine meets these requirements, and you want to give it a go, then it’s a case of bringing up the terminal and entering

dotnet new --install Microsoft.AspNetCore.SpaTemplates::*

If all goes well, you’ll see a whole bunch of packages get restored

my Mac restored 111 packages

Then a new list of currently installed templates will be listed

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
MVC ASP.NET Core with Angular angular [C#] Web/MVC/SPA
MVC ASP.NET Core with Aurelia aurelia [C#] Web/MVC/SPA
MVC ASP.NET Core with Knockout.js knockout [C#] Web/MVC/SPA
MVC ASP.NET Core with React.js react [C#] Web/MVC/SPA
MVC ASP.NET Core with React.js and Redux reactredux [C#] Web/MVC/SPA
MVC ASP.NET Core with Vue.js vue [C#] Web/MVC/SPA
ASP.NET Core Web API webapi [C#] Web/WebAPI
Solution File sln Solution
Examples:
dotnet new mvc --auth None --framework netcoreapp1.1
dotnet new aurelia
dotnet new --help

Pretty impressive, right?

So How Do I Use One Of Them?

Using these templates requires that you use the terminal. At the time of posting, you can’t access these templates directly in Visual Studio 2017. But I can’t see that as being too much of a big hassle for most cases.

The files that the templating engine generate are fully compatible with the Visual Studio IDEs (as long as the template has been configured correctly, that is). So generating a template in the terminal, then opening it with Visual Studio 2017 or Code is pretty trivial.

Say I wanted to create a .NET Core SPA with Angular2, there’s a template for that. In fact, it’s in the list of installed 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
MVC ASP.NET Core with Angular angular [C#] Web/MVC/SPA
MVC ASP.NET Core with Aurelia aurelia [C#] Web/MVC/SPA
MVC ASP.NET Core with Knockout.js knockout [C#] Web/MVC/SPA
MVC ASP.NET Core with React.js react [C#] Web/MVC/SPA
MVC ASP.NET Core with React.js and Redux reactredux [C#] Web/MVC/SPA
MVC ASP.NET Core with Vue.js vue [C#] Web/MVC/SPA
ASP.NET Core Web API webapi [C#] Web/WebAPI
Solution File sln Solution
Examples:
dotnet new mvc --auth None --framework netcoreapp1.1
dotnet new aurelia
dotnet new --help

So to build a project using this template, I’ll just issue the following command

dotnet new angular

Which produce the following output as soon as the .NET Core SDK templating engine has generated the directory structure and the files that I need

Content generation time: 717.327 ms
The template "MVC ASP.NET Core with Angular" created successfully.

And if you’ve installed VS Code in your PATH variable, you should be able to issue

code .

to open the new project in VS Code.

NET Core SPA with Angular
Here is the root of my new project, opened in VS Code

proving that this can be automated using a simple shell script

After a quick restore, I’m able to get my Angualr2 SPA running in no time

NET Core SPA with Angular running
It’s a pretty basic SPA, but it shows off the basic principles using Angualr2

SPA Templates

The SPA templates all follow a common theme, they each have the same content, but use different client side technologies. .NET Core is used as the server side

obviously

in C#, whereas Bootstrap, Typescript and webpack are common client side technologies across all of the SPA templates. The only difference between the SPA templates is the choice of client side JS library:

  • Aurelia
  • Angular
  • Knockout
  • React
  • React and Redux
  • Vue

This helps to make the SPA templates extremely versatile.

I’ve actually been teaching myself a little Angular2 using the Angular template

Other Templates?

So you don’t just want to build SPAs? That’s cool.

As the weeks and months go on, and more developers start open sourcing their templates, we’ll start to see more and more of them show up. I would recommend starting with the list available on the ASP.NET Core Templating GitHub repo.

I’ve experimented with a few of these so far and found them all to be really easy to get up and running

which is the whole point of the templating engine, I guess

and actually build something with.

At the moment, there aren’t that many templates that have been indexed by Google.

my guess is that articles about the templating engine are getting in the way

But searching GitHub for “dotnet-template” returns 82 public repositories. Some of these will, undoubtedly, be VS 2015 templates. But around 80 repos within two months of a feature being released is pretty good, I’d say.

What do you think to the new templating engine? Will you be using it in your new .NET Core projects, or starting from scratch each time? Does the lack of VS Support (at the time of posting this article) bother you? Let me know in the comments and let’s keep the conversation going.

Related Posts

A .NET developer specialising in ASP.NET MVC websites and services, with a background in WinForms and Games Development.

When not programming using .NET, he is either learning about .NET Core (and usually building something cross platform with it), speaking Japanese to anyone who’ll listen, learning about languages, writing for his non-dev blog, or writing for a blog about video games (which he runs with his brother)