Extending Visual Studio Part 3 - Item Templates

Building the Template Itself 

Building the template itself is dead easy - you just use a few of the predefined tokens with dollar signs around them. Here's what the ViewModel.cs template looks like: 

using System;
using System.Collections.Generic;
$if$ ($targetframeworkversion$ >= 3.5)using System.Linq;
$endif$using System.Text;
using System.ComponentModel;

namespace $rootnamespace$
{
    /// <summary>
    /// The $safeitemrootname$ class.
    /// </summary>
    public class $safeitemrootname$ : INotifyPropertyChanged
    {
        /// <summary>
        /// Occurs when a property value changes.
        /// </summary>
        public event PropertyChangedEventHandler PropertyChanged;

        /// <summary>
        /// Notifies the property changed.
        /// </summary>
        /// <param name="propertyName">Name of the property.</param>
        private void NotifyPropertyChanged(string propertyName)
        {
            //  Get and fire the event.
            var theEvent = PropertyChanged;
            if (theEvent != null)
                theEvent(this, new PropertyChangedEventArgs(propertyName));
        }
    }
}

Sheesh it's a bit ugly with those odd looking tokens everywhere but you can see what's happening - $rootnamespace$ is (you guessed it) the root namespace of the destination project, $safeitemroot$ is the file name they've chosen, with things like spaces removed. 

That's all there is to it! We have the item template ready to go. The next thing to do is to create a VSIX package which will contain the template. We can also use this as a way to test and debug it.

Creating the VSIX Package

In the solution, add a new project called 'ViewModelTemplateVsix' with the type as VSIX project.

Double click on the 'source.extension.vsixmanifest' file. Here you can edit data about the package itself. We'll set a better title and some descriptions, as below:

Now we can press 'Add Content' to include our Item Template:

Now that we've done this make sure the VSIX package is the startup project and hit F5. This will start the Experimental Instance of Visual Studio which is where we can test and debug the extension. Create a new C# Class Library project and then choose 'Add New Item...' our new ViewModel item template is listed - choose 'Example' as the file name and add the item. 

Now this is most impressive - we have got a new class with the correct name that implements INotifyPropertyChanged! Here's the newly generated class:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.ComponentModel;

namespace ClassLibrary2
{
  /// <summary>
  /// The Example class.
  /// </summary>
  public class Example : INotifyPropertyChanged
  {
    /// <summary>
    /// Occurs when a property value changes.
    /// </summary>
    public event PropertyChangedEventHandler PropertyChanged;

    /// <summary>
    /// Notifies the property changed.
    /// </summary>
    /// <param name="propertyName">Name of the property.</param>
    private void NotifyPropertyChanged(string propertyName)
    {
      //  Get and fire the event.
      var theEvent = PropertyChanged;
      if (theEvent != null)
        theEvent(this, new PropertyChangedEventArgs(propertyName));
    }
  }
}

Congratulations! At this stage you now know how to build a basic item template. If this is all you need then you're good to go. In the next part of this article we'll look at how we can include a Wizard for the Item Template that'll let us configure some options about how to create it.

Creating a Wizard for the Template

In many cases, if you're creating an Item Template it's for something a bit more specific and specialised. You may not just want to create a new item with a certain layout, but also allow the user to specify some options. In this case you need to include a Wizard for the Item Template. 'Wizard' is a bit of a misleading name perhaps, all we are in fact going to do is show a single dialog with some options.

I use WPF for my Wizards nowadays but to keep things simple we'll use WinForms. Add a new Windows Forms Control Library to the project, and call it 'ViewModelWizard'. 

Add a new form to the library and call it NewViewModelForm. We're going to allow the user to optionally include a notifying property with a specified type and name. Lay out the form as below:

I'm not going to go into the details of how the form works, it's very simple - it just exposes the 'Include Example' as a boolean property as well as the Example Name and Example Type as strings. We now need to actually create the Wizard class. Add a new class to the project called 'ViewModelWizard'. At this stage also add references to:

• ENVDTE 
• Microsoft.VisualStudio.TemplateWizardInterface

As below:

The Wizard class must implement 'IWizard'. Right click on the 'IWizard' line and choose 'Implement Interface'. You're class should now look like this:

public class ViewModelWizard : IWizard
    {
        public void BeforeOpeningFile(EnvDTE.ProjectItem projectItem)
        {
            throw new NotImplementedException();
        }

        public void ProjectFinishedGenerating(EnvDTE.Project project)
        {
            throw new NotImplementedException();
        }

        public void ProjectItemFinishedGenerating(EnvDTE.ProjectItem projectItem)
        {
            throw new NotImplementedException();
        }

        public void RunFinished()
        {
            throw new NotImplementedException();
        }

        public void RunStarted(object automationObject, 
            Dictionary<string, string> replacementsDictionary, WizardRunKind runKind, object[] customParams)
        {
            throw new NotImplementedException();
        }

        public bool ShouldAddProjectItem(string filePath)
        {
            throw new NotImplementedException();
        }
    }

The only function we care about is 'RunStarted' - in this function we'll show the form and add the values specified to the 'replacementsDictionary'. This will let us use the tokens in our template. Update the class to look like this:

