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
Aug 30, 2019
Interactive App Teaches Children How to Use 911

Skyline Technologies partnered with the Center for Childhood Safety (CCS) in Ashwaubenon to develop Kid's Practice 911 Dialer – a free app that teaches children ages 4-9 how to properly use 911. Through educational videos and simulated recordings based on actual 911 operator scripts...
Blog Article
Using Hooks to Reactify a Plain JavaScript Library: A Walkthrough
Andrew PetersenAndrew Petersen  |  
Aug 06, 2019
React Hooks make it really easy to wrap a vanilla JavaScript library with a React component so you can easily reuse it throughout your app and stay in "React Mode".In this walkthrough I'll be focusing on a single library, Shave.js, but the techniques and ideas should be applicable...
Blog Article
How to Create a Readable and Useful Bug Report
Blayne RoselleBlayne Roselle  |  
Jun 25, 2019
Creating a bug that is both readable and provides enough detail is a must-have skill for a Quality Assurance Analyst. Not only will it help when it comes time to retest, but it also provides credibility with your development team. In the content below, I will share the best practices for creating...
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...