Edit

Tutorial: Create a project template

  • Article
  • 5 minutes to read

With .NET, you can create and deploy templates that generate projects, files, even resources. This tutorial is part two of a series that teaches you how to create, install, and uninstall, templates for use with the dotnet new command.

You can view the completed template in the .NET Samples GitHub repository.

Tip

The official .NET templates that are shipped with the .NET SDK can be found in the following repositories:

Templates Repository
Console, class library and common item templates dotnet/sdk
ASP.NET and Blazor templates dotnet/aspnetcore
ASP.NET Single Page Application templates dotnet/spa-templates
WPF templates dotnet/wpf
Windows Forms templates dotnet/winforms
Test templates dotnet/test-templates
MAUI templates dotnet/maui

You can view the templates that are installed on your machine by running the dotnet new list command.

In this part of the series you'll learn how to:

  • Create the resources of a project template
  • Create the template config folder and file
  • Install a template from a file path
  • Test an item template
  • Uninstall an item template

Prerequisites

  • Complete part 1 of this tutorial series.
  • Open a terminal and navigate to the working\templates folder.

Important

This article is written for .NET 7. However, it also applies to .NET 6 and previous versions, with one difference: The dotnet new syntax is different. The list, search, install, and uninstall subcommands should be --list, --search, --install, and --uninstall options, respectively.

For example, the dotnet new install command in .NET 7 becomes dotnet new --install in .NET 6. Use the dotnet new --help command to see a list of all options and subcommands.

Create a project template

Project templates produce ready-to-run projects that make it easy for users to start with a working set of code. .NET includes a few project templates such as a console application or a class library. In this example, you'll create a new console project that replaces the standard "Hello World" console output with one that runs asynchronously.

In your terminal, navigate to the working\templates folder and create a new subfolder named consoleasync. Enter the subfolder and run dotnet new console to generate the standard console application. You'll be editing the files produced by this template to create a new template.

working
└───templates
    └───consoleasync
            consoleasync.csproj
            Program.cs

Modify Program.cs

Open up the program.cs file. The standard console project doesn't asynchronously write to the console output, so let's add that. Change the code to the following and save the file:

await Console.Out.WriteAsync("Hello World with C#");

Build the project

Before you complete a project template, you should test it to make sure it compiles and runs correctly.

In your terminal, run the following command.

dotnet run

You get the following output.

Hello World with C#

You can delete the obj and bin folders created by using dotnet run. Deleting these files ensures your template only includes the files related to your template and not any files that result from a build action.

Now that you have the content of the template created, you need to create the template config at the root folder of the template.

Create the template config

Templates are recognized in .NET by a special folder and config file that exist at the root of your template. In this tutorial, your template folder is located at working\templates\consoleasync.

When you create a template, all files and folders in the template folder are included as part of the template except for the special config folder. This config folder is named .template.config.

First, create a new subfolder named .template.config, enter it. Then, create a new file named template.json. Your folder structure should look like this.

working
└───templates
    └───consoleasync
        └───.template.config
                template.json

Open the template.json with your favorite text editor and paste in the following json code and save it.

{
  "$schema": "http://json.schemastore.org/template",
  "author": "Me",
  "classifications": [ "Common", "Console" ],
  "identity": "ExampleTemplate.AsyncProject",
  "name": "Example templates: async project",
  "shortName": "consoleasync",
  "tags": {
    "language": "C#",
    "type": "project"
  }
}

This config file contains all of the settings for your template. You can see the basic settings such as name and shortName but also there's a tags/type value that's set to project. This designates your template as a project template. There's no restriction on the type of template you create. The item and project values are common names that .NET recommends so that users can easily filter the type of template they're searching for.

The classifications item represents the tags column you see when you run dotnet new and get a list of templates. Users can also search based on classification tags. Don't confuse the tags property in the json file with the classifications tags list. They're two different things unfortunately named similarly. The full schema for the template.json file is found at the JSON Schema Store. For more information about the template.json file, see the dotnet templating wiki.

Now that you have a valid .template.config/template.json file, your template is ready to be installed. Before you install the template, make sure that you delete any extra folders and files you don't want included in your template, like the bin or obj folders. In your terminal, navigate to the consoleasync folder and run dotnet new install .\ to install the template located at the current folder. If you're using a Linux or macOS operating system, use a forward slash: dotnet new install ./.

dotnet new install .\

This command outputs a list of the installed templates, which should include yours.

The following template packages will be installed:
   <root path>\working\templates\consoleasync

Success: <root path>\working\templates\consoleasync installed the following templates:
Templates                                         Short Name               Language          Tags
--------------------------------------------      -------------------      ------------      ----------------------
Example templates: async project                  consoleasync             [C#]              Common/Console

Test the project template

Now that you have a project template installed, test it.

  1. Navigate to the test folder

  2. Create a new console application with the following command which generates a working project you can easily test with the dotnet run command.

    dotnet new consoleasync

    You get the following output.

    The template "Example templates: async project" was created successfully.

  3. Run the project using the following command.

    dotnet run

    You get the following output.

    Hello World with C#

Congratulations! You created and deployed a project template with .NET. In preparation for the next part of this tutorial series, you must uninstall the template you created. Make sure to delete all files from the test folder too. This will get you back to a clean state ready for the next major section of this tutorial.

Uninstall the template

In your terminal, navigate to the consoleasync folder and run the following command to uninstall the template located in the current folder:

  • On Windows: dotnet new uninstall .\
  • On Linux or macOS: dotnet new uninstall ./

This command outputs a list of the templates that were uninstalled, which should include yours.

Success: <root path>\working\templates\consoleasync was uninstalled.

At any time, you can use dotnet new uninstall to see a list of installed template packages, including for each template package the command to uninstall it.

Next steps

In this tutorial, you created a project template. To learn how to package both the item and project templates into an easy-to-use file, continue this tutorial series.

Create a template package