Creating a new category for Custom Templates with a new entry to Install Templates for Visual Studio using Extensibility Project of VS2010 SDK

Download

Introduction

A recent requirement in the project demands a new entry in the "Install Template" section of VS environment.

When the user chooses that, then a custom project template will appear in the VS IDE similar to the already existing ones.

The custom project template will contain the below

1. The solution file will have one project
2. One custom dll in the references folder(MyMath.dll)
3. One folder having one class file(Folder Name: MyFolder,Class Name: MyClass)
4. One class file at the project root level(RootLevelClass.cs)

In a word the final output will be

How to do it?

We will use Extensibility Project of Visual Studio 2010 SP1 SDK for solving this problem.With the VS2010 SDK, we can create a VSIX package that will automatically install all the project templates and item templates. We can also manage all the templates and installers in a single Visual Studio solution.

Steps needed to do so

Step 1: Download Visual Studio 2010 SP1 SDK

Step 2:Install it

Step 3:

Let us open up Visual Studio.File -> New Project (or Ctrl + Shift + N).There is a new category under Visual C# called "Extensibility". Choose "VSIX Project" and click on OK button for the new project to get created in the current solution.

The VSIX project will appear as under

It contains a vsixmanifest file("source.extension.vsixmanifest") about which we will look at a later point of time.

Step 4:

Now we need to create another project of type "C# Project Template" from "Extensibility" template and need to add to the same solution.

At this stage the solution explorer will appear as under

There are atleast two files in the C# Project Template viz.

1. .csproj file(ProjectTemplate.csproj)
2. .vstemplate(SampleProject.vstemplate)

which needs some attention.These two are the configuration files and the way our project template will appear finally depends on how we do the setting properly here.We will look into those more deeply after sometime.

Step 5:

Now let us make the needed project structure

An astute reader might have noticed that, we have deleted "Class1.cs " and "SampleProject.ico" files from the root folder since we donot want them to appear in our project structure

N.B.~The "MyMath.dll" needs to have a strong name first and then needs to register into the GAC using

gacutil -i "Full Path Name of MyMath.dll"

Step 6:

Now let us open the ".csproj" file(ProjectTemplate.csproj).The default structure looks as under

<?xml version="1.0" encoding="utf-8"?>
<Project ToolsVersion="4.0" DefaultTargets="Build" xmlns="http://schemas.microsoft.com/developer/msbuild/2003">
<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>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Debug|AnyCPU' ">
<DebugSymbols>true</DebugSymbols>
<DebugType>full</DebugType>
<Optimize>false</Optimize>
<OutputPath>bin\Debug\</OutputPath>
<DefineConstants>DEBUG;TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
</PropertyGroup>
<PropertyGroup Condition=" '$(Configuration)|$(Platform)' == 'Release|AnyCPU' ">
<DebugType>pdbonly</DebugType>
<Optimize>true</Optimize>
<OutputPath>bin\Release\</OutputPath>
<DefineConstants>TRACE</DefineConstants>
<ErrorReport>prompt</ErrorReport>
<WarningLevel>4</WarningLevel>
</PropertyGroup>
<ItemGroup>
<Reference Include="System"/>
$if$ ($targetframeworkversion$ >= 3.5)
<Reference Include="System.Core"/>
<Reference Include="System.Xml.Linq"/>
<Reference Include="System.Data.DataSetExtensions"/>
$endif$
$if$ ($targetframeworkversion$ >= 4.0)
<Reference Include="Microsoft.CSharp"/>
$endif$
<Reference Include="System.Data"/>
<Reference Include="System.Xml"/>
</ItemGroup>
<ItemGroup>
<Compile Include="Class1.cs" />
<Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>
<Import Project="$(MSBuildToolsPath)\Microsoft.CSharp.targets" />
<!-- To modify your build process, add your task inside one of the targets below and uncomment it. 
Other similar extension points exist, see Microsoft.Common.targets.
<Target Name="BeforeBuild">
</Target>
<Target Name="AfterBuild">
</Target>
-->
</Project>

Now let us visit the important section which we need to change for our project

We can make out that, for the dlls/references to add , there is the reference section.Henceforth, we also need to make a similar entry like the existing one.Suppose we want that our dll (MyMath.dll) will be added only if the target dotnet framework is atleast 4.Henceforth, we will make the entry as

$if$ ($targetframeworkversion$ >= 4.0)
<Reference Include="MyMath"/>
$endif$

For "RootLevelClass.cs", the entry will be

<Compile Include="RootLevelClass.cs" />

For the folder "MyFolder" and the class "MyClass.cs" inside that folder,the entry will be

<Compile Include="MyFolder\MyClass.cs" />

A complete entry is as under(I have kept only those that we modified and removed other things for the sake of brevity)

<ItemGroup>
$if$ ($targetframeworkversion$ >= 4.0)
<Reference Include="MyMath"/>
$endif$
</ItemGroup>
<ItemGroup>
<Compile Include="RootLevelClass.cs" />
<Compile Include="MyFolder\MyClass.cs" />
<Compile Include="Properties\AssemblyInfo.cs" />
</ItemGroup>

Step 7:

Now let us open the .vstemplate file(SampleProject.vstemplate).This file contains information needed to create new project in VS. The default content of .vsTemplate file are diaplayed below

