Create a .NET Core Project Template

Want to learn how you can make your very own custom.Net template. Turns out it’s actually very simple, so learn more on this episode of Visual Studio Toolbox. [MUSIC]. >> Hey everyone, welcome back to another episode of Visual Studio Toolbox. I’m your host, Leslie Richardson, and today I’m joined once again by a senior PM Sayed Hashimi. Welcome back. >> How is it going? >> It’s going all right, it’s a very sunny day in Florida right now. Coming to you from my childhood room. All is well. >> Yeah. I’m around Florida as well. Just a little bit north of you, I think. >> Yeah, sweet. Last time we talked more about.

Net Core templates and specifically how 00:47 - you can use custom templates that people in the.Net community created. What about if you want to create.Net template? How do you do it? >> That is exactly what we’re going to be covering today here. Yes, so what we’re going to do is, basically we are going to talk about how to create your own project templates, and then we can use those from either.Net New. Also now we have got the availability to use the same exact project templates, not only in.Net New, but also in Visual Studio 2019 and Visual Studio for Mac.

01:26 - I believe even JetBrains writer has a functionality to show the templates that have been created and installed with.Net New. Yeah, we’ll basically talk about, you create one template and then just expose that everywhere. In this particular video we’re going to show you how to create a basic template, and then how to get that working with.Net New, and then in future videos, we’ll also show how to fine tune those for Visual Studio and how to improve your overall templates as well. That’s the general idea here. >> Great. This sounds like it would be incredibly useful if there is just a specific template thing that you personally need, whether it’s for a particular project or whatever team you’re working on, but the S doesn’t have by default. >> Yeah, exactly. There’s a lot of scenarios here.

02:19 - One would be, let’s say you’ve got a big enterprise and you’ve got maybe like a team of architects and they’re the ones out there that will be creating these project templates and putting that up unto maybe like a private NuGet repository or some type of private NuGet server that they’ve got there, so that’s one scenario. Another scenario would be, let’s say if you own like an open-source utility there, you might want to go through and create some inputs for your open source projects, so that’s another one there. For example, there’s lots of popular open-source projects that’s available. One would be.Net Boxed, there’s also identity server templates, so on and so forth. There’s just a lot of different scenarios for creating custom templates.

03:16 - It’s actually a lot easier than what it used to be in the past. It used to be pretty complicated to create and maintain these templates. But now we’ve significantly cut that down to make it a lot simpler to go ahead and get started there. That’s the idea. >> Awesome. I do like simplicity. Shall we check it out? >> Yeah, definitely. >> Cool. >> Before we get started, what we’re going to do is, I’ve got this open source repository here on GitHub.

03:47 - You can get to it by going to this link here, https://aka.ms/netcore-templates. We’re essentially going to recreate what we have inside this repository here so users can follow along there. Then in the Read Me, all the information that you need for creating templates and fine tuning them for Visual Studio, everything that you need is inside this Read Me here. For example, here’s a couple of links for how to create your own templates and we’ll be covering that content today. We also have our own ASP.Net Core templates or open source and GitHub as well, so if anybody wants to go and take a look at how the ASP.

Net Core project templates have been created, 04:31 - they can always go through and take a look at these particular examples here for that as well. That’s just more information. Yeah, exactly. We’re going to go ahead and get started on this one. Actually, let me explain something here real quick. The way that we’re going to structure our code is essentially going to follow what we have here. In this repository, I’ve got a Source Folder, so I’ll create a Source Folder, and then there’s also a Content Folder.

05:07 - Inside the Content Folder is actually where these projects exist. Each folder here is a project that has become a template. I’m just going to go ahead and mimic this particular structure here. I’ve got my demo folder here inside my source, so I’m going to add a content. That’s great. Now what we want to do is let’s go ahead and add the solution file to this as well. I’m going to go in and open up a terminal prompt here, and then we’ll go and change directories. Now, last video we showed you how to use.Net New. One thing that I didn’t show was.Net New, you can also create certain types of files here, and the Solution file is one of those. I’m going to go ahead and do that. I’m going to create my solution. I’ll say.Net New solution -n for name will be demo. We’re going to get that created. That should go in and create my solution file here in the source directory. Then at this point, what I’ll do is go in and create a new project and put that into content, and then we’ll go from there. But I’ll just go ahead and do that here with.Net New because I’m already in here. I can say.

