Indicates how the template was invoked. A value of
WizardRunKind.AsNewProject indicates that the template was invoked to create a new project. A value of
WizardRunKind.AsNewItem indicates that the template was invoked to create a new project item. The
runKind parameter allows a single wizard to be used in templates that create new projects as well as new project items.
customParams array was probably intended to contain any custom parameters defined by the template. Custom parameters are defined by the <CustomParameters> section in a .vstemplate file's <TemplateContent> section. Each custom parameter is defined using the <CustomParameter> tag, which takes the form:
<CustomParameter Name="parameterName" Value="parameterValue" />
However, custom parameters are added to the generic
Dictionary object available from the
replacementsDictionary parameter. The
customParams parameter can be safely ignored.
Custom parameters can be used, for example, to allow a single wizard that modifies code in a project to be used with both a Visual Basic and a C# template. The Visual Basic version of the template could include the following definition in its .vstemplate file:
<CustomParameter Name="language" Value="VisualBasic" />
The C# template could include the following definition:
<CustomParameter Name="language" Value="CSharp" />
The ShouldAddProjectItem Method
This method is called when a wizard is launched by a project item template before the item is added to a project. It is not called when a wizard is launched from a project template. The method has the following signature:
ShouldAddProjectItem(filePath As String) As Boolean
filePath is the name of the file to be added. Its path is included only if the file is to be added to a subdirectory of the project directory. The method should return True if the item is to be added to the project; otherwise, it should return False. If the method returns False, Visual Studio gracefully handles the failure to add the item.
The ProjectFinishedGenerating Method
This method is called when a wizard invoked by a project template has finished generating the project. (Its equivalent method for project item templates is the
ProjectItemFinishedGenerating method.) When the method is called, Visual Studio has already replaced all replaceable string parameters found in the project's source code with their values and has added all files defined by the template to the project. The method signature is:
ProjectFinishedGenerating(project As Project)
project is an
EnvDTE.Project interface object that provides access to the project.
The most common uses of this method are to add some additional files to or remove some existing files from the project, to add references to the project, or to modify the source code in the project. When the method is called, Visual Studio has already replaced all replaceable string parameters found in the item's source code with their values.
The ProjectItemFinishedGenerating Method
This method is called when a wizard invoked by a project item template has finished generating the item. (Its equivalent method for project templates is the
ProjectFinishedGenerating method.) The method is invoked only if the item is added to the project--that is, if the
ShouldAddProjectItem method returns True. Its signature is:
ProjectItemFinishedGenerating(ByVal projectItem As EnvDTE.ProjectItem)
projectItem is a reference to the item to be added to the project.
The BeforeOpeningFile Method
The presence of the OpenOrder attribute in the <ProjectItem> tag in a template's .vstemplate file determines whether or not that project item is to be opened in the Visual Studio environment once Visual Studio has finished generating the project. This method is called for wizards invoked by both project templates and by project item templates before Visual Studio actually opens each file. Its signature is:
BeforeOpeningFile(projectItem As ProjectItem)
projectItem is an
EnvDTE.ProjectItem interface object containing a reference to the project item that is about to be opened.
The RunFinished Method
This method is called to indicate that Visual Studio has finished processing the project or project item template. The method has no parameters.
The DTE and DTE2 Interface Objects
EnvDTE80.DTE2 object represents the Visual Studio application. It is derived from the DTE object, which represented the Visual Studio application in the initial release of Visual Studio .NET. The
RunStarted method passes a reference to the Visual Studio application object to wizards invoked from both project templates and project item templates. Access to the DTE2 object requires that you add references to the envdte.dl and EnvDTE80.dll assemblies.
The DTE2 object exposes much of the functionality of the Visual Studio design time environment, and therefore is the top-level object in a rather sizable object model. For wizard development, however, the following members of the DTE2 object are most important:
- LocaleID property: Returns an integer representing the locale in which the development environment is running. It can be useful in localizing template wizards.
- Solution property: Returns an
EnvDTE.Solutionobject that represents the current Visual Studio solution. If your code needs to manipulate child objects such as a Project object or a ProjectItem object before you've been passed a reference to it, you can retrieve it from the child objects of the Solution object. This is often the case, for instance, in a project item template that needs to make changes to other items in the project to integrate them with the new item.
- Quit method: Closes the current instance of Visual Studio.
The DTE2 object also includes a
GetThemeColor method, which takes a
vsThemeColors argument representing a particular user interface element and returns a
UInt32 value representing the color of that element. The method promises to make it possible to display a wizard's user interface in colors that are compatible with those used by Visual Studio. Unfortunately, however, the method appears to not be implemented in Visual Studio 2005. It returns the same value (0xFF000000) regardless of the
vsThemeColors value passed to it.