How to: Create Starter Kits

Article
02/03/2012

Don Peterson
Clarity Consulting, Inc.

December 2005

Applies to:
Visual Studio 2005
Starter Kits

Summary: Visual Studio 2005 templates and Starter Kits provide an efficient and customizable feature to enhance the productivity of any developer. Increasing productivity when starting new projects allows you to jump directly to the implementation of business logic and skip the redundant tasks you would have had to previously perform every time you began a new project. (15 printed pages)

What Is a Starter Kit?
Creating a Project Template
Creating a Starter Kit
Distributing and Installing a Starter Kit
Advanced Features
Conclusion

What Is a Starter Kit?

Before discussing what a Starter Kit is you must first understand Visual Studio templates. A template provides a starting point to begin new projects or project files. Project templates provide all the files necessary to create a new project and can include references, classes, forms, and project settings. The standard new project options you see in the New Project dialog window of Visual Studio such as Windows Application, Class Library, and Console Application are all project templates that come with Visual Studio. Item templates are pre-defined classes or files containing code or data that can be added into an existing project. Visual Studio comes with item templates that display in the Add New Item dialog window such as Class, Windows Form, and User Control. Project templates that use the new Visual Studio 2005 vstemplate architecture can be created from any Visual Basic, J#, or C# project, but are not available for C++ projects.

A Starter Kit is an enhanced project template distributed to other developers to demonstrate a specific technology or implementation. Starter Kits usually include documentation, sample code, and sample data. When a Starter Kit is opened the project can be run without any additional coding, or more features can be added by the user. Starter Kits are a great way to help others learn a language, class features, or a specific programming implementation or technique using a real world project example.

To create a Starter Kit you must first create a project template.

Creating a Project Template

With most new projects, there are a number of tasks that you must always perform when creating a new project to provide a standard feature or comply with a defined coding standard in your business. Developers can eliminate recurring tasks by building them into a Visual Studio project template, and then building their new projects based on the template. This example demonstrates how to create a project template for a simple Windows Forms project containing a standard Windows menu strip.

Create the Project

The first step to creating a Starter Kit is to create a new Visual Studio project that will become a project template.

Start a New Project by selecting the Windows Application template from beneath the Visual C# project type in the New Project dialog window and name it WindowsApplication1.
A new project is created in the solution explorer and includes a Form1 class that is opened in the designer.
Right click on Form1 in the designer and select the Properties menu. In the properties window set the Text property for Form1 to "Hello World Template" and the Size to 450, 400. These property settings will become default settings for any new projects created from this project template.
From the Toolbox window, expand the Menus & Toolbars section. Drag and drop a MenuStrip control from the Toolbox onto the Form in the designer.
Click on the menu shown on the Form in the designer where it is labeled Type Here. Enter the text "&File" to create the main menu item.
Next to the "File" menu item add a "&Edit", "&View," and "&Help" menu items.
Create two sub-menu entries under the File menu called "&Open" and "E&xit" as shown in Figure 1.

Figure 1. Adding a menu strip (Click on the image for a larger picture)
From the Toolbox window, expand the Dialogs section. Drag and drop an OpenFileDialog control from the Toolbox onto the Form in the designer.

Double click on the "Exit" sub-menu item you added to Form1 to bring up the Form1 class. Add a private variable that can be used to track if changes have been made to the form and check it in the Exit menu event handler before exiting the application.

private bool _isDirtyFlag = false;
private void exitToolStripMenuItem_Click(object sender, EventArgs e) {
if (_isDirtyFlag) {
if (MessageBox.Show(
"Your data has not been saved.  Are you sure you want to exit?",
this.Text,
MessageBoxButtons.YesNo
) == DialogResult.No)
{
return;
}
}
this.Close();
}

Switch back to the Form1 designer window and double click on the "Open" sub-menu item of Form1 to create a click event handler for it.
Add the following code within the Open menu item click event handler to show an Open File Dialog window and set the dirty flag if they open a document. When someone uses this template the Open File Dialog code will be in place and they can begin adding the open file logic necessary for their application requirements.
```
private void openToolStripMenuItem_Click(object sender, EventArgs e) {
if (openFileDialog1.ShowDialog() == DialogResult.OK) {
//TODO:  Add open file logic
_isDirtyFlag = true;
}
}
```
Before creating the template from your project ensure it builds without any warnings or errors. Press F5 to build and run the project.

