Creating a Project Template

Objective

Let’s create a simple Project Template. We’ll walk through each step of the process to create a project template for Visual Studio.

Prerequisites

Before we build any Visual Studio templates we should have Visual Studio installed. If you do not have Visual Studio 2015 or greater you can download it here. The next thing you will need to install is the Visual Studio SDK or "Visual Studio Extensibility Tools". You can find instructions on installing the Visual Studio SDK here. If you are installing Visual Studio for the first time, there will be an option to add the Visual Studio Extensibility Tools in the installer under the "Common Tools" node. I suggest you do that while installing Visual Studio. Once you have both Visual Studio installed and the Visual Studio SDK, then we can proceed to creating our project template.

Adding the Visual Studio Projects

Now that we have the Visual Studio SDK installed. Let’s create a new C# Project Template. We do this by clicking on the File menu followed by the New context menu Item followed by the Project context menu Item. Alternatively we can hold down ALT and then type F N P. Or in shortcut notation ALT + F,N,P. Now we see the new project dialog.

In this dialog we will navigate to the Installed section then In the Templates node we’ll expand Visual C# followed by Extensibility. Now we are presented with a few options. We will select the "C# Project Template" for the first project. In the Name field we’ll enter "FancyProjectTemplate". The solution name will be the same. Then click the "OK" button.

The Template starts you off with the files you would need to create a C# project template. Let’s examine those first.

As you can see there are a few files that you would expect in any new project a Class1.cs and a AssemblyInfo.cs. There are also a few files that you may not have seen before an .ico file. This is an icon file that will be the icon for your project template. Also a .vstemplate file, we’ll come right back to that in a minute. Last is the ProjectTemplate.csproj file.

The .vstemplate File

Lets take a look at the .vstemplate file first.

<?xml version="1.0" encoding="utf-8"?>
<VSTemplate Version="3.0.0" Type="Project" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005" xmlns:sdk="http://schemas.microsoft.com/developer/vstemplate-sdkextension/2010">
  <TemplateData>
    <Name>FancyFSharpProjectTemplate</Name>
    <Description>FancyProjectTemplate</Description>
    <Icon>FancyProjectTemplate.ico</Icon>
    <ProjectType>CSharp</ProjectType>
    <RequiredFrameworkVersion>2.0</RequiredFrameworkVersion>
    <SortOrder>1000</SortOrder>
    <TemplateID>15b1144b-eb56-4f46-9d4a-2782dc1125aa</TemplateID>
    <CreateNewFolder>true</CreateNewFolder>
    <DefaultName>FancyProjectTemplate</DefaultName>
    <ProvideDefaultName>true</ProvideDefaultName>
  </TemplateData>
  <TemplateContent>
    <Project File="ProjectTemplate.csproj" ReplaceParameters="true">
      <ProjectItem ReplaceParameters="true" TargetFileName="Properties\AssemblyInfo.cs">AssemblyInfo.cs</ProjectItem>
      <ProjectItem ReplaceParameters="true" OpenInEditor="true">Class1.cs</ProjectItem>
    </Project>
  </TemplateContent>
</VSTemplate>

This is an xml file that describes the ProjectTemplate that will be created by compiling this Project.

It has several components. We’ll only look at the most useful ones. If you want to further examine the entire schema you can find more information here.

The element encapsulates the metadata about the project template. By populating the Name, Description and icon fields you can determine what is displayed in Visual Studio’s New Project Dialog when creating a new project from this template. The DefaultName element is what will show up in the Name text box when creating a new project using this template. The ProjectType element which starts as CSharp says which node our project template will be placed in, in the New Project Dialog.

The element describes the specific files that will be used as a part of the project template. This starts with the element with an Attirube of "File" that points to the csproj for fsproj file to be used in the project.

<Project File="ProjectTemplate.csproj" ReplaceParameters="true">

