How to create a project template

In this article, I will show you how to create a project template. This article assumes that you have BOTH Visual Studio and the Visual Studio SDK already installed.

Step by Step Video

Below is a 5 minute video that shows to create a new project template with SideWaffle. If you missed anything in the video you can find step-by-step instructions beneath the video.

https://www.youtube.com/watch?v=z33jOo75CH4

1. Let's Get Started

First, install SideWaffle if you haven't already.

2. Create a VSIX project

Now that we have SideWaffle installed in Visual Studio, we are going to create a new VSIX project by going to Extensibility->VSIX Project in the Add New Project window.

After creating your new project, the project's VSIX manifest file will open. We'll need to update the Author and Description fields as these will be what are presented to the developer in the Add New Project window. Save and close the file in order to continue.

3. Add your project to the solution

Now that we have our VSIX project, we want to add our project to the solution. In this article, I will be adding a project using the HTML5 Boiler Plate template.

4. Disable the project from building via Configuration Manager

Now before we continue any further we want to keep Visual Studio from building any of the projects that we just added. As shown in the image below select Configuration Manager from the drop down menu at the top of the window

In the Build column uncheck any projects that you added in the last step. Repeat this process for both the Debug and Release configurations.

5. Create a new Template Reference

Right click on your VSIX project and select Add->Add Template Reference (SideWaffle project)

In the dialog that appears select the project you added in Step 3

By adding the Template Reference item template, you just added a three items to your solution. The first thing that was added was a reference to your source project from the VSIX project. Second, the TemplateBuilder NuGet package was added to the VSIX project. Last, it added the SideWaffle Project Template Files item template to your source project, which includes two files.

• _preprocess.xml - This file is used to perform file replacements during the template packing process and to override the path where the template is shown in the New Project/Item dialog; This file Must be in the root folder, and must define the Path attribute on TemplateInfo
• _Definitions\_project.vstemplate.xml - This file contains metadata regarding your template. For example the name, description, logo, etc are all found in this file. This file also has a pointer to the project file that you are creating a template out of.

6. Updating the _preprocess.xml file

You'll need to update _preprocess.xml so that it replaces your namespace values with either $safeprojectname$, $guid1$, or $guid5$. If the file does not contain at least one of these values then you may not be able to debug/run your application. This process should be done automatically when the template is created; however, it is good practice to verify these values before continuing as this defines where the template should be shown in the New Project dialog. It has been highly recommended by the development team that you do not change the code in your source project to use these values and instead perform the replacements using the _preprocess.xml file.

The XML below is an example of a very common and simple replacement of the _preprocess.xml file.

<?xml version="1.0" encoding="utf-8" ?>
<Preprocess>
  <TemplateInfo Path="CSharp\Web\Custom\Subcategory"/>
  <Replacements Include="*.*" Exclude="*.vstemplate;*.csproj*.jpg;*.png;*.ico;_preprocess.xml">
    <add key="_SampleProjRef" value="$safeprojectname$"/>
  </Replacements>
</Preprocess>

Below is another example of the _preprocess.xml file using a more complex replacement.

<?xml version="1.0" encoding="utf-8" ?>
<Preprocess>
  <!--
  You can specify the path where this should show up in the
  Add New Project / Add New Item dialog by setting the value below
  -->
  <TemplateInfo Path="CSharp\Web\SideWaffle"/>
  <Replacements Include="*.*" Exclude="*.vstemplate;*.fsproj;*.vbproj;*.jpg;*.png;*.ico;_preprocess.xml;_project.vstemplate.xml">
    <add key="Nancy.CSharp.AspNetHost" value="$safeprojectname$"/>
    <!--targetFramework="4.0"-->
    <add key="targetFramework=&quot;4.0&quot;" value="targetFramework=&quot;$targetframeworkversion$&quot;"/>
    <!--<TargetFrameworkVersion>v4.0</TargetFrameworkVersion>-->
    <add key="&lt;TargetFrameworkVersion&gt;v4.0&lt;/TargetFrameworkVersion&gt;" 
         value="&lt;TargetFrameworkVersion&gt;v$targetframeworkversion$&lt;/TargetFrameworkVersion&gt;"/>
  </Replacements>
</Preprocess>

While we are working in this file we are going to do one more thing. In the _preprocess.xml file you will see a Replacements element as shown in the line of code below.

<Replacements Include="*.*" Exclude="*.vstemplate;*.csproj;*.fsproj;*.vbproj;*.jpg;*.png;*.ico;_preprocess.xml;_project.vstemplate.xml">

We are going to remove the value corresponding to your project file from the Exclude attribute. So if your project uses C# you will remove *.csproj; and if your project uses Visual Basic then you will remove *.vbproj; from this element. The line of code below is an example of what your line should look like if you added a C# ASP.NET application.

<Replacements Include="*.*" Exclude="*.vstemplate;*.fsproj;*.vbproj;*.jpg;*.png;*.ico;_preprocess.xml;_project.vstemplate.xml">

7. Updating the _Definitions_project.vstemplate.xml file

You'll need to update the _Definitions\_project.vstemplate.xml file and ensure that the correct content for the File attribute on the Project element was generated. It is important that you ensure this value is correct as there have been cases where this has been found to generate an incorrect value. Below is an example of a complete file.

Note: Make sure to set the Path attribute on TemplateInfo here otherwise the template will never be shown

<VSTemplate Version="3.0.0" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005" Type="Project">
  <TemplateData>
    <Name>Sample proj from ref</Name>
    <Description>Sample proj from ref</Description>
    <DefaultName>MyProjApp</DefaultName>
    
    <ProjectType>CSharp</ProjectType>
    <ProjectSubType></ProjectSubType>
    <SortOrder>1000</SortOrder>
    <CreateNewFolder>true</CreateNewFolder>    
    <ProvideDefaultName>true</ProvideDefaultName>
    <LocationField>Enabled</LocationField>
    <EnableLocationBrowseButton>true</EnableLocationBrowseButton>
    <Icon>icon.png</Icon>
    
    <!-- Indicates how many parent folders this item template should appear in -->
    <NumberOfParentCategoriesToRollUp>1</NumberOfParentCategoriesToRollUp>
  </TemplateData>
  <TemplateContent>
    <Project TargetFileName="$projectname$.csproj" File="_SampleProjRef.csproj" ReplaceParameters="true">      
    </Project>
  </TemplateContent>
</VSTemplate>

After you have made these changes you can party on your project and then when you build the TemplatePack project the project template will be included automatically.

You can find a sample of this in the SideWaffle repo as the _SampleProjRef project.

8. Updating the SideWaffle Release Notes (Optional)

Please note that this step is only required if you add/remove/edit a template and/or snippet.

In the root directory of the SideWaffle project you will find release-notes.html. This is where we post the changes to the SideWaffle project since the latest release. You will need to add a corresponding entry to this file before you send a pull request.

Notes from the development team

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.