Create the Project Template

Now that you have created the project it can quickly be turned into a project template for use in a Starter Kit.

Stop the project if it is running in debug mode.
Click the File, Export Template... menu item to launch the Export Template Wizard. The Export Template Wizard will walk you through creating the project template compressed file.
Choose Project Template as the type of template to create.
The "From Which Project would you like to create a template?" list box should default to your project since it is the only project currently open in your solution, as shown in Figure 2.

Note When creating a web template project an additional list box is shown so the developer can choose the development language that the template will appear under in the New Web Site dialog window. This option is only available for web templates because the New Web Site dialog window is laid out differently than the New Project dialog window.

Figure 2. Choosing a template type
Click Next to continue the Export Template Wizard.
For the Template Options the Template Name is what will appear in the New Project dialog window My Templates section for this template and is also the file name of the template zip file the wizard will create. The Template Name defaults to the name of the project. Change it to be "Hello World Application".
Enter a Template Description of "Hello World Template". See Figure 3.
By leaving the "Automatically import the template into Visual Studio" option selected the wizard will add the template to the My Templates section of the New Project dialog window for you. If you uncheck this option you will need to add the template manually later.
Click Finish to create the project template.

Figure 3. Template options
By default, the Template Export Wizard creates the Hello World Application template zip file in your "My Documents\Visual Studio 2005\My Exported Templates" folder. If the "Automatically import the template into Visual Studio" option was checked on the Template Options window, the file is also copied into the "My Documents\Visual Studio 2005\Templates\ProjectTemplates" folder. All template zip files found in this location will automatically appear in your New Project dialog window in Visual Studio.

Your template is now available for use in Visual Studio. To see it in action follow these remaining steps:

Select the File, New, Project... menu option.
There is now a Hello World Application template listed under the user templates section of the New Project dialog window as shown in Figure 4. Double click on this template to create a new project from it.
A new project is created with Form1 open in the designer window. This Form1 contains the MenuStrip and OpenFileDialog controls you added to the template. Looking at the Form1 properties you can also see that the Size and Text properties you set in the template are reflected in the new project.

Figure 4. Opening the user template

Creating a Starter Kit

Once a project template is created it can be turned into a Starter Kit. Creating a Starter Kit involves enhancing an existing project template to include documentation, source code, and modifying the .vstemplate file that describes the kit's contents.

When creating a Starter Kit you should consider the following best practices:

Keep the project files organized by putting only a few files in the root node of the project. Try to move files and classes into subfolders if they are not the most important files a reader will need to look at to understand the application.
Keep documentation, resources, and sample data in subfolders and not in the root node of the project, as demonstrated in Figure 5.
Clearly identify the main form or starting point of the application.
Ensure the code follows a coding standard and is consistent throughout the project.
Run FxCop, or a similar code analysis tool, on the Starter Kit project and correct any warnings that are detected.
Comment liberally throughout the code, including placing comments around all types, methods, and properties.

Figure 5. Example Starter Kit project files organization

Making a Project Template into a Starter Kit

We will make a Starter Kit using the Hello World Application project template created in the previous section.

We need to open the original WindowsApplication1 project that the "Hello World Application" template was exported from in the previous example. To do this go to the Visual Studio Start Page and click on the WindowsApplication1 in the Recent Projects list, or use the File, Recent Projects menu option.
In the Solution Explorer right click on the project name and select the Add, New Folder menu option. Rename the new folder 'Documentation.'
Right click on the new Documentation folder and select the Add, New Item menu option to open the Add New Item dialog window.
Select the HTML Page item and click the Add button. The HTMLPage1.htm file will open for editing in Source mode.
Click the Design option to switch to design mode for the HTML page. Enter the following text: "This is the documentation for the Hello World Application."
Save the changes to HTMLPage1.htm
Click the File, Export Template... menu option. Follow the Export Template Wizard instructions to export a new version of this project template (refer to the Creating a Project Template section for information on the Export Template Wizard). When saving the template you may be prompted with a dialog window stating "The file already exists, do you want to delete to continue." Select OK to overwrite the template file that was exported in the previous section.
Find the Hello World Application zip file in the "My Documents\Visual Studio 2005\My Exported Templates" folder and extract the contents into a HelloWorldTemp directory.
Double click on the MyTemplate.vstemplate file from within the HelloWorldTemp folder to open it within the Visual Studio editor.

