Adding Magic to New Projects with the VSX Template Wizard
While I blog about Visual Studio Extensions all the time, I don't cover Project and Item templates much. Why? Well they just don't seem as exciting or cool as Extensions, I guess. Every day we Click-New Item-... or Click-New Project... and pow, we have a new class or project. Quick, simple, easy, and while a huge time saver, just not all that exciting.
What if you want to spice those new Projects or Items up? Say, include a wizard? Well that's not easy.
At least it was until Ed Dore released his great VSX Project Wizard code and tutorial!
Over the years, I’ve built more than a few project templates with wizard support. Usually for experimental purposes to help answer customer inquiries concerning templates and wizards. Lately, I’ve found myself regularly following steps similar to what I outlined in my previous blog entry:
When you find yourself doing something often enough, you just may find yourself motivated enough to automate things a bit. So without further ado, I’d like to present: The VSX Template Wizard.
Currently, this particular VSIX package doesn’t reside in the Visual Studio Extension Gallery, due to a limitation which prevents us from uploading .VSIX files with multiple .zip files to the gallery. This is a gallery limitation that the Visual Studio team is hoping to address in the not to distant future. Until then, the .VSIX will simply reside here, with the source published as a sample at: Custom Templates and Wizard to create VSIX Deployable Template with Wizard package
When installed, you will find a couple of new project templates, installed under the C#\Extensibility node of your New Project dialog. these new templates will allow you to easily create a VSIX Deployable Project (or Item) Template, with a custom IWizard implementation. The results of which, bear a striking resemblance to the afore mentioned walkthrough.
This VSIX was built with and targets VS 2013. I’ve published the source, to serve primarily as a sample. But in the event someone wants to build a similar VSIX for earlier versions of VS, the sample source may also serve as a template for that effort. The projects that these particular templates create, leverage the VSSDK, so that also needs to be installed.
Finally, you need to install the VSX Template Wizard.
Using the Template
1. Open the New Project Dialog, then find and select one of the new templates
The Implementation Details:
Creating a project template that creates another project template, can be hard to get your head around. The VSXTempateWizard solution includes the following 4 projects:
- VSXItemTemplate – this project creates the VSXItemTemplate.zip, which creates a simple C# Item Template project.
- VSXProjectTemplate – this project creates the VSXProjectTemplate.zip, which creates a simple C# Project Template project.
- VSXWizardTemplate – this project creates the VSXWizardTemplate.zip, which creates the wizard assembly and VSIX Package.
- VSXTemplateWizard – this is the IWizard used by the VSXItemTemplate, VSXProjectTemplate and VSXWizardTemplate to glue everything together.
A Multi-Project Template that isn’t
The first thing you may notice, is that none of these templates are actually multi-project templates. Yet, when you create a new “Item Template with Wizard” project, or “Project Template with Wizard” project, you get a solution containing 2 projects as shown above. Hence, what we have here is a Multi-Project Template that isn’t a multi-project template.
One of the more frustrating limitations of the Multi-Project Template, is that you have almost no control over where its various projects are created, or how they get named. However, it’s entirely possible to seize control of this, if you designate one project to be the “primary” project, and implement an IWizard to add the additional projects after the first is generated. This is exactly what the VSXTemplateWizard does. The “trick” is to mark the subordinate projects as hidden (so they don’t show up in the New Project or New Item dialog). Then call Solution2.AddFromTemplate after the “primary” project has been completely generated (from the IWizard.ProjectFinishedGenerating method). See the VSXTemplateWizard.ProjectFinishedGenerating method in the VSXTemplateWizard.cs in the accompanying sample, for an example of this.
While examining the ProjectFinishedGenerating method also note of the usage of the VSLangProj.VSProject and EnvDTE.Configuration interfaces to change up the debugger settings for the wizard project. The resulting template and wizard projects are configured to run in the Experimental Instance of the IDE, so as to avoid mucking up your actual production environment.
I’ll be the first to admit the VSXTemplateWizard is a bit convoluted, but it’s used by all 3 of the templates, and I shamefully use a few static variables to store key info, to be used when the wizard is invoked a 2nd time when adding the VSXWizardTemplate project. Hence the checks for which .vstemplate invoked the wizard in the RunStarted method, and the conditional setting of various flags and replacement tokens.
That multi-project segment seems familiar, like we've covered that before? Yep! Project, project, project, creating multi-project Solutions
Here's the code behind the tutorial...
This is the source code that accompanies the VSX Arcana blog entry entitled "The VSX Template Wizard" . This sample is a solution containing several project templates, and a custom IWizard assembly, that produces a .VSIX that when installed, will give you a couple of Project Templates that you can use to jump start the creation of your own custom project or item template, with an associated custom IWizard assembly implementation, that is automatically built into a .VSIX file you can use for deployment.
Building the Sample
The VSX Template Wizard solution is make up of the following 4 projects.
- VSXItemTemplate - creates the VSXItemTemplate.zip, which creates a simple C# Item Template project
- VSXProjectTemplate - creates the VSXProjectTemplate.zip, which creates a simple C# Project Template project
- VSXWizardTemplate - creates the VSXWizardTemplate.zip, which creates the wizard assembly and .VSIX package
- VSXTemplateWizard - used by the VSXItemTemplate and VSXProjectTemplate to glue everything together
This project illustrates the following concepts:
- How to create a Project Template, that creates a Project Template project
- How to create a new key.snk file, with the ICLRStrongName interface
- How to add a 2nd project to the solution programmatically, by invoking Solution2.AddFromTemplate
For additional information, please refer to the following two blog entries: