{"id":10005,"date":"2017-04-02T09:47:17","date_gmt":"2017-04-02T16:47:17","guid":{"rendered":"https:\/\/blogs.msdn.microsoft.com\/dotnet\/?p=10005"},"modified":"2023-07-12T10:18:47","modified_gmt":"2023-07-12T17:18:47","slug":"how-to-create-your-own-templates-for-dotnet-new","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/dotnet\/how-to-create-your-own-templates-for-dotnet-new\/","title":{"rendered":"How to create your own templates for dotnet new"},"content":{"rendered":"

You can now create your own templates for dotnet new<\/code>. Creating and installing your own templates is an experimental feature at this point, but one that we are seeing significant interest in and that deserves more of your feedback before we enable it for broad use with .NET Core 2.0. The version of dotnet new<\/code> shipped with the .NET Core 1.0 SDK has a new command line parameter install<\/code>. This is an undocumented feature, and is not currently included in the help output.<\/p>\n

You can try the new template experience if you have the new SDK or Visual Studio 2017 installed. If you didn’t you can right now.<\/p>\n

The goal of this post is to connect with developers who are interested in creating templates. If you maintain a library or framework project on GitHub, then you are a great candidate to be a template author. There are lots of other cases too, where creating templates makes sense. If you can create a sample, you can create a template. It’s not hard at all.<\/p>\n

In the last update for .NET Core, we have updated dotnet new<\/code>.\nThis new version of dotnet new<\/code> is now built on top of the new Template Engine<\/a>, which\nis a library that we are developing. To learn more about how to use dotnet new<\/code> see the docs<\/a>.\nIn this article, we’ll show how to create some custom templates and then use them from dotnet new<\/code>.<\/p>\n

Over the past several years we have seen a lot of interest in creating custom templates. We also heard that it’s too\ndifficult to create and maintain templates with the existing tools. Because of that we wanted to make it easy to create, maintain and share templates. Let’s dive into the demos, and see how to create some templates.\nEverything that we cover here is in a GitHub repository at https:\/\/github.com\/sayedihashimi\/dotnet-new-samples.<\/p>\n

I have a web project which I’d like to create a template out of. The template project can be found at Sayedha.StarterWeb<\/a>. This is a modified version of\nthe mvc template which is availables\nout of the box. Before you create a template out of this, let’s run the sample to see what was created. After running dotnet restore<\/code>, and dotnet run<\/code>, you can view the app at http:\/\/localhost:5000<\/code> (or if running in Visual Studio it will launch automatically when you run the app).\nTHe following screenshot of this app running on my machine (I’m creating these samples on a Mac, but you can use any platform).<\/p>\n

\"app<\/p>\n

The app will look pretty familiar if you’ve created an app with this template in Visual Studio. There are also some strings that need to be replaced when\nyou create a template out of this. For example the namespace is set to SayedHa.StarterWeb<\/code>. This should be updated to match the project name created. Now let’s create a template out of this and then you can start adding the replacements\nthat are needed.<\/p>\n

How to create a basic template<\/h2>\n

To create a template from an existing project you will need to add a new file .template.config\\template.json<\/code>. You should place the .template.config<\/code> folder at the root\nof the files which should become the template. For example, in this case I’m going to add the .template.config<\/code> directory in the Sayedha.StarterWeb<\/code>\nfolder. This is the same folder that contains the .csproj<\/code> project file. Let’s take a look at the content of the template.json<\/code> file.<\/p>\n

{\r\n  \"author\": \"Sayed Ibrahim Hashimi\",\r\n  \"classifications\": [ \"Web\" ], \r\n  \"name\": \"Sayed Starter Web\",\r\n  \"identity\": \"Sayedha.StarterWeb\",        \/\/ Unique name for this template\r\n  \"shortName\": \"sayedweb\",                 \/\/ Short name that can be used on the cli\r\n  \"tags\": {\r\n    \"language\": \"C#\"                       \/\/ Specify that this template is in C#.\r\n  },\r\n  \"sourceName\": \"Sayedha.StarterWeb\",      \/\/ Will replace the string 'Sayedha.StarterWeb' with the value provided via -n.\r\n  \"preferNameDirectory\" : \"true\"\r\n}<\/code><\/pre>\n
The contents of template.json<\/code> shown above are all pretty straight forward. The sourceName<\/code> field is an optional field that you should pay more attention to. I’ll tell you why.”\nWhen a user invokes dotnet new<\/code> and specifies a new project name, by using --name<\/code>, the project is created, and the string value for sourceName<\/code>\nwill be replaced with the value provided for --name<\/code>. In the template.json<\/code> example above, sourceName<\/code> is set to Sayedha.StarterWeb<\/code>. This enables all instances of that string to be re-written by the user-provided value specified at the command line, with --name<\/code>.\nThis string is also used to subsitute the namespace name in the .cs<\/code> file for the project.\nWhen a new project is created with the template, these values will be updated. We will discuss preferNameDirectory<\/code> later.\nLet’s try out our template now and see that in action.<\/p>\n
Now that we have created the template, it’s time to test it out. The first thing to do\nis to install the template. To do that, execute the command dotnet new --install <PATH><\/code> where <PATH><\/code> is the path to the folder containing\n.template.config<\/code>. When that command is executed it will discover any template files under that path and then populate the\nlist of available templates. The output of running that command on my machine is below. In the output you can see\nthat the sayedweb<\/code> template appears.<\/p>\n
$ dotnet new install \/Users\/sayedhashimi\/Documents\/mycode\/dotnet-new-samples\/01-basic-template\/SayedHa.StarterWeb\r\nTemplates                                 Short Name      Language      Tags\r\n--------------------------------------------------------------------------------------\r\nConsole Application                       console         [C#], F#      Common\/Console\r\nClass library                             classlib        [C#], F#      Common\/Library\r\nUnit Test Project                         mstest          [C#], F#      Test\/MSTest\r\nxUnit Test Project                        xunit           [C#], F#      Test\/xUnit\r\nSayed Starter Web                         sayedweb        [C#]          Web\r\nEmpty ASP.NET Core Web Application        web             [C#]          Web\/Empty\r\nMVC ASP.NET Core Web Application          mvc             [C#], F#      Web\/MVC\r\nWeb API ASP.NET Core Web Application      webapi          [C#]          Web\/WebAPI\r\nSolution File                             sln                           Solution\r\n\r\nExamples:\r\n    dotnet new mvc --auth None --framework netcoreapp1.0\r\n    dotnet new sln\r\n    dotnet new --help<\/code><\/pre>\n
Here you can see that the new template is included in the template list as expected.\nBefore moving on to create a new project using this template, there are a few important things to mention about this release.\nAfter running install, to reset your templates back to the default list you can run the command dotnet new --debug:reinit<\/code>. We don’t\ncurrently have support for uninstall<\/code>, but we are working on that. Now let’s move on to using this template.<\/p>\n
To create a new project you can run the following command.<\/p>\n
$ dotnet new sayedweb -n Contoso.Web -o Contoso.Web\r\nContent generation time: 150.1564 ms\r\nThe template \"Sayed Starter Web\" created successfully.<\/code><\/pre>\n
After executing this command, the project was created in a new folder named Contoso.Web<\/code>. In addition, all the namespace elements in the .cs files\nhave been updated to be namespace Contoso.Web<\/code> instead of namespace SayedHa.StarterWeb<\/code>. If you recall from the previous screenshot there were\ntwo things that needed to be updated in the app: the title and the copyright. Let’s see how you can add these parameters to the template.<\/p>\n
How to create a template with replaceable parameters<\/h2>\n
Now that you have created a basic template, let’s see how you can customize this a bit by adding parameters. There are two elements in the home page that\nshould be updated when the template is used.<\/p>\n