To ensure that the documentation is readily apparent to any user of this Starter Kit we will set the HTMLPage1.htm documentation page to open when the Starter Kit is opened. In the MyTemplate.vstemplate XML find the line appearing as:

<Folder Name="Documentation" TargetFolderName="Documentation">
<ProjectItem ReplaceParameters="true"
TargetFileName="HTMLPage1.htm">HTMLPage1.htm</ProjectItem>
</Folder>

Change the ProjectItem element by adding an OpenInWebBrowser attribute set to true. It should now appear as:

<Folder Name="Documentation" TargetFolderName="Documentation">
<ProjectItem OpenInWebBrowser="true" ReplaceParameters="true" 
  TargetFileName="HTMLPage1.htm">HTMLPage1.htm</ProjectItem>

</Folder>

Save the MyTemplate.vstemplate file.
Now create a new updated Hello World Application template zip file that will contain the updated MyTemplate.vstemplate file. In Windows Explorer navigate into the HelloWorldTemp folder and press CTRL-A to select all the files within the folder. With the files still selected, right click and select the Send To, Compressed (zipped) Folder menu item. After the zip file is created rename it to be 'Hello World Application.zip.'

Note Be sure to zip only the contents of the HelloWorldTemp folder and not the folder itself. Visual Studio expects the file structure of the zip file to contain the MyTemplate.vstemplate and other project files in the root of the zip.
Move the new Hello World Application zip file to the "My Documents\Visual Studio 2005\Templates\ProjectTemplates" folder to make the Starter Kit project template available in the New Project dialog window. If you are prompted to overwrite the existing file answer 'Yes.'

The Starter Kit is now finished. To test the Starter Kit perform the following two steps:

Open Visual Studio 2005 and select to begin a New Project. The Hello World Application template is now listed In the My Templates section of the New Project dialog window.
Select to create a new project from your template and the project will open in the solution with the HTMLPage1.htm file open.

Distributing and Installing a Starter Kit

In order for developers to use your Starter Kit, you need to deploy it. Visual Studio 2005 has included the Visual Studio Content Installer, which is an easy way to package a Starter Kit for distribution and installation to other developers. Also, built into the IDE are direct links to developer community Web sites from which developers can download Starter Kits directly through the Visual Studio IDE.

Visual Studio Content Installer

The Visual Studio Content Installer is a stand-alone tool that is installed as part of Visual Studio and that supports the installation of Starter Kits deployed as .vsi files. A .vsi file is a zip file containing the project template zip file and a .vscontent file. The zip file is named with the file extension .vsi instead of .zip so that Windows will launch the Visual Studio Content Installer instead of file explorer when the file is opened, taking the user directly into installation.

The .vscontent file is an XML document specifying the descriptive information about the Starter Kit, including the name of the template zip file that should be present in the .vsi file.

Creating a .vscontent File

Create a new text file in any text editor such as Notepad.

Enter the following XML to describe the Starter Kit.

<?xml version="1.0" encoding="utf-8"?>
<VSContent
xmlns="https://schemas.microsoft.com/developer/vscontent/2005">
<Content>
<FileName>Hello World Application.zip</FileName>
<DisplayName>Hello World Application</DisplayName>
<Description>Hello World Template</Description>
<FileContentType>VSTemplate</FileContentType>
<ContentVersion>1.0</ContentVersion>
<Attributes>
<Attribute name="TemplateType" value="Project"></Attribute>
<Attribute name="ProjectType" value="Visual C#"></Attribute>
<Attribute name="ProjectSubType" value=""></Attribute>
</Attributes>
</Content>
</VSContent>

Save the text file as HelloWorld.vscontent. Make sure to select the file type as "All Files" before saving so that a .txt extension is not automatically placed on the file name.

Creating a .vsi File

Using Windows Explorer, copy the HelloWorld.vscontent file and HelloWorldApplication.zip file into the same directory.
Select both files and right click on the HelloWorld.vscontent file and select Send To, Compressed (zipped) Folder.
A new file called HelloWorld.zip is created in the directory.
Rename the HelloWorld.zip file to HelloWorld.vsi.

