Beta 1 and the new Template Wizard

As you probably know by now from the abundant number of postings on the issue, VS 2005 beta 1 and the Express editions are now available. A few months ago, when we released the PD5 build of VS, the Add-in wizard had a listing of about 8 different applications that you could build Add-ins for; these included all the Express IDEs. We got a lot of questions about what Express meant, and since it was not an announced product yet, we had to side step the issue. Now you know.

 

Beta 1 also has a few new items that we are now talking about. One of these is what we are calling VSTemplates. Previously, when you needed to create a new project you had two options. The first way was to copy the project into a special directory, then an item would appear in the New Project dialog box. The user would then select the item and the project would be copied into the destination directory, and loaded into VS. This would not be ideal because the source files would not be modified to rename the main class to match the name of the project – in other words, there would be no token replacement on the files, they would just be copied into the destination directory and opened. The second way of creating new projects would be to write a wizard. You would create a component that implements IDTWizard, create a .vsz file that would point to that component, and then put the .vsz file in the correct directory. When the user selected your .vsz file in the New Project dialog box, your wizard would be invoked. Your wizard could then do whatever it wanted to fix up the project templates (such as parameter replacements), then import it into the solution. But writing wizards like this are a real pain, they can be tedious to write, and hard to get right.

 

For this version of VS we have the VS Template Wizard. First you create a project that serves as your templates. Next, you create an XML file with the extension .vstemplate. The New Project dialog box can read the .vstemplate file and do all the work of generating a project for you. It will open the .vstemplate file, read in the list of files that are contained within the project, search for special tokens in the files and replace them with values meaningful to that project, then load the project into the solution. For example, suppose you entered the project name “MyProject” into the New Project dialog box. When you try to open a template from the New Project dialog box, the wizard will automatically open the files, look for the string “$projectname$”, and replace it with the text MyProject – and you did not need to write a bit of code.

 

That does not mean you cannot write code to customize the template wizard. Suppose you have a standard that you want to name everything with lower case, thus the value $projectname$ will be replaced with myproject, or you have a token in your template that you want to replace (put “

123 Main St

.

” in place of $myaddress$). You can do this by creating a wizard component. Think of a wizard component as an Add-in for a wizard. When a certain tag is found in the .vstemplate XML, we will load a component that you specify and call methods on that component giving you a chance to do custom work. For example, to add the $myaddress$ token, you would write code like this:

 

public class MyWizardComponent : IWizard

{

      void RunStarted(object automationObject,

                        System.Collections.Generic.Dictionary<string, string> replacementsDictionary,

      WizardRunKind runKind,

      object[] customParams)

      {

            replacementsDictionary.Add("$myaddress$", "

123 Main St

.");

      }

      //Other methods of the IWizard interface go here.

}

Not only does this mechanism work for new projects, but also new project items also. Need to add file(s) to a project such as a custom form which consists of, for example, the files Form.cs, Form.designer.cs, and Form.resx and do modifications on those files? You can set up a .vstemplate to import those files into your project.

 

Packaging up your templates is also easy. Put the files into a .zip file, put them on disk (in the install path to make them available to anybody or in the ProjectTemplates/ItemTemplates folders buried in …\My Documents\Visual Studio, and they will appear in the appropriate dialog box. Need to quickly generate a .vstemplate file and the project? No problem, in the next beta we should have a wizard that will package up a project for you.

 

If you would like some examples of how this works, most of the wizards in VS Beta 1 are written using the new vstemplate format. Search your disk for *.vstemplate files to see how to get started.