Walkthru:Extending Project Creation 

Glossary Item Box

Extending the Project Creation Wizard

For developers using Visual Studio Team System, the Team Explorer provides a tightly integrated mechanism for interacting with team resources stored on the Team Foundation Server for a given project. Within each Team Project, key resources, such as process documentation, work items, reports, build settings, and source control repositories are organized as defined by the Team Project's Process Template. Each time a new Team Project is created, a serialized version of the project is hydrated, or instantiated, from the chosen Process Template with the help of a Project Creation Wizard (commonly referred to as the PCW) that walks the project creator through a serious of configuration steps. Once all of the configuration information is collected, a new Team Project is created with the schema and resources defined in the Process Template – merged with any data gathered during the creation process.

Given the highly extensible nature of Process Templates, and the ability to add in new PCW plug-ins, Visual Studio Team System customers and partners may find it beneficial to integrate their own information gathering steps into the Project Creation Wizard. Information gathered during setup can then be easily communicated to customized Plug-ins, ensuring strong integration with core Team System components. In this way, for example, paths to external server resources can be specified for Plug-ins requiring connection information. Extensibility of this nature requires the use of a specialized type of VsPackage designed to extend the Team Explorer known as a TEPlugin.

TEPlugins make use of an interface designed to allow custom, deeply integrated, interaction with the Process Creation Wizard – including the injection of UI elements directly into the PCW sequence if desired. Because of their specialized nature, this walkthrough will guide you through the examination of an existing TEPlugin that ships with the VS SDK rather than attempting to guide you through the creation of your own plug-in – which would be beyond the scope of this Guided Tour.

To examine the sample plug-in:

1.  Locate the zipped files in the VS SDK. The typical path to these files will be in the following location:

C:\Program Files\Visual Studio 2005 SDK\<build>\VisualStudioTeamSystemIntegration\
     Team Explorer and Project Creation\

(Where <build> is the year and month of the build of the VS SDK that you currently have installed.)

