Back to List

Creating and Installing Project Templates in .NET Core

Ben Buhr Ben Buhr  |  
Apr 30, 2019
 

In my previous blog article, we examined the .NET Core Command Line Interface (CLI). As part of that, we saw that templates in .NET Core can be very useful. Templates in .NET Core are very easy to create, and there already are a ton of very helpful ones available. They allow us to quickly get an app from 0 to 60. In this article, I'll go into more depth on this subject.
 

.NET Core Templating Engine

The .NET Core templating engine was enabled for broad use with .NET Core 2.0, and was created to make it easier for developers to create and maintain custom templates. One of the biggest headaches in new app creation is the initial app bootstrapping. The default templates provided with Visual Studio or the .NET Core CLI can help create a fairly useful barebones project. However, a developer will often have to make large changes to the code generated just to get things up to their own company's standard.

For example, your organization might require the use of a specific type of .NET library for authentication. Maybe the organization always uses a UI framework like Foundation instead of the default framework (Bootstrap) that gets installed with most .NET templates. What tends to happen is that a repository gets forked, or outright copied, and then the developer is responsible for refactoring namespaces and class names to match the new application.

All of this can be tedious, can lead to mistakes, and (possibly worse) can contribute to unnecessary early technical debt. There are other code scaffolding tools available on the web (Yeoman, for example). However, we will just focus on the templating engine native to the .NET Core CLI.
 

Installing New Templates

A great starting point when deciding if you need to create a template is to check the available third-party templates. This website has a large listing of existing templates that have been contributed by the .NET community. The website also lists the necessary CLI commands used to install and create a project with the respective templates.

For this example, we'll create a project using a template published by Microsoft for creating a new .NET Core web app that uses Blazor. Blazor is an experimental web framework that relies on WebAssembly to run the .NET runtime in your browser. This allows you to use C# code to perform operations in the client (as opposed to needing to use JavaScript). I won't get too in depth for this example, but you can check out more information about this at GitHub.

To install a new template into your .NET Core CLI, use the following command:

dotnet new --install "Your.Template.Here"

This command will search for any path that matches the inputted template and (if nothing is found) will then check NuGet for the matching template. This allows you to set up templates specific for your organization by hosting them in your organization's private NuGet feed. With that in mind, we can install the Blazor templates with this command:

dotnet new --install "Microsoft.AspNetCore.Blazor.Templates"

With the templates installed, we can then create a new project with:

dotnet new blazor -o TestBlazor

If you ever need to update the templates you have installed, you just need to rerun the dotnet new --install command again for the template you wish to update.

You can also uninstall the templates by running the following command:

dotnet new --uninstall "Your.Template.Name"
 

Creating Your Own Template

So what does it take to create one of these awesome templates? In the past, there was a ton of work involved to get a template to work and be recognized by Visual Studio. The .NET Core CLI simplifies all of this into a single file. The CLI uses this template configuration file as a map to know what to replace when it creates a project based off of the template.

Starting with any .NET Core project, we just need to add the following folder and file to the root level of the project:

.template.config\template.json

Below is a basic example of what a template.json file could look like:

{
    "author": "Your Name",
    "name": "Test Web Template",

    "identity": "MyTest.WebTemplate",
    "shortName": "testWeb",
    "classifications": [ "Web" ],
    "tags": {
        "language": "C#"
    },

    "sourceName": "TestProject"
}

Let’s break down what some of this stuff means. The first two properties (author and name) are fairly self-explanatory. They allow you to claim authorship and give a display-friendly name for the template.

The next four properties are more important to the classification of the template:

  • identity - The unique name that people will use typing the dotnet new --install command.
  • shortName - The keyword that users will use when creating a project using your template.
  • classifications - This allows you to specify what type of project (such as web) that your template belongs to.
  • tags - This area lets you classify additional metadata for your template.

The sourceName property is somewhat special. It allows you to specify the project name of the current template project. This then lets the CLI know to replace that value with the value provided with the —name option when creating a new project from the template. If no name option is provided, then the directory for the project will be used. This transformation will update the namespaces inside of the created project to match the expected new project.

To install the template, you simply need to run:

dotnet new --install "Path.To.Your.Template"

You can then utilize the template just like you would any other template. To share the template with more developers, you can host the template in a custom NuGet source.
 

Advanced Templates

While this basic template will allow you to make a pretty effective template, there are many advanced actions you can integrate into your project. The templating engine utilizes a few areas to help create more advanced templates. Perhaps you want to specify the name of a class that should be created as part of the initial generation. Maybe you want to generate a unique ID for the application upon its creation. You can even include preprocessor commands inside of your project to conditionally create blocks of code based on the passed in parameters. By using parameter generators, you can infuse your templates with additional code generation capabilities.

In addition to code generation, you can also specify actions to be executed after a project is created. This is very useful when you want a new project to automatically execute a dotnet restore. Additional information on both parameter generators and post actions can be found in the dotnet/templating wiki linked below.
 

Closing Thoughts

The templating engine introduced for .NET Core is very powerful and extensible. There’s also a large community of third party templates out there, beyond just the provided starter projects from Microsoft. In addition, you can create your own custom templates to help make new project bootstrapping much faster. With this ability also comes responsibility. If you are planning on creating custom templates for your company, make sure you have a plan for maintaining the templates. Out-of-date templates can be worse than no templates at all.
 

More Resources

 

 

.Net Programming

 

Love our Blogs?

Sign up to get notified of new Skyline posts.

 


Related Content


Spring 2019 Kentico User Group
Apr 17, 2019
Location: Waukesha County Technical College - Pewaukee Campus - 800 Main Street, Pewaukee, Wisconsin 53072 - Building: Q, Room: Q361
Blog Article
Azure Tips & Tricks: Application Insights Snapshot Debugger
Todd TaylorTodd Taylor  |  
May 21, 2019
A painful memory that is burned into my developer-brain is a production support issue for a .NET web API that I wrote years ago. I worked for a large retailer at the time, and the bug was preventing electronic pricing signs from displaying the most up-to-date price for hundreds of products at...
Blog Article
Thinking Outside the Application Development Box with Unity
Jeff WeberJeff Weber  |  
May 14, 2019
Do you or your company have an idea for an application that sits a little outside your comfort zone? Does your idea possibly require game-like graphics, Augmented Reality, Virtual Reality or similar technology? If so, Unity might be worth a look.   I’ve been using Unity in my spare...
Blog Article
How to Overcome the 5 Common Barriers to Manufacturing Innovation
Mitch WeckopMitch Weckop  |  
Apr 04, 2019
Manufacturing companies have an opportunity ahead of them – thanks in large part to information technology advances. These advances are increasing the rate of product innovation, improving cost and quality, enabling planned and predictive maintenance, and launching new business platforms...
Blog Article
Developing on a Raspberry Pi using Gulpjs
Eric DitterEric Ditter  |  
Jan 15, 2019
Developing on one machine and running on another is a tedious process, but sometimes you need to when a library has different features for ARM vs x64 (and then there are always the Windows vs Linux issues). This was the issue I had when I was working on a Raspberry Pi project using Python...