Creating and Sharing Project & Item Templates

Creating and Sharing Project & Item Templates

Rate This
  • Comments 16

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.

Export Template As VSIX Wizard

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?

C# Project Template in New Project Dialog

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.

    Add Content dialog in VSIX manifest editor
    • 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.

aaronm3Aaron 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.

Leave a Comment
  • Please add 6 and 5 and type the answer here:
  • Post
  • Aaron,

    Attemting to follow above:

    Results in an Internal Compiler Error:

    Seems to be linked to step 4 - linking in the Template sub-project.  If this is not linked - compiler does not complain, if linked as described above - compiler crashes with error below

    Error 3 Internal Compiler Error (0xc0000005 at address 0FA616A1): likely culprit is 'BEGIN'.

    An internal error has occurred in the compiler. To work around this problem, try simplifying or changing the program near the locations listed below. Locations at the top of the list are closer to the point at which the internal error occurred. Errors such as this can be reported to Microsoft by using the /errorreport option.

    TestTemplateSetup

  • @David I'm not able to reproduce the ICE error you're describing when using Visual Studio 2010 RC and the matching Visual Studio SDK build. Could you contact me via my blog (http://blogs.msdn.com/aaronmar) so we can debug this further? I'd be interested to find out more about your machine configuration.

  • Does this (or something similar) work for Item templates as well?

  • @Cameron  Yes. This is mentioned in the post title, but not in the walkthrough. In step 1, choose "C# Item Template" from the New Project Dialog and the remaining steps should be essentially the same.

  • Applied two VS patches - now works as described above!

    Thanks.

    djt

  • "David Tuke" Which patches you applied?. I am also not seeing these options of C# Item Template & C# Project Template. Can anyone help me out ?

    I am running VS 2010 Ultimate.

    Thanks

  • C++!?

    It seems to be you have appareltly missed out on way to create templates for C++? ...or do you will all your clients to switch to ever improving XCode?!?

  • How can I have my Custom Project Type Node(ex. MyProjectType) and ProjectSubnode(ex. MyProjectNode), I don't want to have CSharp as my Project Type Node. Also at which Location and File we put the following infomration.

    <VSTemplate Include="MyTemplate.vstemplate">    

    Please let us know if you have any sample code.

    Thanks,

    Mohi

    dotnethungry2010@gmail.com

  • I do it like you said,but there is errors which said can't recognize the "$".Is there any way to solve it?

  • i made project sharing website necessary help give me my id untilboy@gmail.com anyone can help you contact id

  • Sounds like a good approach. Would you give a hint how are the steps different when packaging a multi-project template? Especially, packaging existing projects as a multi-project template?

  • I got most of this to work, I ran into an issue because it only install it for the user runnning it.  So I found the <AllUsers>true</AllUsers> that needs to be added to the extension.vsixmanifest.  Now when I install it, it does put it in for all users but I can only see it if I run VS2010 as an administrator.

    How do I fix this!!!!

  • As an additional note it appears that if I use another account that is an AD group that is an admin on the local machine it wont work unless I specificly put that account in hte Admin group can I run it as an admin to see the template

  • Hi,

    I created a basic project system by following this: msdn.microsoft.com/.../cc512961.aspx. It works good in experimental hive.

    Then I created I a VS Isolated Shell by following msdn.microsoft.com/.../cc512961.aspx. It works ok too.

    Then I tryied to include the project system to my custom isolated shell by following msdn.microsoft.com/.../ee524005.aspx.  My custom project shows up on the "New Project" dialog, but when I click on the OK button on the dialog, it gives me an error msg saying "The extension '.MyProjExt' is not supported by this version of the applicaiton. To Open it, please try the version that supports it."

    Both projects(isolated shell and custom project system) are in the same solution.

    Please help.

    I posted it also in MSDN Forum (social.msdn.microsoft.com/.../8cd221ec-838c-4299-8602-0f880edff49f), no help.

    Regards,

    Mizan

  • Hi Guys, the "Export Template as VSIX wizard" was great in VS2010 can you make is available for 2012 and 2013 please?

    Steve

Page 1 of 2 (16 items) 12