Net New, console and let’s say 06:32 - MyConsole01. That should be right. That should create another folder called MyConsole01. Then everything is here. Now what we’ll do is go ahead and fire up the Solution file in Visual Studio and add that project to it. I have got my program.cs. I’m just going to make a small modification to this. I’m going to take the project name, which was my console. I’ll say Hello from MyConsole01.

07:05 - Now let me just go ahead and run this to verify that it builds and runs. Hello from MyConsole, so this builds and runs. Now what we’re going do now is, go back and add a couple additional files that we need here to create a template out of this. The files that we’ll need is the template.json file, and that’s going to go into a folder name.template.config. It’s going to create that folder here. I’m going to go into the project folder and I’ll say New. >> Just going to create a new JSON file here for the template.json. Go back to Visual Studio. I’m going to create a Solution Folder here, so it can interact with these files. But this is not necessarily needed here. You can just directly open the files if you like. Now I’ve got my template.json file loaded up here. Whenever you’re editing one of these JSON files, whether it’s the template.

json 08:19 - file or one of the other JSON files that we work with, you always want to start by putting the schema declaration inside the file. This is going to do a number of things. One thing it’s going to do is it’s provide completions, for example, this completions here. The other thing it does is within the completions, there’s an indication of required properties here, and those are the ones that have been bolded here. We can see there’s a list of bolded items at the top. These are all required. We have to set all those. We’re also going to set a couple of different ones.

08:53 - Then in addition to that, the schema will also give validation. Let’s say if you did introduce an error in this file, you should see the error down here in the error list here. Let’s go ahead and run through these here. Author, is me, classifications, for this, it’s a console app, so I will put console here. There’s more information on the Read Me about what are the classifications and what are the different values that can be used.

09:25 - But essentially, this is going to appear in Visual Studio as a filter here, but we’ll get to that. Identity should be a unique name for this. I’m just going to come up with some long name here that’s never been used, name is the the full name. >> What happens if the name has been used? Will VS flag you or something about it? >> Yeah. That’s a great question. Let’s say if identity has been used and you reuse that same identity, what might end up happening is you might get some unexpected behavior, it might not necessarily be clear if you’re using the first one that you had installed or the second one that you had installed.

10:16 - It’s always good for identity to give a longer name that you’re going to be pretty sure is unique. Usually I would put some identifier in here as well like I’ll always put my alias here. Yeah, I would always try to make this unique because you could get unexpected results if you do reuse some identity value that’s already been there. >> Got you. >> We’ll going to add a short name. The short name is the value that users will use on the console. I’ll say Sayedcon is fine for that one. Tags, so tags are things like the type here.

10:55 - Is it a project template or it’s an item template? I’m going to can pick project for this one. Currently we support item and project, but we are considering to support solution there as well. Then language is, what’s the main language that this project is using here? Like C#, VB, F#. But you’re not limited to any particular languages when you create these types of templates here. We’ve gone ahead and filled in all the required parameters here.

11:29 - There’s going to be an additional parameter that you’re always going to want to specify, and that’s source name. Let me copy this. Let me explain how source name works here. With most template like processors or template engines, what happens is you normally have to go into your source code and actually modify or tokenize things. For example, when I create a project template out of this, odds are I want users to be able to specify the value for the namespace. Normally, that’s the name of the project. So with most template pre-processors we have to do this. You have to go into your code and tokenize these.

