Templates for New Projects and New Items

Another way to increase productivity with Visual Basic .NET

Office worker using computer
Image Source/Image Source/Getty Images

What's a Template?

When you start a new project in VB.NET, you have to select the type of project such as Windows Application or Class Library. These are templates. In addition, when you add a new item to your project (from the Project menu, select Add New Item) you select from item templates.

But wouldn't it be nice if you could use a template that already has a few of your own tweaks in it? If there are local standards, special requirements, or just programming styles that you like to use, you can start out with part of your work already done by creating a custom template.

(This works in both Visual Studio 2005 and VB.NET Express!)

Before we go any further, let me make it clear that this is not the same thing as something Microsoft is trying to sell called "Enterprise Templates". That is a high level architecture concept that Microsoft claims will allow you to organize and control "distributed applications with multiple projects." About Visual Basic is focused on down-to-earth programming.

In addition, none of this was available in Visual Studio 2003. Templates actually were available (after all, New Project still worked the same way), but were undocumented and Export Template didn't exist. So you could do it only if you were willing to blaze your own way in an uncharted software wilderness.

But in 2005, the basic operation to create your own template became about as simple as it could be!

  1. Create a project with the modifications you want to use
  2. Select Export Template from the File menu
  1. Click Next then Finish to generate the template
    (And to accept the defaults.)
  2. You're good to go with your new template!

The screen below shows how the process looks.

Click Here to display the illustration
Click the Back button on your browser to return

If the screens look funny to you, I used Windows Vista for this example.

Visual Studio 2005 (but curiously, not VB.NET 2005 Express) requires a special update before it will run on Windows Vista and the file locations can be significantly different. Here's where the template, testtest can be found in Windows XP after being generated by VB.NET 2005 Express:

Click Here to display the illustration
Click the Back button on your browser to return

This is important because, for some reason, a lot of the books out there don't seem to even be aware of the existance of the Export Template wizard. (John Paul Mueller's Mastering Web Development book, for example.)

Doing it this way can get mighty complicated fast, especially since even the instructions at MSDN don't seem to track what you will see on your own computer much of the time. So if at all possible, I'd stick with the wizard. My experience is that the VB.NET development software - VB.NET Express and Visual Studio 2005 - are updated better than the documentation and you're less likely to run into problems that way. For example, MSDN states that if you manually create templates instead of using the wizard, you should place them in:

My Documents\Visual Studio 2005\Templates\ProjectTemplates

The My Documents folder has a new name in Vista.

(See the first illustration above.) And Mueller's book tells you to put them in a subdirectory of the Program Files > Visual Studio 8 > ProjectTemplatesCache directory. (It's a long path ... I left a lot out.) A coder could get confused!

However ...

The heart of the process of creating a template manually boils down to three basic steps. (After you design what you want your template to do. This is just the process of actually creating it.)

  1. Assemble the files that are necessary for your template in one folder.
  2. Code a .vstemplate XML file that describes the template.
  3. Zip the files together (including the .vstemplate file) and copy the Zip file to the Visual Studio project template directory.

Generating a template using the wizard is easy, but there are a few more options available too. The next page tells you about them.

article illustrations © Dan Mabbutt

To get started, check out a wizard generated .vstemplate file. If you have been following along and you have generated the template on your own system, double-clicking the file should open it in Visual Studio or IE. You'll see that this, like so many of the data files in .NET, is an XML file. Here's the top level:

<VSTemplate Version="2.0.0"
    < ... >
    < ... >

The TemplateData element contains sub-elements like Name, Description and ProjectType. The TemplateContent element contains sub-elements for the actual files, like the .vbproj file, that will be the basis of your new project. In the wizard generated template, you will notice that the "target" files are named the same as the actual files like this:

<ProjectItem ... TargetFileName="Form1.vb">Form1.vb</ProjectItem>

This gives you the flexibility of using files with other names in your template. For example, your project might have a naming convention so that a Form is named ProjXYZFm123. You can include that in a template for a new project without renaming anything.

More flexibility is available with the ability to actually change the content of the VB code itself using parameters in the .vstemplate files. For example, you can embed a statement like this in your VB code before generating the template.

MsgBox("Project name passed as parameter: " _
   & "$safeprojectname$")

When a new project is created using that template, the code in the project will look like this:

MsgBox("Project name passed as parameter: " _
   & "ParmTest1")

Note that when the wizard processes $safeprojectname$, the name with a "1" appended that you're used to seeing as project names in Visual Studio is generated.

It will remove blanks and any other illegal characters too.

The illustration below shows parameters in action.

Click Here to display the illustration
Click the Back button on your browser to return

When you used the Export Template wizard to create a project template, you probably noticed that another options was available to create an item template. These are simply the items that you can select from when you select Add New Item... under the project menu. The process of creating item templates are about the same as the process for project templates except that you also have to select the parts of the project that will be in the item and any references that your item depends on.

Microsoft also includes something they call Starter Kits into this category of tools. But as they candidly state:

"Visual Studio templates and Starter Kits are built and used in almost exactly the same way. A distinction is made between Starter Kits and a templates to provide a level of expectation to someone downloading and using them."

But then they say, "Several key features are required to separate a Starter Kit from a template."

I added the bolding on the word "required". How are these "key features" required?

The answer is, they're not. It's just a marketing thing. Don't worry about it.

This article will get you started making your own templates. The key information that is missing is the exact definitions of the XML elements that are used in the .vstemplate file. Unlike some books which fill chapters with detailed (and sometimes out of date) information that you can get online, I recommend that you get what you need online at MSDN. Use the search key "Visual Studio Template Schema" and the hints in part II of the Visual Basic .NET 2005 Express tutorial.

article illustrations © Dan Mabbutt