2.  Once you locate the above directory, right click on the Team Explorer and Project Creation Sample.zip file and select Extract All , then click Next . Because the path to this example is so long (if left in the default directory), you'll need to extract the files to your Desktop (or you won't be able to compile the project due to compiler warnings about file names for associated assemblies being too long). To extract the files to your Desktop (or another suitable location) use the Browse button to locate a suitable path and click OK once your have selected a path. (Note that you'll likely want to create a new folder or the new files will just be unzipped directly to you Desktop or other chose destination.) Once you have specified an extraction location, click Next. Then click Finish to complete the extraction process.

3.  From the directory where you extracted the files, open the Sample Solution\PcwTESample folder, and then double click on the PcwTESample.sln file to open the Solution in Visual Studio.

Note that if you do not have Visual C++ installed you will receive a warning about the failure to load the PcwTESampleUI Project. If this is the case, you will be able to follow along with this walkthrough, though you will not be able to compile and experiment with the Plug-in once you have completed the walkthrough.

4.  Once the project is loaded, expand the References node for the PcwTESample Project in Solution Explorer.

A number of references to Microsoft.VisualStudio related assemblies are in place – to support the fact that this project will be deployed as a VsPackage. There are also references to core Microsoft.VisualStudio.TeamFoundation assemblies as well – to support the fact that this project represents a PCW Plug-in. Furthermore, because the project will integrate with an existing Wizard (the Process Creation Wizard), there is also a reference to the Microsoft.WizardFramework assembly.

5.  In Solution Explorer, double click on the VsPkg.cs file to open it in the editor.

6.  Scroll down to the definition for the main class in VsPkg.cs : HostPackage . Note that the class doesn't inherit Package, rather it inherits a subclass of Package : PluginHostPackage.

PluginHostPackages represent a specialized Subclass of Package (i.e. VsPackage) that provides an IProjectCreationPlugin interface exposed as a service. In fact, if you note the attributes above the class (lines 29 and 32 (in the above image)), you'll notice that this class exposes two services: one which is a Team Explorer Plugin (of type TEPlugin), and a PCW Plugin (SamplePcwPlugin). Note too, that as a best practice, this VsPackage is implemented as a Singleton.

7.  Scroll down into the HostPackage, and locate the override of OnCreateService(). In this method, the requested serviceType is evaluated, and returned as needed. If the requested serviceType is a TEPlugin, then a Team Explorer Plugin is returned (the code for the TEPlugin is located at the bottom of VsPkg.cs as well as a number of helper classes used to report hierarchical data in Team Explorer). Likewise, if the requested serviceType is a SamplePcwPlugin, then a new SamplePcwPlugin is returned.

8.  Scroll back up to lines 30 and 32 (or look at lines 30 and 33 in the image above) of VsPkg.cs. Note the PluginRegistrationAttributes – that they map a Plug-in name to its type in the VsPackage. Now locate the Sample Process Template folder in the directory where you unzipped the sample files. Open the folder and then open ProcessTemplate.xml in either Visual Studio or Notepad. Near the top of the file is a node for <plugins> – where the name of the Plug-in (matching the mapping name used in the PluginRegistrationAttribute in the VsPackage) is specified. This same name/type mapping allows Process Templates to provide a high degree of flexibility by providing a mechanism wherein custom logic and functionality can be added declaratively.

9.  In Solution Explorer, double click on PluginPcwSample.cs to open it in the editor. Press CTRL+M and then CTRL+O to collapse the file to definitions.

Note that there are two classes in this file, PluginSampleUploader and SamplePcwPlugin. It is in these two classes that the IProjectCreationPlugin interface is implemented. Two key members of the IProjectCreationPlugin are a single property, ComponentCreator, which returns an IProjectComponentCreator, and a method, GetWizardPage(), which returns an abstract class that is typically implemented as a User Control, which is the case in this sample as a new PluginSampleWizardPage instance is returned to satisfy this aspect of the interface. (You won't be able to view this class in the designer, but you will be able to view the code if you'd like – in PluginSampleWizardPage.cs.) During the creation of a new Team Project, the concrete TeamProjectWizardPage implementation will be used to display options and collect user input. Handling of the display and collected data is in turn handled by the PluginSampleUploader which exposes the following main methods as part of the IProjectComponentCreator interface: Initialize(), Execute(), CreateLink(), and Validate(). The Initialize() method is called when the PCW is first started, and allows the Plug-in to ensure that all private data is initialized as needed. It also allows the Plug-in to check user credentials, ensure that remote resources are available, or any other custom logic that should occur before the wizard is allowed to continue. Execute() is called when the wizard invokes the Plug-in and hands it an xml representation of the task to perform (from the Process Template). Take a few seconds to look at the code in these implementations. Note that Initialize() doesn't do anything in the current implementation. Note too that CreateLink() is also not used (this method allows for the handling of artifacts and their registration in the Link Manager). Finally, the Validate() method deserves special mention. Its purpose is NOT to validate user input during project creation – rather, its purpose is to validate the way in which the Plug-in has been applied to a Process Template when a new Process Template is uploaded to the Team Foundation Server. This allows the Plug-in to validate dependencies and ensure that required tasks have been properly defined in the calling Process Template.

10.  Attempt to compile the project. If you encounter build errors (excepting issues with the missing PcwTESampleUI project), locate the Sample Setup.htm file in the root of the directory where you extracted the compressed files and follow the instructions there to get the project to compile.

11.  After compiling the project, follow the instructions in Sample Setup.htm to deploy the project to Experimental Build (by pressing F5) and upload the accompanying custom Process Template. (Note that Experimental Build must be connected to a Team Foundation Server before the Team menu will be available for uploading the custom Process Template.)

12.  Once the Plug-in has been deployed to Experimental Build, and the Sample Process Template has been uploaded as per the instructions in Sample Setup.htm, create a new Team Project with the Project Creation Wizard Plugin Sample Process Template to see the PCW Plug-in in action.