Mere Mortals .NET Column - Customizing VS 2005 with New Item Templates
Visual Studio 2005 provides much easier mechanisms than previous version of
Visual Studio for extending the IDE. In this month's column I'm going to show
you how MM .NET uses new item templates in VS 2005 to provide better RAD capabilities. As always, this column contains valuable information even if you are
not an MM .NET user.
The Add New Item Dialog
If you have MM .NET installed on your machine, when you right-click a project and select Add | New Item... from the shortcut menu, MM .NET templates are displayed under My Templates at the
bottom of the Add New Item dialog: As you select each template a description of the template is displayed under the templates list and a default class name is displayed in the Name text box:
The following sections show you the steps it takes to display your own custom templates in this dialog.
Item Template Zip Files
When you install MM .NET on your computer, a set of zip files is installed in the following directories:
C:\Documents and Settings\Kevin\My Documents\Visual Studio 2005\Templates\ItemTemplates\Visual C#\1033
C:\Documents and Settings\Kevin\My Documents\Visual Studio 2005\Templates\ItemTemplates\Visual Basic\1033
Here is a screen shot of the C# template zip files:
When you launch the Add New Item dialog, Visual Studio searches this directory for zip files and examines their contents. Template zip files contain one .template file and one or more source code files. For example, the MMBusinessObject.zip file contains these files:
And the MMBusinessForm.zip file contains these files:
Visual Studio Template Files
Visual Studio .template files contain information that instructs Visual Studio how to display a template in the Add New Item dialog and what actions to perform when a new item is added to a project from the template.
For example, here is the contents of the MMBusinessObject.vstemplate file:
Specifying Display Information with the <TemplateData> Element
The <TemplateData> element contains information that tells Visual Studio how to display the template in the Add New Item dialog. Here is a rundown of its sub-elements:
||The name displayed under the template icon in the dialog
||The description displayed at the bottom of the dialog when the template is selected
||The icon displayed for the template in the dialog
||The type of project (CSharp, VisualBasic, etc.) the template is associated with
||A relative number that specifies the order in which the template is displayed in the dialog
||The default name of a new item created from the template. This is displayed in the Name text box of the dialog
Specifying Dependent Assemblies with the <References> Element
The <References> element (nested within the <TemplateContent> element) allows you to specify .NET assemblies that must be referenced in the project when a new item is added to the project from the template. This is an extremely useful feature of template files. For example, in the MMBusiness.template file shown above, the following assembly dependencies are specified:
- Mere Mortals Framework Interfaces
- Mere Mortals Framework
When Visual Studio adds a new business object to a project based on this template, it checks if the specified assemblies are already referenced in the project. If not, it automatically adds a reference to these assemblies for you.
Specifying Template Source Code Files with the <ProjectItem> Element
The <ProjectItem> element (nested within the <TemplateContent> element) specifies the source code files that are added to the project when a new item is added. There is one <ProjectItem> element for each source code file. For example, the MMBusiness.template file specifies a single source code file:
The MMBusinessForm.template file specifies two source code files:
This is because Windows Forms in VS 2005 are comprised of two partial classes by default.
Replacing Parameters in Template Source Code Files
Notice the <ProjectItem> elements shown in the previous section have a ReplaceParameters attribute that is set to "true". This tells Visual Studio to search the source code files for parameter tokens and replace them with specified values when adding the source code files to the project.
For example, here is the MMBusinessObject.cs template source code file:
The text strings contained within "$" signs are parameter tokens. In this example, the $rootnamespace$ and $safeitemrootname$ tokens are built-in parameters used by Visual Studio to indicate the project's default namespace (C#) or root namespace (VB .NET). When the source code file is added to the project, VS replaces this token with the specified namespace. The $safeitemrootname$ token is the name the user specified for the class in the Add New Item dialog. Again, Visual Studio replaces this token with the specified class name.
The other two tokens, $basefullname$ and $createbusinessrule$ are two custom parameters unique to MM .NET.
Specifying Custom Parameters in Template Files
The <CustomParameters> element (nested within the <TemplateContent> element) allows you to specify your own custom parameters in template source code files. For example, the MMBusiness.template file contains these custom parameter declarations:
The <CustomParameter> sub-element specifies the token for the custom parameter and the value to be inserted in place of the token when the source code file is added to the project. In this case, an empty string is used to replace the $createbusinessrule$ token, and the text "ABusinessObject" is used to replace the $basefullname$ token (this specifies the default base class of the new business object).
Templates In Action
To better understand how templates work, here is a step-by-step demonstration of adding a new item to a project:
- Right-click a project and select Add | New Item... from the shortcut menu.
- In the Add New Item dialog, select the MM .NET Business Object template:
Notice the description "MM .NET Business Object" is displayed beneath the templates box as specified in the <Description> element of the MMBusiness.template file. Also notice the default name of the class is BusinessObject1.cs which was specified by the <DefaultName> element.
- If you change the name of the class to Inventory.cs and click the Add button, here is the resulting source code added to the project:
Note the following:
- The $rootnamespace$ token has been replaced with the project's default namespace OakLeaf.MM.NorthwindSample
- The $safeitemrootname$ token has been replaced by Inventory (the name specified in the Add Item dialog)
- The $basefullname$ token has been replaced by ABusinessObject as specified in the template file.
- The $createbusinessrule$ token has been replaced by an empty string.
The approach Microsoft has taken for new item templates is much easier to understand and implement in Visual Studio 2005. By creating your own custom templates you can add RAD to your daily development tasks as well as encourage coding standards for your development team.