<?xml version="1.0" encoding="utf-8"?>
<VSTemplate Version="3.0.0" Type="Project" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005">
<TemplateData>
<Name>SampleProject</Name>
<Description>
<No description="" available="">
</Description>
<Icon>SampleProject.ico</Icon>
<ProjectType>CSharp</ProjectType>
<RequiredFrameworkVersion>2.0</RequiredFrameworkVersion>
<SortOrder>1000</SortOrder>
<TemplateID>17a8b26e-c2af-49c8-964f-43ea7ce8c030</TemplateID>
<CreateNewFolder>true</CreateNewFolder>
<DefaultName>SampleProject</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>

The <TemaplateData> contains various tags whose purpose is self explanatory.We can change these values as we will see now:

For the <Name>, the value will be changed from "SampleProject" to "Our Sample Custom Project".

For the <Description>, the value will be changed from "No description available" to "Developed by Niladri Biswas".

For the <Icon>, the value will be changed from "SampleProject.ico" to "AppIcon.ico".

For the <DefaultName>, the value will be changed from "SampleProject" to "CustomSampleProject".

In <TemplateContent> tag, we need to mention details of all files which we wish to include in the template

<ProjectItem ReplaceParameters="true" OpenInEditor="true">RootLevelClass.cs</ProjectItem>
<ProjectItem ReplaceParameters="true" OpenInEditor="true">MyFolder\MyClass.cs</ProjectItem>

Hence, the complete .vstemplate file(SampleProject.vstemplate) will now look as under

<?xml version="1.0" encoding="utf-8"?>
<VSTemplate Version="3.0.0" Type="Project" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005">
<TemplateData>
<Name>Our Sample Custom Project</Name>
<Description>Developed by Niladri Biswas</Description>
<Icon>AppIcon.ico</Icon>
<ProjectType>CSharp</ProjectType>
<RequiredFrameworkVersion>2.0</RequiredFrameworkVersion>
<SortOrder>1000</SortOrder>
<TemplateID>17a8b26e-c2af-49c8-964f-43ea7ce8c030</TemplateID>
<CreateNewFolder>true</CreateNewFolder>
<DefaultName>CustomSampleProject</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">RootLevelClass.cs</ProjectItem>
<ProjectItem ReplaceParameters="true" OpenInEditor="true">MyFolder\MyClass.cs</ProjectItem>
</Project>
</TemplateContent>
</VSTemplate>

N.B.~The OpenInEditor="true" in ProjectItem tag indicates that the respective file can be set to be opened by default when we start a new project by selecting the template. The ReplaceParameters states that dyamic paramters can be added into the file and used by template when creating new project.For more information, we can read this.

N.B.~Remember that .vstemplate defines the project template. It will typically include a templated definition of a .csproj (or several) that will be created when we instantiate a project from that template.So generally the structure will be(with two .csproject)

<VSTemplate Type="Project" Version="3.0.0" xmlns="http://schemas.microsoft.com/developer/vstemplate/2005">
<TemplateContent>
<Project File="ProjectTemplate1.csproj">
<ProjectItem>Class1.cs</ProjectItem>
<ProjectItem>Properties\AssemblyInfo.cs</ProjectItem>
</Project>
<Project File="ProjectTemplate2.csproj">
<ProjectItem>Class2.cs</ProjectItem>
<ProjectItem>Properties\AssemblyInfo.cs</ProjectItem>
</Project>
</TemplateContent>
</VSTemplate>

Step 8:

At this point we should be able to build the project template. When we build it, it will show up under "bin\debug\ProjectTemplates\CSharp\1033".This will show up under Visual C# in the projects list. To make it show up in a custom category, manually we need to edit the project template's project file.Right-click on the template project(i.e. Sample Project) in the Solution Explorer, and choose "Unload project".

Then right-click on the project again, and choose "Edit SampleProject.csproj". This will open up the project file in an XML editor where we need to find the VSTemplate element and add a child element called "OutputSubPath" as follows:

<VSTemplate Include="ProjectTemplate1.vstemplate">
<OutputSubPath>Sample Test Project</OutputSubPath>
</VSTemplate>

Save the changes and right-click on the project and choose "Reload project".Now if we build, the output should show up under "bin\Debug\ProjectTemplates\CSharp\Sample Test Project\1033". This will allow our template to be in the custom category when we install it in Visual Studio.

Step 9:

Now let us go to the VSIX project inorder to get the template installed in Visual Studio.Double click on the "source.extension.vsixmanifest" file to open it. It should open in a designer for the manifest.

Enter value for the Author field which is a mandatory one.After this, come to the Content section and click the "Add Content" button.

In the "Add Content" dialog, set the content type to "Project Template". Then set the Project Source to "Sample Project", and click OK.

Step 10:

Building the VSIX project will generate a .vsix and a .manifest file in the "bin\debug" folder.

Click on the .vsix file to install the template in Visual Studio

Step 10:

Now open a fresh VS solution and we will find our Installed Template, Project Template.Click on that to get the custom project

How to Uninstall the custom template?

Tools -> Extension Manager

Choose the custom project template and click "Uninstall" button

Choose "Yes" to uninstall it

Reference

Conclusion

Hope this article has helped all of us to create a custom project template in VS enviroment.We will delve into more features in subsequent articles about the same.Zipped file is attached

If you like this article, subscribe to our RSS Feed. You can also subscribe via email to our Interview Questions, Codes and Forums section.