Installing a Starter Kit with the Visual Studio Content Installer

When you download or receive a .vsi file you can use it to launch the Visual Studio Content Installer by following these steps:

Double click on the HelloWorld.vsi file to start the Visual Studio Content Installer wizard.
The installer first asks to select the Starter Kit to install and the "Hello World Application" is already selected. See Figure 6.

Figure 6. Visual Studio Content Installer Select Content screen
Click Next to continue.
A warning message appears since the content has not been signed. Click Yes to continue.
The Content Installation Summary screen appears, listing the Starter Kits and Templates that were included in the .vsi file and that will be installed. See Figure 7.

Figure 7. Visual Studio Content Installer Installation Summary screen
Press Finish to install the Starter Kit.
The Starter Kit will install and installation completed screen will display. See Figure 8.

Figure 8. Visual Studio Content Installer Completion screen

Installing Starter Kits for Multiple Users on a Single Machine

The Visual Studio Content Installer only installs the Starter Kit for the current user by placing the template in the "My Documents\Visual Studio 2005\Templates\ProjectTemplates" directory. There are two ways that you can make Starter Kits or templates available to all users on a machine:

Move the templates into a directory available to all users on the machine. For example, create a C:\CommonTemplates directory and copy all custom templates from the "My Documents\Visual Studio 2005\Templates\ProjectTemplates" folder to this location.
In Visual Studio all users must change their user template location property by opening the Tools, Options... window in Visual Studio. Select the Projects and Solutions option and set the Visual Studio user project templates location to C:\CommonTemplates. Press OK to save the setting.

Copy the templates into the same location as the Visual Studio installed templates that, for a typical installation, can be found in "Program Files\Microsoft Visual Studio 8\Common 7\IDE\Project Templates."
On the Windows Start menu open the Visual Studio 2005 Command Prompt.
Type devenv.exe /installvstemplates.
By placing the templates at this location and running the command line option, they will appear along side the Visual Studio shipped templates (such as Windows Application).

Community Search

Starter Kits and Templates can be downloaded through the integrated Community Search feature of Visual Studio, as well as from other Visual Studio community Web sites like dotnetjunkies.com.

Community Search can be accessed from within Visual Studio by using the Community, Community Search, Templates and Starter Kits menu option. When selected, the integrated help window opens directly to the search feature, allowing filtered searches for templates and starter kits by language, keyword, and location. Searches can be performed against MSDN Online or the Codezone Community.

Advanced Features

Starter Kits can be customized to fit many scenarios. Creating Starter Kits that contain multiple project templates and including a custom interactive wizard to guide the user during the Starter Kit project creation are examples of advanced customization features.

Creating Multi-Project Templates

Multi-project templates are similar to single project templates, except that when the user opens the project template from the New Project dialog window of Visual Studio it will create a new project for each of the project template included in the template zip file. For example, if a Starter Kit wanted to show an n-tier architecture it could contain a Windows Application project displaying data that is accessed through a Class Library project.

To create a multi-project template, first create each project individually in Visual Studio and export it into a project template (see the Creating a Project Template section). Once you have a project template for each project, associate them together into a single project template zip file by creating a .vstemplate file that includes a ProjectTemplateLink element pointing to the .vstemplate location of each project template included in the zip file.

Create a working directory c:\MultiTemplateExample where files can be temporarily stored.
Extract each project template zip file into a separate sub folder within the working directory. For example, if there are two project template files named Project1.zip and Project2.zip extract the contents into the following folder structure:

C:\MultiTemplateExample\Project1\*.*

C:\MultiTemplateExample\Project2\*.*
Create a text file in the C:\MultiTemplateExample directory named MyMultiTemplate.vstemplate.
Open the MyMultiTemplate.vstemplate file in a text editor.

Enter the following XML into the MyMultiTemplate.vstemplate file.