This line states when creating a new Project from the template "ProjectTemplate.csproj" will be used as the basis for the new .csproj file created when using this template. The "File" attribute is telling the .vstemplate where to find the .csproj file to use as the template. It is in the root of our current project now. The "ReplaceParameters" attribute tells visual studio to look for any replacement parameters in the "ProjectTemplate.csproj" file and replace them with the appropriate value. This will be true of any file listed in the .vstemplate with a ReplaceParameters="true".

Replacing Parameters

Let’s look at some of the values in the ProjectTemplate.csproj now. Here is the first PropertyGroup in the ProjectTemplate.csproj.

<PropertyGroup>
<Configuration Condition=" '$(Configuration)' == '' ">Debug</Configuration>
<Platform Condition=" '$(Platform)' == '' ">AnyCPU</Platform>
<ProductVersion>8.0.30703</ProductVersion>
<SchemaVersion>2.0</SchemaVersion>
<ProjectGuid>$guid1$</ProjectGuid>
<OutputType>Library</OutputType>
<AppDesignerFolder>Properties</AppDesignerFolder>
<RootNamespace>$safeprojectname$</RootNamespace>
<AssemblyName>$safeprojectname$</AssemblyName>
<TargetFrameworkVersion>v$targetframeworkversion$</TargetFrameworkVersion>
<FileAlignment>512</FileAlignment>
</PropertyGroup>

Notice there are a few values that start and end with $. Any values starting or ending with $ will get replaced with values in Visual Studio. The $guid1$ parameter tells Visual Studio to generate a new guid for this location when creating the project from the template. The $safeprojectname$ parameter gets replaced with the Name entered when the New Project Dialog is used to create a new Project in Visual Studio. Notice its used for the AsemblyName, and the RootNamespace.

Now let’s take a look at the AssemblyInfo.cs that was generated

[assembly: AssemblyTitle("$projectname$")]
[assembly: AssemblyDescription("")]
[assembly: AssemblyConfiguration("")]
[assembly: AssemblyCompany("$registeredorganization$")]
[assembly: AssemblyProduct("$projectname$")]
[assembly: AssemblyCopyright("Copyright © $registeredorganization$ $year$")]
[assembly: AssemblyTrademark("")]
[assembly: AssemblyCulture("")]

You can see in the AssemblyInfo.cs also has some values that will get replaced during the creation of a project. There are quite a few. If you want to view all the builtin replacement parameters you can check them out here.

Finally lets look at the Class1.cs that was generated with the project.

using System;
using System.Collections.Generic;
$if$ ($targetframeworkversion$ >= 3.5)using System.Linq;
$endif$using System.Text;
namespace $safeprojectname$
{
    public class Class1
    {
    }
}

This should be pretty straightforward. Its using the project name as the namespace and verifying what version of .NET you are targeting.

Compiling a template

Since we started with a C# Project Template Project we can actually just build the project and get a usable template, assuming we didn’t mess anything up along the way.

Lets build it now. I typically use CTRL + SHIFT + B to build. After its built we can look in the output folder, and we should see a bunch of nested folders.

Since its still a C# project template it puts it out into Bin/Debug/ProjectTemplates/CSharp/1033/FancyProjectTemplate.zip.

If we look inside the zip file, we’ll see our project template contents.

You might have noticed all that happend is that our project was zipped an placed in a folder.

Well that is basically all that is required to create a template. Include a .vstemplate file the references the files you want in your template, set the replacement parameters in the files where you want values overriden. Sepcify ReplaceParameters in the .vstemplate where you listed your files, and zip it up. In this case just compile it.

Deploying a Project Template

Its pretty easy to deploy a project template. The simplest way is to copy the zip file to your c:\user\documents\Visual Studio 2015\Project Templates\Visual C# directory. Then the next time you are in the New Project dialog you can use your template to create a new project.

Summary

We looked at using the extensibility project templates in Visual Studio to create a simple project template. In future posts we will look at how to make an F# project template, and how to create a VSIX installer and publish our template to the Visual Studio Extension gallery.

Spread The Word
Adam.Wright
 

Adam Wright is a technologist specializing in software development using Microsoft technologies.

Click Here to Leave a Comment Below 0 comments