public class ViewModelWizard : IWizard
    {
        public void BeforeOpeningFile(EnvDTE.ProjectItem projectItem)
        {
        }

        public void ProjectFinishedGenerating(EnvDTE.Project project)
        {
        }

        public void ProjectItemFinishedGenerating(EnvDTE.ProjectItem projectItem)
        {
        }

        public void RunFinished()
        {
        }

        public void RunStarted(object automationObject, 
            Dictionary<string, string> replacementsDictionary, WizardRunKind runKind, object[] customParams)
        {
            //  Create the form.
            var form = new NewViewModelForm();

            //  Show the form.
            form.ShowDialog();

            //  Add the options to the replacementsDictionary.
            replacementsDictionary.Add("$IncludeExample$", form.IncludeExample ? "1" : "0");
            replacementsDictionary.Add("$PropertyName$", form.PropertyName);
            replacementsDictionary.Add("$PropertyType$", form.PropertyType);
        }

        public bool ShouldAddProjectItem(string filePath)
        {
            return true;
        }
    }

You can see that all we're doing is showing the form and adding the options into the replacements dictionary. The dictionary can only contain strings - so use "1" or "0" for booleans!

Now we can update the actual template (ViewModel.cs) itself, to use these tokens. We'll set up a conditional block based on $IncludeExample$ that will add a property of name $PropertyName$ and type $PropertyType$ that uses NotifyPropertyChanged. Update ViewModel.cs to the below:

using System;
using System.Collections.Generic;
$if$ ($targetframeworkversion$ >= 3.5)using System.Linq;
$endif$using System.Text;
using System.ComponentModel;

namespace $rootnamespace$
{
    /// <summary>
    /// The $safeitemrootname$ class.
    /// </summary>
    public class $safeitemrootname$ : INotifyPropertyChanged
    {
        /// <summary>
        /// Occurs when a property value changes.
        /// </summary>
        public event PropertyChangedEventHandler PropertyChanged;

        /// <summary>
        /// Notifies the property changed.
        /// </summary>
        /// <param name="propertyName">Name of the property.</param>
        private void NotifyPropertyChanged(string propertyName)
        {
            //  Get and fire the event.
            var theEvent = PropertyChanged;
            if (theEvent != null)
                theEvent(this, new PropertyChangedEventArgs(propertyName));
        } $if$ ($IncludeExample$ == 1)

        /// <summary>
        /// The value of $PropertyName$.
        /// </summary>
        private $PropertyType$ $PropertyName$Value;

        /// <summary>
        /// Gets or sets $PropertyName$.
        /// </summary>
        public $PropertyType$ $PropertyName$
        {
            get { return $PropertyName$; }
            set
            {
                if( $PropertyName$Value != value)
                {
                    $PropertyName$Value = value;
                    NotifyPropertyChanged($PropertyName$);
                }
            }
        } $endif$
    }
}

Before we can test this we need to do three things - sign the Wizard assembly, install the Wizard assembly in the GAC, then update the Item Template to use the Wizard.

To sign the assembly, open the Wizard project settings, choose Signing, check 'Sign the Assembly' and enter a new key - no password is necessary.

To install the assembly into the GAC, add the following to the post build steps of the Wizard project:

32 bit Machine:
"C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools\gacutil" /if "$(TargetPath)"
"C:\Program Files\Microsoft SDKs\Windows\v7.0A\bin\sn" -T "$(TargetPath)"

64 bit Machine:
"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\bin\NETFX 4.0 Tools\gacutil" /if "$(TargetPath)"
"C:\Program Files (x86)\Microsoft SDKs\Windows\v7.0A\bin\sn" -T "$(TargetPath)"

This just build the project. The post build step will install the wizard to the GAC and show the strong name token:

Assembly successfully added to the cache
  
  Microsoft (R) .NET Framework Strong Name Utility  Version 3.5.30729.1
  Copyright (c) Microsoft Corporation.  All rights reserved.
  
  Public key token is e0700af0fcefc5c7

We'll need this token to do the final part of the project. Open the ViewModelItemTemplate.vsitemtemplate file and after the closing tag of TemplateContent add:

<!-- Use the appropriate IWizard from the ViewModelWizard assembly. -->
  <WizardExtension>
    <Assembly>
      ViewModelWizard, Version=1.0.0.0, Culture=neutral, PublicKeyToken=e0700af0fcefc5c7
    </Assembly>
    <FullClassName>ViewModelWizard.ViewModelWizard</FullClassName>
  </WizardExtension>

Don't forget to use the correct public key token (highlighted in bold).

Now press F5. Add a new View Model to a class library - we get the user interface we created when we add it and can specify an example property:

and we get the result below:

using System.ComponentModel;

namespace ClassLibrary2
{
  /// <summary>
  /// The Example class.
  /// </summary>
  public class Example : INotifyPropertyChanged
  {
    /// <summary>
    /// Occurs when a property value changes.
    /// </summary>
    public event PropertyChangedEventHandler PropertyChanged;

    /// <summary>
    /// Notifies the property changed.
    /// </summary>
    /// <param name="propertyName">Name of the property.</param>
    private void NotifyPropertyChanged(string propertyName)
    {
      //  Get and fire the event.
      var theEvent = PropertyChanged;
      if (theEvent != null)
        theEvent(this, new PropertyChangedEventArgs(propertyName));
    }

    /// <summary>
    /// The value of FirstName.
    /// </summary>
    private string FirstNameValue;

    /// <summary>
    /// Gets or sets FirstName.
    /// </summary>
    public string FirstName
    {
      get { return FirstName; }
      set
      {
        if (FirstNameValue != value)
        {
          FirstNameValue = value;
          NotifyPropertyChanged(FirstName);
        }
      }
    }
  }
}

Final Thoughts 

I hope you've enjoyed this article - please feel free to comment on ideas, problems or potentially improvements!