<VSTemplate Version="2.0.0"
xmlns="https://schemas.microsoft.com/developer/vstemplate/2005"
Type="ProjectGroup">
<TemplateData>
<Name>Multi-project</Name>
<Description>Two great templates.</Description>
<ProjectType>CSharp</ProjectType>
<ProjectSubType>
</ProjectSubType>
<SortOrder>1000</SortOrder>
<CreateNewFolder>true</CreateNewFolder>
<LocationField>Enabled</LocationField>
<EnableLocationBrowseButton>true</EnableLocationBrowseButton>
<Icon>__TemplateIcon.ico</Icon>
</TemplateData>
<TemplateContent>
<ProjectCollection>
<ProjectTemplateLink
ProjectName="Project1">
Project1\MyTemplate.vstemplate</ProjectTemplateLink>
<ProjectTemplateLink
ProjectName="Project2">
Project2\MyTemplate.vstemplate</ProjectTemplateLink>
</ProjectCollection>
</TemplateContent>
</VSTemplate>

Ensure the Type attribute of the VSTemplate element is set to ProjectGroup. This instructs Visual Studio to look for links to multiple projects for this template file instead of looking for a single project template.
Ensure the ProjectTemplateLink element values are pointing to the sub folder name of the project and the name of the .vstemplate file within those projects. This path should be entered as relative to the path where the multi-project template .vstemplate file resides (C:\MultiTemplateExample in this example).
Save the MyMultiTemplate.vstemplate file.
In Windows Explorer select the MyMultiTemplate.vstemplate file, Project1 folder, and Project2 folder in the C:\MultiTemplateExample directory.
Right click on the MyMultiTemplate.vstemplate file and select the Send To, Compressed (zipped) Folder menu option.
Copy the MyMultiTemplate.zip file to your "My Documents\Visual Studio 2005\Templates\ProjectTemplates" folder.
Open Visual Studio and look for the template named Multi-project in the New Project dialog window.

Note If the XML in the vstemplate file is invalid, your project will not appear in the New Project dialog window. If the template does not appear, check the Application Event Log for error information. Template errors will appear in the event log with the Source of "Visual Studio—VsTemplate."
Select the template and start a new project. Visual Studio will create a solution containing two new projects based on Project1 and Project2, which were included in the template.

Adding a Custom Wizard

Some templates may need to provide a more customized installation experience by allowing user interaction during the project template set up through a custom wizard. You can accomplish this by creating an assembly that the project template can reference directly. To implement a custom wizard create a signed assembly containing a class that implements the IWizard interface found in the Microsoft.VisualStudio.TemplateWizard namespace. You can create an installation wizard that can interact with the IDE directly to perform any actions necessary to the project properties or class files during the installation through the EnvDTE namespace.

This example demonstrates the creation of a custom wizard that will allow the user to specify the output directory path for the build configuration.

Creating an IWizard Class Library

Create a new Class Library project in Visual Studio named MyWizard through the New Project dialog window.
In the solution window right click on the References folder and select the Add Reference... menu option.
Select the EnvDTE, System.Windows.Forms, and Microsoft.VisualStudio.TemplateWizardInterface components in the Add Reference dialog window and click OK. See Figure 9.

Figure 9. Add Reference dialog window
In the Solution Explorer window right click on the project and select the Add, New Item... menu option.
Select to add a Windows Form from the Add New Item dialog window with the name Form1.cs.
Double click on Form1 in the solution window to open up the form in the designer.
From the Toolbox expand the Common Controls section and drag and drop a Label, Textbox, and Button onto Form1, as shown in Figure 10.

Figure 10. Sample custom wizard form
Using the properties window, change the Label1 Text property to Output Path.
Using the properties window change the Button1 Text property to Go.
On Form1 in the designer double click on Button1 to open the Form1.cs code file and create a button1_Click event handler.

Add the following code to create a public property on the form and set its value during the button1_Click event handler.

        public string OutputPath = string.Empty;
private void button1_Click(object sender, EventArgs e) {
OutputPath = textBox1.Text;
this.Close();
}

Now it is time to implement the IWizard interface. Double click on the Class1 file in the solution explorer to open the class file.
Add a reference to the namespace of the IWizard interface by adding a using statement at the top of the class file.
```
using Microsoft.VisualStudio.TemplateWizard;
```
Make Class1 implement the interface by changing the class declaration.
```
class Class1:Iwizard
```
Place the cursor on the IWizard word in the class declaration and right click and select the Implement Interface, Implement Interface menu option. Visual Studio will automatically create all of the required function declarations for the interface within the class.

Change the code within the class file to make Form1 appear at the beginning of the project template execution, prompting the user to enter the build output path for the project. Once the user has entered the information and closed the form, the project creation will continue. Upon the completion of creating a new project from the template, the ProjectFinishedGenerating method of Class1 will be called and will set the output path in the project properties using the EnvDTE IDE access.

