How to Create A Project Template
In this article, I will show you how to create a new project template with SideWaffle. This article assumes that you have the following installed on your machine:
- Visual Studio 2017 (15.3 or later) with the Visual Studio Extensibility component
- SideWaffle Creator 2017.
Below is a ten minute video that showing the steps we will be covering in this article. If you missed anything in the video you can find step-by-step instructions below.
To get started, we must first create the project that we want to turn into a template. For this tutorial, I'm going to use a Console Application and will call it HelloGitHub.
Once you've created your project it should open in Visual Studio automatically. Right click on the project and select "Create Template".
This will open a dialog prompting you for metadata about your template. Below is some basic information about each of the metadata fields:
- Author - Enter your name or your company's name
- Short name - This is the name your users will use to refer to your template.
- Identity - how you identify the template (i.e. Demo.HelloGitHub.CSharp)
- Group identity - it is important that this value be a substring of Identity (i.e. Demo.HelloGitHub)
- Default project name - default name of the project that's created when your template is used (i.e. HelloGitHub)
- Display name - name of the template that's shown in the New Project dialog
Now, click OK to continue on to the new step.
This will create a .template.config folder with a couple of files in it. (template.json and template.vstemplate). You may have to click the button in your Solution Explorer to Show All Files, because while these 2 files have been created they have not been included in the project.
Open the template.vstemplate file and look at the CustomParameter with the name SideWaffleNewProjNode. The value for this CustomParameter should be updated to match where you expect the template to be in the New Project dialog. For the purposes of this demo I'm going to put my template under CSharp\Console. The line looks like this now:
<CustomParameter Name = "SideWaffleNewProjNode" Value="CSharp\Console"/>
Now, save and close the file. You can also close the template.json and Program.cs files if you have them open.
Now that we have our project set up, we need to create a container that we can put our template into so Visual Studio users can consume it. Usually, you will do that by adding a VSIX project to your solution. To add the VSIX project, right click on your solution, go to Add, and select New Project...
A dialog will open with the title Add New Project. In the dialog, click on the Extensibility node on the left side. On the right side of the dialog, you should now see a project called "Template Pack Project Template (SideWaffle)". This template was added when you installed SideWaffle. Select this template, rename the project at the bottom of the dialog. I'm going to name mine DemoTemplatePack, then hit the OK button.
Now that we have added the VSIX project to our solution, we need to set it as the start up project. To do that right click on the DemoTemplatePack project, and select "Set as StartUp Project" from the list.
Doing this will allow us to use the Ctrl + F5 shortcut so we can test our new template.
In the last step I mentioned that we can test our template using the Ctrl + F5 shortcut. Go ahead and press those keys to launch the Visual Studio 2017 Experiemental Instance.
Once the experimental instance has finished loading, go to the File menu and select the Project option under the New submenu. This will open the New Project dialog.
If you've been following these instructions exaclty you should now see your template under the Visual C#\Console nodes. As you can see the template name that shows up on the right hand side pulled from the Display name we entered in Step 2. The project name at the bottom of the dialog was also pulled from the data we entered in Step 2. In this case in came from the value we entered for Default project name.
Now let us name our project, you can accept the defaults if you like. Mine defaulted to HelloGitHub1, I am going to use that name and click the OK button.
If you did everything correctly thus far you project should be created. You should see your custom project and any files it contained as part of your new project.
The last thing we want to do is build the project and make sure it runs correctly. If it does then you are all set. You've created your first project template with SideWaffle Creator 2017.
If you have any trouble following the instructions found in this article or are unsure about something in your project please create an issue and we will be happy to assist you with your project.
- How to Create Templates
- Template Engine repository
- Template Engine samples repository
- Template Engine Wiki
-
SideWaffle Creator 2017 code
- Note: This may move into the main SideWaffle repository