Tutorial : Creating Custom Project Template Wizards in Visual Studio .NET

The [!output SAFE_CLASS_NAME] would be replaced by the java script with a class name derived from the target name. Below is the code from the function AddFilesToCSharpProject in the common.js file that generates the class name.

Listing 2 Code from common.js that renders the template

if(!AddItemFile)
{
strTarget = GetCSharpTargetName(strName, strProjectName);
}
else
{
strTarget = wizard.FindSymbol("ITEM_NAME");
}
var fso;
fso = new ActiveXObject("Scripting.FileSystemObject");
var TemporaryFolder = 2;
var tfolder = fso.GetSpecialFolder(TemporaryFolder);var strTempFolder = fso.GetAbsolutePathName(tfolder.Path);
var strFile = strTempFolder + "\\" + fso.GetTempName();
var strClassName = strTarget.split(".");
wizard.AddSymbol("SAFE_CLASS_NAME", strClassName[0]);

In the code above, the target is first derived from the project name and then the class name is derived by stripping the file extension. Finally the class name is associated with the SAFE_CLASS_NAME keyword for rendering the template.

So now you get the idea of how the java script and the template works together in the default wizard. As we stated before, it's possible to bypass all of the java scripting and create the wizard completely in C#. The way to do this is simply to create our own automation object in .NET that inherits the IDTWizard dispatch interface. The IDTWizard is an interface with exactly one method, Execute. Overriding this method allows us to execute the wizard in any way you wish and passes in parameters that help us in accomplishing the task of wizarding the IDE. The steps to creating our wizard are simple. First create a simple dll library in .NET using the New->Project menu and choosing class library.

Figure 1 Choosing the project for the custom Wizard dll

In order to use the Windows Forms and EnvDTE assemblies, you will need to manually add these references. To add the references, right click on your solution in the solution explorer and choose Add Reference. Then find the references and add them to your project.

Figure 2 Choosing the references that are not already part of the library

Next, replace class1 with the following code. The class below implements the IDTWizard interface. Notice it contains a program dispatch id attribute above the class definition that allows the vsz file to recognize the wizard:

Listing 3 Class that implements the template wizard functionality