12:16 - For example, with the older existing VS template approach, you’d have to go through your code and change all your namespace declarations to be something like $RootNamespace$. I forget if it’s a dollar sign or a percent sign or something, but the point is, you have to go and modify your code in such a way that it no longer builds. >> Right. I’m sure that’s fine. >> Yeah, this really creates just a huge maintenance nightmare because if you’ve got your project here, that’s the source, then you build and run that one, and then you have this tokenized version of your project, so you’re constantly maintaining two different things and it’s not easy. I’ve even heard of cases where there was an open-source template and they had C# support and a contributor contributed VB support, but then it was so hard to maintain the VB template that they just got rid of it. So those are the types of things that we’re trying to avoid with the template engine.

13:15 - With template engine, what we do is we turn it on top of its head here. Instead of having users go through and tokenize all of their code, what we do is we provide abilities for users to indicate what replacements should be happening. All that stuff happens in the template.json, and source name is a very special one. Source name is the, string MyConsole01. That was the name of the project that I had given when I created this. Now what happens is when a user will use this template either with.

Net New or with Visual Studio, 13:52 - whatever project name was given, will replace MyConsole01. That will happen across all the template files. Wherever MyConsole01 shows up, it’ll be replaced with the name of the project. This is not only in the contents of the files, but also for the file names themselves. Now, we’ve got everything that we need for this template.json. Now, we should be able to go in and run. We should go ahead and be able to install this template and then use that. I’m putting clear out of this. Inside the GitHub repository, in my GitHub repository in the Read Me, there’s some PowerShell here that might be helpful for users. There’s a reset templates function here that I’m going to be using here. Users can copy and paste this into their PowerShell prompt or in their PowerShell profile. Let me go ahead and call that. So if you’re developing templates locally, if you’re a template developer, you’re going to want to reset the templates pretty often, essentially while you’re going through this process here. I’ve reset.

Net New to everything and 15:03 - only the default things are available right now. I’ll put in and install that. I’ll say “dotnet new – install”, and then point it to a folder, and then it will search for the templates underneath that. Now here we are. Now we see we’ve got sayedha.console.01 with the short name of sayedcon. Now, I can do dotnet new sayedcon -o and we could say ConsoleDemo, so that would be the name of the project, ConsoleDemo. Let’s go into that then. ConsoleDemo. Just look. Let’s go ahead and run this with dotnet run, and see what the output is. Hello from ConsoleDemo, exclamation point. >> Awesome. >> Go ahead. >> That was a good sign. >> Yeah, exactly.

16:04 - We didn’t really have to do much for that replacement, and I was to open up the program.cs here, we can see that that replacement did take place not only in the namespace, but also in the code itself. So wherever it was MyConsole01, it’s now ConsoleDemo. Then also, we notice that the project was named ConsoleDemo.csproj as well. That’s what we expected as well. Now, what we want to do is, we’ve created a template, but this template is here locally on my machine.

16:38 - What we want to do is we want to take this template and share it with friends and colleagues. The way to do that is to actually take this template, put it inside of a NuGet Package, and then you can upload that to NuGet.org or to any NuGet server that you’re working with there. Let’s go back to the samples here and I’ll show you where is the new spec and we’re going to just copy the file that’s there. Let me copy the contents here, let me go back to Windows Explorer.

17:12 - I will create this file, so we’ll put it in the source folder here, so I’ll say New. >> Let’s get this loaded up in Visual Studio as well. I’m just going to drag it into my template files here. Now I get my new spec here. Let me go ahead and paste in the contents, we’ll change some of this, the filename itself. There we go. This is just a very basic new spec file. The new spec just describes the NuGet package here. There’s a lots of docs for this as well.

18:00 - But let me go through and customize something; the demo and the pack. Whenever you are creating a NuGet package that contains templates, you always want to indicate that this package contains a template and this will show up in the search on NuGet.org that we showed in a previous video. Then for the contents of the NuGet package, it should pick up all the files in the content folder excluding the bin and obj folders. Just make sure that’s correct. Yes, so that’s correct and that’s what I’m expecting. I’m going to reset my templates again. I just list them just to double check that there’s no sayed console template here. So it’s not there.

