How to create a great online project template (or how to make applications that speak)

Like the project templates installed with Visual Studio, online project templates enable people to easily start creating various applications. It’s not just Microsoft that creates these templates -- anyone can create an online template and publish it at the Visual Studio Gallery.  Once it’s published, developers can access online project templates by clicking File->New->Project in Visual Studio and then clicking “Online Templates”.   This post will show you how to create an online template that has a clear purpose and that shows you what to do next after you install it.  In other words, how to create a great online project template!

An Example

To get started let’s look at the online template IE8 Accelerator (CS).

Even though you may not know exactly what an IE8 accelerator is, the inclusion of a thumbnail icon + a preview image + a description help to explain the purpose of this application. The purpose was clear and it sounded useful so I decided to give it a try.

I clicked “OK” to install the template and once the download and install completed I was presented with a “Readme” welcome page to instruct me on how to get started.

Most project templates that I’ve seen create a project and leave me hanging without any idea of what to do next.  But this one was different.  It gave me a welcome page that told me exactly what to do next.  Not only was I able to install and use the MSDN Accelerator that came with the template, I was also able to create quickly two more projects: one accelerator for Visual Studio Gallery, and another for an internal search tool that our team uses a lot.  I had some suggestions for the author of the template, so I left a comment in the Discussion which you can reach from the More Info link in the New Project dialog.

The IE 8 Accelerator template is a great template because

• It includes a thumbnail icon, a preview image, and a short description about what the template does, and
• It shows you what to do next after you install it via a welcome page.

How to create a great online project template

Here’s how you can create an online project template like IE 8 Accelerator that has a clear purpose and shows you what to do next.

1. In Visual Studio Pro or above go to Tools -> Extension Manager, click on the “Online Gallery” and type “Export Template” into the search bar. The result list should display the Export Template Wizard. .
   
2. Click “Download” to install and then restart Visual Studio in order to finish installing the extension.
3. Create the project that will be the basis for your template.  I decided to create a template for a talking program in which the consumer can replace “Hello World” with anything he or she wants the program to say.  Here are the steps I used:
   a. File –> New –> Project -> C# (or VB) -> Console Application
   b. Right click on the project name -> Add Reference -> .NET -> System.Speech
   c. Use the System.Speech.Synthesis namespace in Program.cs:

using System.Speech.Synthesis;

d. Add the code below into the Main method of Program.cs.  (The "using" statement automatically takes care of disposing of all the resources used by the speech synthesizer when it is done.)

using (SpeechSynthesizer synth = new System.Speech.Synthesis.SpeechSynthesizer())
{
    synth.Speak("Hello World");
}

e. Turn up the volume and debug your project.  :)

4. Now let’s create a Welcome Page for your template.  We want to give the best possible experience to the consumer of the template, so what we need to do as a template author is a little tricky. 
   a. In a folder outside your project create a welcome.htm file.
   b. If you link images (using the <IMG> tag) then put those images in a welcomeimages subdirectory.  
   c. Add your content to welcome.htm and get all your images ready in welcomeimages.
   d. Open welcome.htm in a browser or Visual Studio and verify that everything looks as expected.
   e. Copy welcomeimages into the project, but do not copy welcome.htm.  The template will create welcome.htm when a project is created from it.
5. File -> Export Template as VSIX
6. On the first screen of the wizard, select the project you are exporting as a template.  Item templates can also be exported on this screen, but they are outside the scope of this post.  For more information about project and item templates see Visual Studio Templates.
7. On the second screen of the wizard, enter the following:
   a. Template Name: projects created from this template will have this default name
   b. Template Description: this description will appear when users browse templates in Visual Studio.  It should concisely explain the purpose of your template so that consumers can decide whether they are interested.
   c. Icon Image: Appears to the left of the template name when selecting the template.  A good source of icon images is the Visual Studio Image Library
   d. Preview Image: Larger image that gives a preview of the template’s purpose.  If your application has UI, a screenshot is usually a great preview image. If it doesn’t have UI, a good source of images is Office Clipart.
   e. (optional) Wizard Assembly: enables you to execute custom code when a project is created from your template; wizards are out of scope of this post.   
   f. Welcome page: browse to your welcome.htm file.
      
8. On the third screen of the wizard you can enter the following:
   a. VSIX Id: Uniquely identifies your template in Visual Studio and on the Visual Studio Gallery.  This will be auto-generated for you.
   b. Product Name:  this name shows up on the Visual Studio Gallery web site and in the list of Online Templates, so it’s a good idea to include spaces in the name to make it look good. 
   c. Company Name: Your company name or your name. This will show up as Created By in Visual Studio when consumers browse online templates.
   d. Version: Higher numbered versions supersede lower numbers in Visual Studio and the Visual Studio Gallery.
   e. License: When you distribute a template through the Visual Studio Gallery, it is covered automatically under the terms of the Contribution Agreement.  Therefore, for online templates leave the License field blank.
   f. Getting started guide URL: this only shows up in the Extension Manager so it isn’t terribly useful.  However, I put in a reference to A Very Easy Introduction to Microsoft.NET Speech Synthesis.
   g. Supported VS Editions: VS 10.0 Professional includes VS Professional, Premium, and Ultimate.  Click Select to choose other additions as well such as C# Express.
   h. Output Location: Auto-generated for you.  You’ll browse to this location later when uploading the VSIX file into Visual Studio Gallery
   i. Automatically import the template into Visual Studio: Check this so that you can immediately verify your template.
    
9. Now verify that your template works as expected in Visual Studio:
   a. Find the template under Installed Templates and create the project.
   b. Verify that the Welcome Page opens and looks as expected
   c. Debug the project – verify that it builds successfully and that the application works as expected.
10. Publish your template to Visual Studio Gallery
    a. Browse to http://visualstudiogallery.msdn.microsoft.com/
    b. Click the Upload button
    c. Log in with your Windows Live ID. (If you don’t have one you can sign up for one.)
    d. Select “Project or Item Template” and click Next.
    e. Browse to the .vsix file that you exported above and click Open
    f. Click Next
    g. Click the check box on up to 3 categories.  These categories determine where your template will appear in the New Project dialog.
    h. Enter Tags.  Template consumers can find your template using these tags.
    i. Cost Category: Only Free is supported at this time.
    j. Allow discussions for your extension: Check this so that you will be able to get feedback from users of your extension.
     
    k. Scroll down and enter a description.  This description will appear when the consumer clicks More Info for your template in the New Project dialog.  I like to capture here the purpose and pointers for what to try next.
    l. Agree with the Contribution Agreement, enter the encoded words, and click Create Contribution.
    m. Click “publish it” to make your extension visible to others!
     
11. Verify that your template appears and works as expected in Visual Studio.
    a. Browse to your template in the New Project Dialog.
    b. Select the template and OK to install it.
    c. Verify that the welcome page looks as expected.
    d. Debug – verify that the project builds and works as expected.
    e. Pretend you are a consumer of the template: modify Hello World to display something else; browse to some of the information links on the welcome page and see how easy it is to extend the project.

To see the online template created above look at Hello World Out Loud. 

We hope these resources will be of great help to you. As always, we are happy to hear your feedback. Please comment on this blog post to do so.

Michael Leonard, Software Design Engineer in Test, Visual Studio Platform. 
Short Bio: Michael was responsible for testing the New Project Dialog and the Visual Studio 2010 Express editions.  His passion is for smoothing the learning curve for Visual Studio users of all levels.