using System;
using EnvDTE;using System.Windows.Forms;
using System.Runtime.InteropServices;
namespace MyWizard1
{
/// <summary>
/// Summary description for Class1.
/// </summary>
[ProgId("VSWizard.VSCustomWizardEngine")]
public class Class1 : IDTWizard
{
public Class1()
{
//
// TODO: Add constructor logic here
//
}
public void Execute(object Application, int hwndOwner, ref object[] ContextParams, ref
bject[] CustomParams, ref EnvDTE.wizardResult retval)
{
_DTE IDEObject = (_DTE)Application;
WizardPage TheFirstPage = new WizardPage();
if (TheFirstPage.ShowDialog() == DialogResult.OK)
{
CreateProject(IDEObject, TheFirstPage.ProjectName,
TheFirstPage.DirectoryName);
}
}

After you build the project, youll also need to register the dispatch interface using egasm.exe so that the IDE can find the wizard through the vsz file. Simply run regasm.exe on your MyWizard1.dll assembly. Also, I noticed that the wizard dll assembly has to either be in the local path with the devenv.exe (the absolute path is C:\Program Files\Microsoft Visual Studio .NET\Common7\IDE\devenv.exe) or you need to make MyWizard1.dll a strong named assembly that is placed in the GAC(anotherwords a shared assembly). Otherwise the development environment has no clue where to find the wizard. (You would think it wouldnt matter since we registered it in the registry, but with .NET, what really gets registered by regasm is the mscoree.dll with the absolute name of the assembly and public key token). In the Visual Studio IDE, I changed the output path of my project to point to the IDE directory so the assembly is kept local and so I didn't have to keep copying the file all the time:

Figure 3 - Project Properties window with Output Path changed

Also the name of the wizard engine needs to be updated in the vsz file shown below:

VSWIZARD 7.0
Wizard=VSWizard.VSCustomWizardEngine
Param="WIZARD_NAME = CSharpCustomServiceWiz"
Param="WIZARD_UI = FALSE"
Param="PROJECT_TYPE = CSPROJ"

As we stated before, you'll also need to list the CSharpCustomServiceWiz in the vsdir file with the other CSharp Project Templates so the IDE can find the vsz file. You don't need scripts in this case, because all of the functionality is handled by the custom engine.

Thats all there is to plugging your Wizard into the framework. Now you can add any code you wish to the Execute method to create a project. You can use the Application object parameter passed into Execute to help build your project. The Application object is the root automation object of the IDE and can be unboxed with the extensibility (_DTE) class to be used to manipulate the environment.

For example: Say we wanted to create a solution from a solution project template and save it to the disk. Also we want to provide our own wizard interface and not the one provided by the VSWizard. Inside our wizard project, we can simply create a dialog based on a Window Form and then prompt for the information our wizard needs. Then well take advantage of the Extensibility interface to create our solution.

Our WizardPage dialog is created simply by adding a Windows Form to our Wizard Project. The Dialog is shown below:

Figure 4 - Custom Wizard User Interface Dialog

The dialog is a simple one that accepts the name of the project and the directory we wish to place the project solution. The directory input even comes with a browser button to pick a directory for our project This directory button actually invokes the SHBrowseForFolder in the shell32.dll API, but this is a topic for a completely new article, so we wont get into it here. Once weve gotten our input from the "Wizard", we can create the solution. The code for creating the solution is shown below:

Listing 4 - Extensibility code in C# to create a Project

public void CreateProject(_DTE IDEObject, string name, string destination)
{
// Create a new Solution Class
SolutionClass MySolution = new SolutionClass();
// Use the solution class to create a new solution
MySolution.Create(destination, name);
// Create the files for the solution by rendering them from an existing
// template
EnvDTE.Project theProject = MySolution.AddFromTemplate(@"C:\Program
Files\Microsoft Visual Studio .NET\VC#\VC#Wizards\DefaultDll.csproj",
destination, name, true);
// Get a reference to the Visual Studio Project and
// use it to add a reference to the XML assembly
VSProject myVSProject = (VSProject)theProject.Object;
References refmanager = myVSProject.References;
refmanager.Add("System.XML");
// Open a template C# File, render it and add it to the project
string templateFile = @"C:\Program Files\Microsoft Visual
Studio .NET\VC#\VC#Wizards\CSharpCustomServiceWiz\Templates\1033
MyWinServiceTemplate.cs";
string rendered1 = "MyServiceFile.cs";
// Our own home brewed rendering routine
string filename = RenderTemplate(templateFile, name, destination);
// Add the C# file to the project
EnvDTE.ProjectItem theItem = myVSProject.Project.ProjectItems.AddFromFile(filename);
// Save the project file
myVSProject.Project.Save(destination + "\\" + name + ".csproj");
// Save the solution file
MySolution.SaveAs(destination + "\\" + name + ".sln");
}

The code above steps create a solution by utilizing a method of the Solution class that creates files from a template and renders them from the name of the project passed into the method. It then adds a System.Xml assembly reference to the project and saves the project and the solution.

In our example, we bypass the template method provided by the wizard and created these files with our own rendering method. The way we do this is read the template into a file stream, use the replace routines of the string class to populate the template substitution values, and write the string back out to our new C# Class file. As you can see the .NET library and C# language give you a great deal of power and flexibility in how you create your wizards. Below is the code that renders the template in C#:

Listing 5 - C# Code used to render the template from a project name

public string RenderTemplate(string templateFile, string name, string destdir)
{
// Create the file stream for reading the template file
FileStream fs = new FileStream(templateFile, FileMode.Open, FileAccess.Read);
// Use a stream reader to read the file into a string
StreamReader sr = new StreamReader(fs);
string strFile = sr.ReadToEnd();
sr.Close();
fs.Close();
// Replace the template fields in the file with the appropriate values
strFile = strFile.Replace("[!output SAFE_NAMESPACE_NAME]", name);
strFile = strFile.Replace("[!output SAFE_CLASS_NAME]", name + "Class");
// Write the string back out to the new C# class file in our solution
FileStream fs2 = new FileStream(destdir + name + ".cs", FileMode.CreateNew,
fileAccess.Write);
StreamWriter sw = new StreamWriter(fs2);
sw.Write(strFile);
sw.Close();
fs2.Close();
return (destdir + name + ".cs");
}

Conclusion

One thing I had trouble doing was figuring out how to make the solution show up in the solution explorer after the project was created. If anybody figures out this one, shoot me an e-mail and I'll update the article. If after running the custom wizard, though, you go and open the project manually, you'll see the results show up in the solution explorer. The extensibility object has many good features for customizing your wizard. Some ideas may be to put special menu items in the IDE specific to your project or create your own project item wizards. It essence you can create project template wizards that not only customize the project itself, but the entire Visual Studio environment!