18:53 - Now what we want to do is we want to go ahead and pack this, so let me see where am I at. Now to do this, we’re going to use NuGet.xc here, so I’ve got that on my path. For users, you can download this from NuGet.org, and the command that we’re going to send here is pack. We’re going to give the new spec file and specify output directory. >> Can you do all this within Visual Studio itself or do you have to do it in the console window? >> Yeah, right. So, that’s a great question here. So, yes.

19:34 - For this particular step of creating a package from a new spec file, there’s no way that I know of to achieve this directly in Visual Studio. I think it’s easier to just do these from the command line. But after we’ve created these artifacts, would be possible for you to automate this with Visual Studio as well by creating maybe some custom MSBuild files there. But yeah, there’s no direct support built in for this exact scenario in Visual Studio itself. >> Got you. >> I’m going to create a package here. In my template samples repository, I do have all this kind of automated in a PS1 file, in case anybody’s interested in that. >> Yeah. That repo looked extremely helpful. So yeah, so definitely go look into that. >> Yeah. Definitely, a lot of good stuff there.

20:27 - Now we can see that the NuGet package has been created here, so what I want to do now is go ahead and install this from the NuGet package itself. That same dotnet new install command. This time we’re just going to pass it the NuGet package instead of the folder path. Now, we can see I’ve got my sayedha.console.01 project template here. We can just go ahead and try that again one more time. What I’ll do is I’ll just do it like this; dotnet new and then the output will go in to d demo out, and then we’ll say TestConsole. Let’s just go there and double check that for confine onetime real quick from the NuGet package. There we go.

Now what we can do is we can take 21:37 - this and then just publish it directly to NuGet.org at this point. Let’s say you’ve customize your template, you’re ready to go, and you’re ready to publish the sky out. What you’ll do is you just go to NuGet.org, sign-in obviously, then go to Upload. At this point what I can do is I can take my NuGet package that was just created, drag it here. There’s going to be some verification. I’ll give you a little preview of it, and then you can go ahead and publish this. I’m not going to close this one because there’s nothing here.

22:17 - But after that was done, then what your users can do is, then I can say “dotnet new – install. Just take this one for an example. This one, the ID would be this sayed.demo.con.01, right? >> Right. >> So that’s what users would view to create a NuGet, to create a project template. Use it from.Net New locally to verify that it works. Wrap it inside of a NuGet package. Publish it to NuGet.org. You can publish it to any NuGet server there, to MyGet or any server that you’ve got, and then your friends and colleagues can then go ahead and start installing and partying on these templates. >> That’s really cool. Honestly, I expected you’d have to jump through more hoops just to publish a package like that. It’s pretty straightforward. >> That’s right. What we’ve done is, here we did just the very basics here.

23:19 - There’s still a lot more that we can do to improve the experience, not only for.Net New, but also for Visual Studio. You’re right, it’s very easy and fast to get started with these templates and also to publish them. But to make a great template will require a little bit of additional effort. Those are kind of things that we’ll be covering in our future videos as well. >> Great. Speaking of which, what are we going to talk about next? >> Yes.

I think what we’re going to do next is we’re going to 23:51 - take this template that we’ve created here and add some parameters to it. If I were to go back to my GitHub and take a look at this console project here, we can see in the template.json, there are some parameters here. These parameters are things that users can specify, either on the command line and also in Visual Studios. We will talk about how to create parameters in the template, and there’s also a template analyzer tool that I’ve created to show how to install and run that tool. Then we’ll discuss how to address the warnings that are coming out of it for this template that we have, like it goes to show you some things, we are missing some things here.

24:38 - For example, we’re missing the framework 1 and we’ll show how to add that. Then there’ll be some other customizations and modifications that we make to make this experience even better. >> Sounds good. I can’t wait to see how we continue to flash out that template. >> Oh, yeah. >> So until next time, happy coding. >> Thank you. [MUSIC] .