Creating a custom Visual Studio project template that you can use from the ‘New Project’ dialogue is a great way to reduce the amount of repetitive code you have to write. It gets you running through the jungle with the leaves brushing against your face, instead of sitting at the starting block wondering where your shoes are.
The Visual Studio Gallery is a great place to share your custom Visual Studio project template with the community. There are actually two ways to create a template. I recently had to create one for ASP.NET MVC Boilerplate and found it less than simple. This post talks you through creating one and submitting it to the Visual Studio Gallery, allowing anyone to use it from the ‘New Project’ dialogue.
Export Template as .zip
The first method of creating a custom project template is to use the ‘Export Template’ wizard in Visual Studio, as shown in the steps below, you can create a .zip file which contains a template of your selected project.
The wizard allows you to select the project from your solution you want to export as a template.
You can even specify an icon and preview image of the project template. This is perfect as this information also gets displayed in the Visual Studio ‘New Project’ dialogue.
The .zip file that is output must be copied into the following folder, for Visual Studio to pick it up:
C:/Users/[Your User Name]/Documents/Visual Studio [2010|2012|2013|2015]/Templates/ProjectTemplates
This is a super easy process and you should really consider creating your own templates if you find yourself making the same old changes to every project you are creating. The downside is that its not very customizable and these types of project templates cannot be submitted to the Visual Studio Gallery.
The gallery website only supports project templates created using the VSIX package. Creating a VSIX package is a pretty involved process and will take a couple of hours.
Export Template Wizard Extension
This Visual Studio extension claims to support exporting your projects into VSIX packages using a simple wizard interface. Unfortunately, this tool is only available for Visual Studio 2010 and the Microsoft developers of the extension seem to have stopped further development.
This is a real shame. Here we have an excellent tool which the community really needs. A tool that makes creating a VSIX project template package, a matter of a few clicks. This should be built into Visual Studio out of the box!
SideWaffle Project Templates
There is even an alternative method of creating project templates and sharing them with the community that I should mention. It’s called SideWaffle (I like the name for some reason). It makes it slightly easier to create a template but its still not as simple as a few clicks. It’s certainly something worth taking a look at though.
Creating a VSIX Package
The first step is to create a .zip project template package using the steps above. Once you’ve done that, download and install the Microsoft Visual Studio 2013 SDK. This will give you new project templates to create VSIX packages. The first thing to do is create a new C# Project Template (Or a Visual Basic one if you prefer).
The next step is to open the .zip version of your project template and copy the contents into your new project. Copy everything (Including the project file), except the ‘Properties’ folder as this will conflict with the existing one in the project.
Select all the files in the project and in the properties window, ensure that their ‘Build Action’ is set to ‘Content’.
The .vstemplate file in the project contains all the information about the contents of the project template. If you select it and go to the ‘Properties’ window, you can set the ‘Category’ property which determines where your project template will appear in the ‘New Project’ dialogue.
Note, that I’ve set the project template name, description and the default name of the project which is shown in the ‘New Project’ dialogue and the user can rename. The XML then goes on to declare the name of the .csproj file in the ‘Project’ node, followed by each and every file and folder to be included in the template.
Note, that the AssemblyInfo.cs file is a little special. There are two of them in the project. The one we are interested in was already located in the root of the project when we created it. We also need to add it to the XML below slightly differently than the other files (See below).
You can use the ‘OpenInWebBrowser’ or ‘OpenInEditor’ attributes on a ‘ProjectItem’ to get the file to be opened in a web browser or text editor when the project is first created. I’ve used ‘OpenInWebBrowser’ to open the ReadMe.html file containing basic information about the project, when the project is first created.
<?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">
<Name>ASP.NET MVC Boilerplate</Name>
<Description>A professional ASP.NET MVC template for building secure, fast, robust and adaptable web applications or sites. It provides the minimum amount of code required on top of the default MVC template provided by Microsoft. Find out more at RehanSaeed.com</Description>
<Project File="MvcBoilerplate.csproj" ReplaceParameters="true">
<ProjectItem ReplaceParameters="true" TargetFileName="Properties%5CAssemblyInfo.cs">AssemblyInfo.cs</ProjectItem>
<ProjectItem ReplaceParameters="true" OpenInEditor="false">BundleConfig.cs</ProjectItem>
<ProjectItem ReplaceParameters="true" OpenInEditor="false">FilterConfig.cs</ProjectItem>
<ProjectItem ReplaceParameters="true" OpenInEditor="false">RouteConfig.cs</ProjectItem>
<ProjectItem ReplaceParameters="true" OpenInEditor="false">Startup.Container.cs</ProjectItem>
<!-- Omitted lots of Folder and ProjectItem nodes... -->
<ProjectItem ReplaceParameters="true" OpenInWebBrowser="true">ReadMe.html</ProjectItem>
The next step is to add a VSIX Project to our solution. This is the project that will actually build a .vsix file.
If you open the .vsixmanifest file, you can fill in basic information about the template. This information will be displayed in the ‘New Project’ dialogue. I have specified an Icon, Preview Image and Licence file. All three of these files are added to the project.
The ‘Install Targets’ tab lets you target a specific version of Visual Studio. I changed this to support Visual Studio 2012 and above by specifying the version range to be [11.0,]. More information here.
The ‘Dependencies’ tab is very similar. Here you can specify which version of the .NET Framework your project depends on. I stuck with the defaults of .NET 4.5 only.
If you click on the ‘Assets’ tab on the left, you can add a reference to your other ‘C# Project Template’ project.
Submitting your VSIX Project Template to the Visual Studio Gallery
Submitting your new VSIX extension to the Visual Studio Gallery is a great way to share your new Project Template with the world. The ASP.NET MVC Boilerplate extension now has over a hundred downloads within two days of submitting it!
If you’ve followed the steps above to create a VSIX package and tested that it works correctly then submitting one to the site is really easy. Follow this link to the submission page and fill in the form. An example of what it looks like can be seen below:
Once you have made your submission and you go to the ‘New Project’ dialogue, you can go to the ‘Online’ section and see your project template listed.
If you use the template above, explicitly install it from the Visual Studio Gallery or install it from ‘Extensions and Updates’, you will then see the project appear in the ‘New Project’ dialogue under the category you specified in the settings above.
Creating a simple .zip project template is super simple and something everyone should know and use for larger projects. Creating VSIX project templates is a lot more involved but to be honest, there is no reason why it should be. I hope Microsoft makes this process a lot easier.