using System;
using System.Collections.Generic;
using System.Text;
using Microsoft.VisualStudio.TemplateWizard;
namespace MyWizard {
class Class1:IWizard {
private string _outputPath = string.Empty;
#region IWizard Members
public void BeforeOpeningFile(EnvDTE.ProjectItem projectItem) {

}
public void ProjectFinishedGenerating(EnvDTE.Project project) {
EnvDTE.Property pt =
project.ConfigurationManager.ActiveConfiguration.Properties.Item(
"OutputPath");
if (pt != null) { pt.Value = _outputPath; }

}
public void ProjectItemFinishedGenerating(
EnvDTE.ProjectItem projectItem){}
public void RunFinished() {}
public void RunStarted(object automationObject, Dictionary<string,
string> replacementsDictionary, WizardRunKind runKind,
object[] customParams) {
Form1 userPrompt = new Form1();
userPrompt.ShowDialog();
_outputPath = userPrompt.OutputPath;
}
public bool ShouldAddProjectItem(string filePath) {
return true;
}
#endregion
}
}

In order for your IWizard library to run within Visual Studio it must be a signed component. Right click on the project and select the Properties menu option to open the project properties screen.
Click on the Signing tab.
Check the Sign the assembly box and select <New...> for the strong name key file.
In the Create Strong Name Key dialog window enter a key file name and password. Click OK to create the key.
Select the Build, Build Solution menu item to build the project.
Write down the public key token for the library by retrieving it using the sn command line tool; you'll need this later when referring to your component. Open the Visual Studio 2005 Command Prompt from the Start menu and type the command: sn -Tp "<assembly path>.

Replace <assembly path> with the fully qualified path of the MyWizard.dll assembly compiled in the previous step.

Install the Wizard Class Library

When a template references a wizard, Visual Studio looks for the custom class library in the GAC or the Visual Studio installation sub folder "Common 7\IDE" (which would be located at C:\Program Files\Microsoft Visual Studio 8\Common 7\IDE if you performed a standard installation). To install your class library for use as a custom wizard, copy the file to the GAC folder (C:\Windows\assembly) or the "Common 7\IDE" Visual Studio program sub folder.

Reference the Wizard Class Library

The project template must have a reference to your IWizard implementation. Adding this reference will allow Visual Studio to automatically load and execute the wizard whenever a user begins to create a new project based on that template.

Extract your project template zip file into a temporary folder named C:\WizardTemp.

Open the .vstemplate file in a text editor. After the TemplateContent section add a WizardExtension element as shown in the following code. In the Assembly element be sure to replace the PublicKeyToken with the token of your signed component.

<VSTemplate Version="2.0.0"
xmlns="https://schemas.microsoft.com/developer/vstemplate/2005"
Type="Project">
<TemplateData>
...
</TemplateData>
<TemplateContent>
...
</TemplateContent>
<WizardExtension>
<Assembly>MyWizard, Version=1.0.0.0, Culture=neutral,
PublicKeyToken=1f1ba71262185337</Assembly>
<FullClassName>MyWizard.Class1</FullClassName>
</WizardExtension>
</VSTemplate>

Save the modified .vstemplate file.
Create a new project template zip file with the updated files by navigating to the C:\WizardTemp folder in Windows Explorer. Select all the files by pressing CTRL-A and then right clicking and selecting the Send To, Compressed (zip) Folder menu option. Rename the zip file that is created to the name of the original zip file opened in step 1.
Copy the project template zip file to the "My Documents\Visual Studio 2005\Templates\ProjectTemplates" folder. When prompted to overwrite the existing file, answer 'Yes'.
Open Visual Studio and create a new project by opening the New Project dialog window.
Click on your template to create a new project from it.
Form1 will appear, prompting you to enter an output path for the project builds. Your wizard is now executing!

Conclusion

Starter Kits are a great way to increase the productivity of developers by providing a workable starting project including documentation and other sample material. With the advanced features of project templates it is possible to customize a Starter Kit to include multiple projects that demonstrate advanced implementation techniques. With the numerous community sites dedicated to helping Visual Studio 2005 developers improve their skills, there will be many helpful Starter Kits available to everyone.