Creating and Sharing Project & Item Templates

One of the great new features we added in Visual Studio 2010 is the ability to easily find and consume online Project and Item templates without leaving the New Project/Item dialog. What may not be so obvious is how to go from a piece of code you want to share to a template contained in a VSIX file that can be uploaded to the Visual Studio Gallery or shared with others in your organization.

This post describes two ways (one quick and simple, the other for more complex situations) to create a VSIX file that contains your shareable code templates.

Quick, (mostly) Automatic Way: Export Template as VSIX

In a series of posts on Visual Studio 2010 Beta 1 (Part 1, Part 2, Part 3, Addendum), Pedro Silva walked through the process of using the standard Export Template wizard that has shipped in Visual Studio for several releases in combination with the VSIX Explorer tool or the VSIX Project template in the Visual Studio SDK to package up your template. While this does the job, it seemed like a few too many steps for something that should be straightforward.

To make this process much simpler, we recently published a new Export Template as VSIX wizard that will guide you through the process of turning an existing project into a VSIX file containing your template. After downloading the Export Template as VSIX wizard from the Visual Studio Gallery website or the Extension Manager dialog, you will find a new option on the File menu in Visual Studio 2010 for “Export Template as VSIX…”. This will bring up the Export Template as VSIX Wizard, which will allow you to configure options for both the template and the VSIX file that will contain it.

Longer, (mostly) Manual Way: Template Project + VSIX Project

While this is the ideal way to quickly share some starter code with others, it is not ideal for all situations where you’re creating a template. For example, you may be building a series of templates in conjunction with a VSPackage or editor extension. What if you are making frequent changes to the template files? What if you wish to keep the template source files in a version control system? What if you need to make a customization to the templates or the VSIX container not permitted by the Export Template as VSIX wizard?

This is where the Visual Studio SDK comes in to help. In the Visual Studio 2010 SP1 SDK, we’ve included project templates for building project and item templates. (Yes, we’ve created templates for templates.) If you go to the Extensibility node under Visual C# or Visual Basic in the New Project dialog, you’ll find two new templates (for either a project template or an item template). Let’s walk through the process of creating and packaging a C# Project template using these new templates in the Visual Studio SDK.

Walkthrough: Packaging a template with the Visual Studio SDK

First, we'll create a project template project which generates a zip file for a single template. Then, we'll create a VSIX project to contain and deploy the generated project template.

1. Open the New Project dialog to create a new “C# Project Template” from the Extensibility category called “MyTemplate”. There are a few interesting things to note about the generated project:
   • The .vstemplate file has a Build Action of “VSTemplate”. The .cs, .csproj, and .ico files have a Build Action of “None”. Since this project is meant to build a .zip file, not a .dll or .exe file, the code files are not compiled or treated as code by the build targets.
   • If you open Class1.cs or ProjectTemplate.csproj in the text editor, you’ll see that there are several VSTemplate parameters ($safeprojectname$, $guid1$, etc…) that will be replaced when the template is instantiated.
   • The files to include in the zip file are discovered at build time by reading the .vstemplate file. Any files not specified in this file will not be included in the template zip file.
2. Build the project. Note that a .zip file is created for you in a subdirectory of the project output folder. (In our example, the template builds to ProjectTemplates\CSharp\1033\MyTemplate.zip.) The subdirectory in the output folder is determined by looking at a few things at build time:
   • The “Type” attribute in the .vstemplate file root node. Project templates go under “ProjectTemplates”. Item templates go under “ItemTemplates”.
   • The “Language” part of the path (“CSharp” in our example) is determined by the <ProjectType> node in the .vstemplate file.
   • The next part of the sub path is optional (and null by default). This is the OutputSubPath. This can be used for placing the template in a sub-node (e.g. Windows, Web Silverlight) in the New Project dialog. Since we’re building a template for targeting Windows, let’s specify this additional piece of metadata in the MyTemplate.csproj file. (You can edit the file by right clicking the project node and choosing “Unload Project”. Then right click the project node again and choose “Edit MyTemplate.csproj”.)
     

     <VSTemplate Include="MyTemplate.vstemplate"> <OutputSubPath>Windows</OutputSubPath></VSTemplate>

   • The “1033” in the path is the LCID of the template. The LCID for English (US) is 1033 and this is the default. To change the LCID (for example to 1041 for Japanese), you must edit the MyTemplate.csproj to the following:
     

     <VSTemplate Include="MyTemplate.vstemplate"> <OutputSubPath>Windows</OutputSubPath><Culture>1041</Culture></VSTemplate>

   • Finally, the name of the zip file is taken from the name of the project specified in the New Project dialog.
3. The project we just created only builds a zip file for you. It does not build a VSIX file, nor does it set up the template for debugging in Visual Studio. To do that, add a new VSIX Project to your solution and call it “MyTemplateSetup”. (You can find the VSIX Project template also on the Extensibility node in the New Project dialog.)
4. When the VSIX project is created, you should see the editor for your source.extension.vsixmanifest file appear. Click the “Add Content” button to specify that the template file you created in steps 1-2 should be included in the VSIX file built by this project.
   
   
   • Select “Project Template” for the content type
   • For the source, select “Project” and then choose the “MyTemplate” project.
   • Click OK
5. Save and close the VSIX manifest editor
6. Right click the “MyTemplateSetup” project and select “Set as StartUp Project” to debug your template in the Visual Studio Experimental instance.
7. Press F5 to start debugging (or CTRL + F5 to launch without the debugger).
8. Show the New Project dialog in the Visual Studio and see your template listed under “Visual C# \ Windows" (if you added the OutputSubPath from step 2).

There are a few other interesting points about the support in the SDK for building templates:

• Multi-project templates are supported
• If you are building a collection of templates, you can include them all in one VSIX file by repeating the steps above (skipping step 3).

While not as simple as the “Export Template as VSIX” wizard, this technique allows you to build templates and deliver them using the VSIX format while still keeping control over the template source files.

Aaron Marten - Developer, Visual Studio Platform

Short Bio: Aaron has been on the Visual Studio team for 6 years with a focus on extensibility. For Visual Studio 2010, Aaron worked on the Extension Manager and the Visual Studio SDK. In addition to contributing to the Visual Studio blog, he also writes about extending the IDE on his own blog at http://blogs.msdn.com/aaronmar.