VSX Arcana

Creating a VSIX Deployable C++ project template.

Ed Dore — Thu, 04 Jan 2018 22:21:43 GMT

The problem:

Recently I had a customer inquire about an issue they had encountered with a custom C++ project template they had created. Using a vstemplate based project template, they were able to successfully create a C++ project, but noticed a discrepancy in the project’s General Property Page. Specifically, the “Target Platform”, and “Windows SDK Version” settings appeared to be incorrect. For example: Whereas, if they created a new C++ DLL project using the standard DLL template that comes with Visual Studio: The resulting projects “Target Platform” and “Windows SDK Version” were set to: Typically, whenever I see issues like these, the first thing I do is compare the .vcxproj files to see what might be different. And sure enough, the .vcxproj generated by the standard template included the following:

  <PropertyGroup Label="Globals">
    <VCProjectVersion>15.0VCProjectVersion>
    <ProjectGuid>{C56BA256-602E-4F31-AC6D-8453D7BFBCB3}ProjectGuid>
    <Keyword>Win32ProjKeyword>
    <RootNamespace>MyStandardDLLProjectRootNamespace>
    <WindowsTargetPlatformVersion>10.0.16299.0WindowsTargetPlatformVersion>
  PropertyGroup>

To confirm, I removed the above tag from the .vcxproj, reloaded the project, and observed, the “Target Platform” and “Windows SDK Version” settings changed to “Windows” and “8.1” respectively. So it was pretty obvious the culprit was a missing entry in the .vcxproj. But upon examining the .vcxproj files used by various VC++ templates (located under the C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\VC\VCWizards directory), none of these .vcxproj files contained a entry.

So it was pretty safe to assume this entry was programmatically added after the fact. Searching the files under “C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\VC\VCWizards” for “WindowsTargetPlatformVersion” quickly revealed the StampWindowsTargetPlatformVersion method in the “C:\Program Files (x86)\Microsoft Visual Studio\2017\Enterprise\Common7\IDE\VC\VCWizards\1033\common.js” file:

function StampWindowsTargetPlatformVersion(oProj)
{     
   var strLatestWindowsSDKVersion = GetLatestWindowsSDKVersion(oProj);
   if (strLatestWindowsSDKVersion)
   {
      //Stamp the latest Windows SDK version found in the disk - It is a global property, so enough to do it for any one config
      var commonConfigRule = oProj.Object.Configurations(1).Rules("ConfigurationGeneral");
      commonConfigRule.SetPropertyValue("WindowsTargetPlatformVersion", strLatestWindowsSDKVersion);
   }
}

And subsequently, the GetLatestWindowsSDKVersion method:

function GetLatestWindowsSDKVersion(oProj)
{     
   return oProj.Object.LatestTargetPlatformVersion;
}

The solution:

Given that we want to use .VSIX deployment and consequently a .vstemplate based template, it’s fairly obvious we’ll need to implement and associate a custom IWizard implementation to the template. To set the WindowsTargetPlatformVersion property, you can use the VCProject.LatestTargetPlatformVersion property, and the IVCRulePropertyStorage.SetPropertyValue method in an IWizard.ProjectFinishedGenerating method similar to the following:

public void ProjectFinishedGenerating(Project project)
{
   // use VCProject.LatestTargetPlatformVersion property, which is what the stock wizards use.    
   VCProject vcProject = (VCProject)project.Object;    
   string wtpv = vcProject.LatestTargetPlatformVersion;    
   if (wtpv != null)    
   {
      // we only have to do this for a single config, as the property in question is global.
      IVCCollection configs = (IVCCollection)vcProject.Configurations;
      VCConfiguration firstConfig = (VCConfiguration)configs.Item(1);
      IVCRulePropertyStorage rule = (IVCRulePropertyStorage)firstConfig.Rules.Item("ConfigurationGeneral");
      rule?.SetPropertyValue("WindowsTargetPlatformVersion", wtpv);
   }
}

The final issue that needed to be addressed was a missing .vcxproj.filters file. The project template contained a SimpleDLL.vcxproj.filters file, which was also referenced as a ProjectItem in the templates .vstemplate manifest. And while I could see the SimpleDLL.vcxproj.filters file was included in the .VSIX, it wasn’t showing up along side the SimpleDLL.vcxproj. This is due to a limitation of the IDE’s project template wizard implementation. Files included via the projects’ .vstemplate manifest are copied to a temp directory when the template is first unpacked, but only the files referenced by the project file are then copied to the final destination directory. Because .vcxproj.filters files aren’t referenced in the .vcxproj file, these will need to be programmatically copied from the temp directory, to the final destination directory. And given we already have a custom IWizard to handle setting the WindowsTargetPlatformVersion, this can be easily added to IWizard.RunStarted method similar to the following:

public void RunStarted(object automationObject, Dictionary<string, string> replacementsDictionary, WizardRunKind runKind, object[] customParams)
{
   _dte = (DTE)automationObject;

   // manually copy over the SimpleDLL.vcxproj.filters file because it isn't
   // referenced by the .vcxproj, and the wizard engine doesn't copy it to
   // the project's destination directory.

   // note, customParams[0] is the full path to the .vstemplate file, so we'll
   // use it's folder to find the needed SimpleDLL.vcxproj.filters file.
   string sourceFile = Path.Combine(Path.GetDirectoryName((string)customParams[0]), "SimpleDll.vcxproj.filters");
   string destFile = Path.Combine(replacementsDictionary["$destinationdirectory$"], string.Format("{0}.vcxproj.filters", replacementsDictionary["$projectname$"]));
   File.Copy(sourceFile, destFile);
}

So there you have it. To create a VSIX deployable C++ project template, that properly sets the WindowsTargetPlatformVersion property, and includes a .vcxproj.filters file, you can implement and associate a custom IWizard assembly with your project template as described above. A working example can be found in the VSXArcana github repo at : https://github.com/EdDore/VSXArcana/tree/master/CppDLLProjectTemplate.

Debugging F1 Help Context with the Debug Help Context ToolWindow extension

Ed Dore — Tue, 19 Dec 2017 21:41:10 GMT

Every once in a while I have a need to watch what’s being pushed as the active F1 context to debug or troubleshoot F1 Context Help. The Debug Help Context ToolWindow is quite useful for diagnosing possible issues with your F1 help context keywords, but requires a bit of insider knowledge or bing/google super powers to dig up the magic registry key to reveal the menu item that displays the toolwindow. With VS 2017’s changes to use a privateregistry.bin, file adding this magic registry value is even more painful. So without further adieu, I present the “Debug Help Context” extension. This is a very simply extension that adds a “Show Help Context” menu item to the bottom of the IDE’s “View” menu. Invoking this menu item will display the hard to find “Debug Help Context” toolwindow.

How to add a custom Paste Special command to the VS Editor menu

Ed Dore — Thu, 21 Apr 2016 21:12:25 GMT

When editing code with the Visual Studio Editor, you may have come across a very useful feature that allows for copying JSON or XML data to the clipboard, and then pasting new classes into your code based upon the structure of the data. For example, consider the following JSON data:

{"employees":[
{"firstName":"John", "lastName":"Deere", "age":"25"},
{"firstName":"Karen", "lastName":"Carpenter", "age":"33"},
{"firstName":"Ronald", "lastName":"McDonald", "age":"101"}
]}

If you select the above JSON text and copy it to the systems’ clipboard, and then select Visual Studio’s “Edit | Paste Special | Paste JSON as Classes” menu command, you’ll end up with a couple of nice new classes inserted into your code file, based upon the structure of the JSON data. For example:

public class Rootobject
{
   public Employee[] employees { get; set; }
}

public class Employee
{
   public string firstName { get; set; }
   public string lastName { get; set; }
   public string age { get; set; }
}

Seeing as how DulcineaS posted a question about adding additional Paste Special commands to Visual Studio, I suspect a small walkthrough might be useful to others that may be contemplating adding similar customizations to the IDE. Additionally, given VS 2015 has been out for some time now, I wanted to play with the updated code spew the new VS 2015 VSIX template and Custom Command item template generated. So without further ado, lets walk through the process of building a new custom command that pastes text as a comment, into a C# code file.

Prerequisites

Visual Studio 2015 Community Edition or better. Don’t forget to use the custom install option and specify the Visual Studio Extensibility Tools. If you don’t, you will need to rerun the setup, to install the extensibility tools that include the project templates and reference assemblies used in this walkthrough.

Walk Through

Those of you familiar with earlier versions of the Visual Studio SDK, take note. The VSSDK Project Templates deployed with the earlier Visual Studio SDKs were revamped for VS 2015, with some of the features turned into Item Templates. So first things first, we need a new VSIX project, to which we’ll subsequently add a custom command to.

Create a new “VSIX Project”

Think of the VSIX project as the deployment or installation package for your extension. Building this project will result in a .VSIX file that you can use to easily deploy your extension.

Select the File | New.Project… menu item, to invoke the “Add New Project” dialog
Select the “VSIX Project” template and enter a project name as highlighted below
Click the “OK” button to create the initial VSIX project

Add a new “Custom Command”

Now we need to add an extensibility point to our newly created VSIX Project. We want to add an additional command to the Edit | Paste Special menu item, so we should choose the “Custom Command” template as follows:

Select the Project | Add New Item… menu item, to invoke the “Add New Item” dialog
Select the “Custom Command” template and enter a filename as highlighted below
Select the “Add” button to add the custom command to the project

Modify the Custom Command

By default, the Item template simply adds our new command to the Tools menu, so we’ll need to modify its properties, so that it shows up on the correct menu, and displayed or hidden, depending upon whether there is any text currently copied to the clipboard.

Open the .VSCT file (PasteAsCommentCommandPackage.vsct)
Locate the following command definition
Then replace it with the following
Save and close the .vsct file

Note, the guidSHLMainMenu:IDG_VS_EDIT_PASTE group is where the existing “Paste JSON As Classes” and “Paste XML As Classes” commands are located. By changing our command’s parent to the same menu group, and setting it’s priority to 0x0300, we have placed our custom “Paste Text As Comment” command in the same menu group, such that it will appear beneath the other two commands. Additionally, I’ve removed the icon, and also added the various CommandFlags to allow for showing and enabling the command programmatically.

Side Note:

So how did I know to use that guidSHLMainMenu and IDG_VS_EDIT_PASTE value? Finding these values can be tricky. I usually start by searching the .VSCT files that ship with the Visual Studio SDK, to see if I can get a hit on a related menu item. For example: However, in this instance I didn’t turn up any references to the Paste commands I was interested in (not entirely unexpected). So the next step was use the old EnableVSIPLogging trick to find the menu I was interested in. Which resulted in the following: So firing up the Find In Files, and casting a wider net. I tried searching all .VSCT files for the word “Special” as that doesn't pop up very often in the VS menus, and found the following in ShellCmdPlace.vsct:




   Paste &Special
   Paste &Special

But this is the menu definition, and while we could use this to add a new menu group with our command, what I really want to do is find the menu group the other commands are already added to. Unfortunately, this particular menu group is not published in any of the VSSDK files, and I had to resort to searching through the Visual Studio code base to see how the Paste JSON As Classes, was defined: And as it turns out, the actual ID we want (IDG_VS_EDIT_PASTE) is defined in the vsshlids.h file. So we can happily use that definition from our own VSCT file.

Specifying When to Load the Package

By default, this VSPackage will load only when you first selected the menu item. However, because we want to programmatically show and enable the command, we need to ensure the package is loaded at the most appropriate time. In general, you should avoid loading your package until needed. This particular example only supports C#, so we can force the package to load whenever a C# project is loaded by adding the following attribute to our Package class as follows:

[PackageRegistration(UseManagedResourcesOnly = true)]
[InstalledProductRegistration("#110", "#112", "1.0", IconResourceID = 400)]
[ProvideMenuResource("Menus.ctmenu", 1)]
[ProvideAutoLoad(VSConstants.UICONTEXT.CSharpProject_string)]
[Guid(PasteAsCommentCommandPackage.PackageGuidString)]
public sealed class PasteAsCommentCommandPackage : Package
{
…..
}

Implementing the Command

First, add a reference to the Microsoft.VisualStudio.Editor.dll, Microsoft.VisualStudio.ComponentModelHost.dll and PresentationCore.dll assemblies. then add the following using statements to your PasteAsCommentCommand.cs file:

using System;
using System.ComponentModel.Design;
using System.Globalization;
using System.Windows;
using Microsoft.VisualStudio.Shell;
using Microsoft.VisualStudio.Shell.Interop;
using Microsoft.VisualStudio.Editor;
using Microsoft.VisualStudio.ComponentModelHost;
using EnvDTE;
using EnvDTE80;

Then add the following helper functions to your PasteAsCommentCommand class:

private DTE2 _dte = null;
DTE2 GetDTE()
{
   if (_dte == null)
   {
      _dte = Package.GetGlobalService(typeof(SDTE)) as DTE2;
   }
   return _dte;
}

private IVsEditorAdaptersFactoryService _adapterFactoryService = null;
IVsEditorAdaptersFactoryService GetAdapterFactoryService()
{
   if (_adapterFactoryService==null)
   {
      IComponentModel componentModel = (IComponentModel)Package.GetGlobalService(typeof(SComponentModel));
      _adapterFactoryService = componentModel.GetService();
   }
   return _adapterFactoryService;
}

Next, modify the existing PasteAsCommentCommand constructor, to create an OleMenuCommand, instead of a MenuCommand, and add a BeforeQueryStatus handler method, which we will use to show and enable the command programmatically:

private PasteAsCommentCommand(Package package)
{
   if (package == null)
   {
      throw new ArgumentNullException("package");
   }

   this.package = package;

   OleMenuCommandService commandService = this.ServiceProvider.GetService(typeof(IMenuCommandService)) as OleMenuCommandService;
   if (commandService != null)
   {
      var menuCommandID = new CommandID(CommandSet, CommandId);
      var menuItem = new MenuCommand(this.MenuItemCallback, menuCommandID);
      var menuItem = new OleMenuCommand(this.MenuItemCallback, menuCommandID);
      menuItem.BeforeQueryStatus += MenuItem_BeforeQueryStatus;
      commandService.AddCommand(menuItem);
   }
}

Next, implement the MenuItem_BeforeQueryStatus method as follows:

private void MenuItem_BeforeQueryStatus(object sender, EventArgs e)
{
   OleMenuCommand pasteCommand = (OleMenuCommand)sender;

   // hidden by default
   pasteCommand.Visible = false;
   pasteCommand.Enabled = false;

   Document activeDoc = GetDTE().ActiveDocument;
   if (activeDoc != null && activeDoc.ProjectItem != null && activeDoc.ProjectItem.ContainingProject != null)
   {
      string lang = activeDoc.Language;
      if (activeDoc.Language.Equals("CSharp"))
      {
         // show command if active document is a csharp file.
         pasteCommand.Visible = true;
      }

      // enable command, if command is visible and there is text on the clipboard
      pasteCommand.Enabled = (pasteCommand.Visible) ? Clipboard.ContainsText() : false;
   }
}

And finally, implement the MenuItemCalback method as follows:

private void MenuItemCallback(object sender, EventArgs e)
{
   string comment = string.Format("// {0}", Clipboard.GetText());
   DTE2 dte = GetDTE();
   try
   {
      dte.UndoContext.Open("Paste Text as Comment");
      var selection = (TextSelection)dte.ActiveDocument.Selection;
      if (selection!= null)
      {
         selection.Insert(comment);
         dte.ActiveDocument.Activate();
         dte.ExecuteCommand("Edit.FormatDocument");
      }
   }
   finally
   {
      dte.UndoContext.Close();
   }
}

Build and Test the Solution

Build the Solution
Launch the Experimental Instance of VS (CTRL+F5), or (F5 if you want to run under the debugger)
Create a new C# project, or load an existing one
Open a C# (.cs) source file in the code editor.
Copy some text to the clipboard
Click in the code editor, where you want the comment to be added
The select the Edit | Paste Special | Paste Text as Comment command to insert the commented text into the source file

Summary

And there you have it. A new custom command, added to the Paste Special menu, that will paste any text copied to the clipboard, formatted as a comment, into your C# source file. In the event I’ve missed something in the above walkthrough, or the casual reader would rather peruse the source, I’ve published the working sample code to the VSXArcana Repo on GitHub. Enjoy.

The VSX Template Wizard

Ed Dore — Sat, 11 Apr 2015 20:19:00 GMT

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:

Creating a VSIX Deployable Project (or Item) Template with Custom Wizard Support

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.

Prerequisites

Visual Studio 2013 Community Edition or better, and the Visual Studio 2013 SDK.

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

2. Then click the OK button to create the Project (or Item) Template with Wizard project.

3. Examine/explore the resulting solution. You’ll find two projects in the solution similar to the following

Note, the first project is the template project responsible for creating the .zip file that contains the actual template that will be deployed when you install the resulting .VSIX. The second project (MyProjectTemplateWizard) creates the wizard assembly and packages it (and the .zip file from the first project) into a .VSIX that you can use to deploy your template and wizard to other machines.

The TemplateWizard.cs contains a rudimentary IWizard implementation, which you can customize to fit your specific needs. Some wizards require a UI, and others don’t. So you’ll want to customize the wizard functionality to fit your specific needs.

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.

There can be only one vstemplate

The VSXItemTemplate and VSXProjectTemplate both produce a “Project Template project”. This particular project type supports the presence of a single .vstemplate. Note that the “other” .vstemplate is actually named with a ._vstemplate extension. This is to ensure the project build properly, and that the ._vstemplate doesn’t accidentally get displayed in the New Project or Add Item dialogs. The ._vstemplate actually gets renamed to .vstemplate by using the TargetFileName attribute, in the owning .vstemplate. See the VSXItemTemplate.vstemplate or VSXProjectTemplate.vstemplate, as an example.

Generating the Key.snk file programmatically

A custom IWizard assembly needs to be built with a strong name. Given it’s not a good idea to distribute the same pre-generated key.snk file, the VSXTemplateWizard generates a new one for each VSXWizardTemplate. The APIs (like StrongNameGen) commonly used to generate the contents of a key.snk file are now deprecated. So the VSXTemplateWizard uses the new ICLRStrongName interface. This interface currently isn’t defined in managed code, so I “borrowed” the definition the CLR Runtime Team published on codeplex. See the VSXTemplateWizard.GenerateStrongNameKeyAndToken method in the VSXTemplateWizard.cs file, to see how this interface is retrieved and used to generate the content of the key.snk file.

Summary

I believe that pretty much covers it. Hopefully, you’ll find the VSX Template Wizard useful. It certainly saves me a bit of time setting up a new templates that need a custom wizard.

VSXArcana.VSXTemplateWizard.vsix

Creating a VSIX Deployable Project (or Item) Template with Custom Wizard Support

Ed Dore — Tue, 10 Jun 2014 13:34:00 GMT

Every now and then, I get an interesting question or problem from a customer (thanks Uma) that highlights a need for some additional documentation, or at the least a sample or walkthrough to illustrate how to get from A to Z. In this instance, the question was "How do you localize a project (or item) template, to support multiple languages?". Better yet, what if that template uses a custom wizard assembly, and you want to deploy it with a VSIX package?

Given all the moving pieces involved, I've opted to break this down into a couple of different blog entries. The first being this one, which will walk you through creating the initial project. And then a follow up blog entry, that will detail the steps to localized the template, wizard assembly, and VSIX package.

Prerequisites

To follow this walkthrough, you will need to install the Visual Studio SDK that matches the version of Visual Studio you are using. If you aren't sure where to find it, there is a list of useful links on the very first entry of this blog that I keep up to date with links to various downloads and resources. Note, while I used VS 2013 Ultimate to create this project, this same technique can be used for VS 2012 and VS 2010 (Pro or better SKUs).

Getting Started

Upon installing the Visual Studio SDK, the following project templates are added to assist you in developing new project and item templates.

C# Item Template
C# Project Template
Visual Basic Item Template
Visual Basic Project Template

These Project templates create a baseline project or item template, that when built, produces a .zip file that you can manually copy into your ...\Documents\Visual Studio 20xx\Templates directory, and then used to create a new project, or add a new item to an existing project.

The Visual Studio SDK, also includes a stand-alone "VSIX Project" template, which can be used to deploy a template (in addition to other assets).

These VSIX projects do not generate an assembly by default. But if you manually edit a few properties in the .csproj, you can use the VSIX project to build an assembly and have it included as a part of the .VSIX payload.

So instead of creating a solution with a structure similar to the following:

   Solution - MyTemplateWithWizard
      - MyProjectTemplate   (produces the template as a .zip file)
      - MyTemplateWizard   (produces an assembly with an IWizard implementation)
      - MyTemplateWithWizardVSIX   (packages the template and assembly into a .VSIX)

You can actually implement the wizard assembly with the VSIX project, simplifying the solution structure such that there are only two projects required. For example:

   Solution - MyTemplateWithWizard
      - MyProjectTemplate (produces the template as a .zip file)
      - MyProjectWizard   (builds the wizard assembly, packaging it and the template into a .VSIX)

The following is a walkthrough that will show you how to create a VSIX deployable project template with custom wizard support, using just the two projects as described above.

Create a new "C# Project Template" project

Select the File.New.Project... menu item, to invoke the "Add New Project" dialog
Select the "C# Project Template" template and enter a project name as shown below
Click the "OK" button to create the initial template project

Add a new "VSIX Project" to the solution

Right click the "Solution" node in the Solution Explorer, and select the Add.New Project... menu item, to invoke the "Add New Project" dialog
Select the "VSIX Project" template and enter a project name as shown below
Click the "OK" button to create and add the VSIX project to the solution

Add the template as an asset of the VSIX project.

Open the project's source.extension.vsixmanifest file
In the manifest designer, add a name or company to the "Author:" field
Select the "Assets" tab, then click the "New" button as highlighted below
In the "Add New Asset" dialog, select the Type, Source, and Project fields as shown below

Build and Verify

Build the Solution
Launch the VS Experimental Instance with CTRL+F5
Select the File.New.Project... menu item, to invoke the "Add New Project" dialog
Select the "MyProjectTemplate" and create a new project as shown below

Modify the template.

Change some of the elements displayed in the New Project dialog, by editing the .vstemplate file
1. Open the .vstemplate file
2. Change the Name, Description, and DefaultName elements as highlighted below
  
  xmlversion="1.0"encoding="utf-8"?>
  <VSTemplateVersion="3.0.0"Type="Project"
  xmlns=https://schemas.microsoft.com/developer/vstemplate/2005xmlns:sdk="https://schemas.microsoft.com/developer/vstemplate-sdkextension/2010">
     <TemplateData>
        <Name>My ProjectName>
        <Description>My Custom Project TemplateDescription>
        <Icon>MyProjectTemplate.icoIcon>
        <ProjectType>CSharpProjectType>
        <RequiredFrameworkVersion>2.0RequiredFrameworkVersion>
        <SortOrder>1000SortOrder>
        <TemplateID>0504f2de-af7a-4065-a542-f65ca8c61790TemplateID>
        <CreateNewFolder>trueCreateNewFolder>
        <DefaultName>MyProjectDefaultName>
        <ProvideDefaultName>trueProvideDefaultName>
     TemplateData>
     <TemplateContent>
        <ProjectFile="ProjectTemplate.csproj"ReplaceParameters="true">
           <ProjectItemReplaceParameters="true"TargetFileName="Properties\AssemblyInfo.cs">AssemblyInfo.csProjectItem>
           <ProjectItemReplaceParameters="true"OpenInEditor="true">Class1.csProjectItem>
        Project>
     TemplateContent>
  VSTemplate>
Rename Class1.cs to something more appropriate.
1. Right click "Class1.cs" in the Solution Explorer, and select the "Rename" menu item
2. Rename Class1.cs to MyProject.cs
3. Open MyProject.cs, and change the classname from Class1 to MyProject, and add a simple comment as shown below

Fixup the .vstemplate and .csproj
1. Open the .vstemplate file, find and rename "Class1.cs" to "MyProject.cs"
2. Open the template's .csproj file, find and rename "Class1.cs" to "MyProject.cs"
(Optional) Build and Test in the Experimental Instance again

Modify the .VSIX project to build a custom wizard implementation.

Modify the project's properties to build an assembly.
1. Right click the VISX Project node in the Solution Explorer, and select "Unload Project"
2. Right click the VISX Project node in the Solution Explorer, and select "Edit MyProjectWizard.cs"
3. Change the following properties from "false" to "true"
  
  >true
  true
  true
4. Save MyProjectWizard.csproj
5. Right click the VSIX Project node in Solution Explorer, and select "Reload Project"
Add a reference to EnvDTE.dll. Select the envdte node in Solution Explorer, and in the Properties toolwindow, change the "Embed Interop Types" property to "False", to ensure a clean build
Add a reference to the Microsoft.VisualStudio.TemplateWizardInterface.dll
Right click the VSIX Project node in Solution Explorer, and select Add.Class... menu item
Add a new class called MyProjectWizard.cs
Replace the contents of MyProjectWizard.cs with the following

using System;
using System.Collections.Generic;
using EnvDTE;
using Microsoft.VisualStudio.TemplateWizard;

namespace MyProjectWizard
{
    public class MyProjectWizard : IWizard
    {
        private DTE _dte;

        public void BeforeOpeningFile(ProjectItem projectItem) { }
        public void ProjectFinishedGenerating(Project project) { }
        public void ProjectItemFinishedGenerating(ProjectItem projectItem) { }
        public void RunFinished() { }

        public void RunStarted(object automationObject, Dictionary<string, string> replacementsDictionary, WizardRunKind runKind, object[] customParams)
        {
            _dte = (DTE)automationObject;

            // add an entry to the dictionary to specify the string used for the $greeting$ token
            replacementsDictionary.Add("$greeting$", "Hello Custom Library");
        }

        public bool ShouldAddProjectItem(string filePath) { return true; }
    }
}
Open the source.extension.vsixmanifest, select the Assets tab, and click the "New" button
In the "Add New Asset" dialog, select the Type, Source, and Project fields as shown below
Select File.Save All to ensure all the above changes are saved
Strong Name the Assembly (Wizard assemblies need to be strong named)
1. Right Click the VSIX Project node in Solution Explorer, and select the Properties menu item
2. In the Project Designer, select the "Signing" tab
3. Check the "Sign the Assembly" checkbox as shown below
4. Select " in the "Choose a strong name key file"
5. In the "Create Strong Name Key" dialog, enter "key.snk" for the Key filename
6. Uncheck the "Protect my key file with a password" checkbox, and click the OK button

Associate the Wizard with the project template

Run SN.EXE -T on the wizard assembly to retrieve the public token key
Tip: Create an external tool entry on the Tools menu, as described in Jeremiah Clark's blog Visual Studio Tip: Get Public Key Token for a Strong Named Assembly
Open the template's .vstemplate file and add the following section

<WizardExtension>
<Assembly>MyProjectWizard, Version=1.0.0.0, Culture=neutral, PublicKeyToken=22c2a1a5fa7b6905Assembly>
<FullClassName>MyProjectWizard.MyProjectWizardFullClassName>
WizardExtension>
Open the template project's MyProject.cs file, and replace the comment line with the following

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

namespace $safeprojectname$
{
    // $greeting$
    public class MyProject
    {
    }
}

Build and Test the Solution

Build the Solution
Set a breakpoint on the MyProjectWizard.RunStarted method
Launch the Experimental Instance with the debugger (F5)
Select the File.New.Project... menu item, to invoke the "Add New Project" dialog
Select the "My Project Template", and click the OK button
When the breakpoint is hit, select Debug.Continue (or F5) and let the wizard run to completion
Note the new comment added to the resulting MyProject.cs file

Summary

And there you have it, a VSIX deployable template with a custom wizard support. When finished, use the resulting .VSIX file to deploy the template to your production environment. And if you think others will find your template useful, consider uploading it to the VS Extension Gallery.

The resulting code from the above walkthrough can be downloaded from here.

VS 2013 SDK Samples released

Ed Dore — Fri, 30 May 2014 14:41:55 GMT

It took a bit longer than we’d have liked, but the VS team has finally gotten around to porting and posting the original VS SDK samples from VS 2010, over to VS 2013. Below is a listing of the samples and where they can be downloaded from.

Build Progress Bar – VS 2013

A Visual Studio Package which provides a new tool window called "Build Progress" which displays a WPF ProgressBar indicating percentage completion of the current solution build.

Caret Fish Eye – VS 2013

This is a sample extension for Visual Studio 2013 that visually scales lines to be smaller the farther away from the caret's current position they are. It accomplishes this using the line transformation API.

Code Sweep – VS 2013

This sample allows the user to specify a set of terms to search for by specifying a set of XML files containing the term definitions. The user-configurable settings are stored in the project file. The scan can be invoked either on command or as an integrated part of the build process. When the scan is performed, a custom task provider causes hits, if any, to be shown in the task list.

Command Target RGB – VS 2013

A Visual Studio Package which provides a multi-instance tool window called "Red Green Blue" which hosts a toolbar with three buttons that will change the tool window's background color and move the toolbar in the frame.

Completion Tooltip Customization – VS 2013

This is a sample extension for the Visual Studio 2013 editor that replaces the completion tooltip UI.

WPF Designer over SML – VS 2013

Demonstrates how to create an extension with a WPF-based Visual Designer for editing XML files with a specific schema (XSD) in coordination with the Visual Studio XML Editor.

Diff Classifier – VS 2013

This is a sample Visual Studio 2013 classifier for diff/patch files. It provides formatting for the various line types found in diff files using the classification API.

Highlight Word – VS 2013

This is a Visual Studio 2013 sample extension that uses tagging and adornments to highlight all the occurences of the word currently under the caret.

Inline XPS Viewer – VS 2013

This is a sample adornment extension showing how to host a document viewer in Editor code window. In the doc viewer you can zoom in/out, view whole/2 pages, print and find text in the doc.

Intra-text adornment – VS 2013

This is a sample extension for the Visual Studio 2013 editor that replaces a hexadecimal color with a color swatch using intra-text adornments.

Ook Language sample – VS 2013

This is the example used during the Visual Studio Ecosystem Summit Presentation "Getting Linguistic: Integrating a Language into Visual Studio" by Chris Granger. It implements the following language features for the esoteric language "Ook!":

Reference Package – VS 2013

This sample shows how to create a Visual Studio package and how to add an entry into the Help About dialog.

Reference Service – VS 2013

This sample shows how to be a Visual Studio service provider and how to consume Visual Studio services.

Single File Generator – VS 2013

This sample demonstrates how to build a single file generator.

Source Control Provider – VS 2013

This sample demonstrates how to create a source code control provider.

Todo Classification – VS 2013

This is the sample code written during the Visual Studio Ecosystem Summit presentation "I Want Coloring: A scenario based look at the new editor". It provides a general purpose TodoTagger as well as classification and a glyph factory.

Todo Glyph Factory – VS 2013

This sample adds a glyph in the glyph margin on all lines that have comments with the word "todo" in them. It demonstrates how to create a custom glyph factory that uses a tagger.

Typing Speed Meter – VS 2013

This is a sample editor extension for Visual Studio 2013 that uses and IVsTextViewCreationListener and an adornment to create a typing speed meter.

Spell Checker – VS 2013

This sample uses smart tags and squiggles to display spelling errors in your comments inside of Visual Studio 2013. The extension provides an excellent example of how you use other services in combination with those provided in VS to add real-world functionality to the editor.

Options Page – VS 2013

This sample demonstrates how to add custom options pages into the standard Visual Studio Options dialog. The sample adds two options pages and demonstrates how to customize the presentation and properties' persistence.

Running Document Table Explorer – VS 2013

This sample demonstrates how to create an explorer that logs Running Document Table (RDT) events. Selecting an event from the grid displays its properties in the Properties Window.

WPF Tool Window – VS 2013

This sample demonstrates how to create a package that provides tool windows which host Windows Forms controls and WPF controls.

Windows Forms Control Installer – VS 2013

This sample demonstrates how to create a Visual Studio package (VSPackage) that loads custom Windows Forms controls into the Toolbox. The code defines two toolbox items: MyCustomTextBox, which is a normal Windows Forms control, and MyCustomTextBoxWithPopup, which provides a custom ToolboxItem that pops up a dialog box when the item is added.

Menu and commands – VS 2013

This sample demonstrates how to create menu and command items and visualize them inside Visual Studio’s menus and toolbars.

Editor with Toolbox – VS 2013

This sample demonstrates how to create a package that provides an Editor type extended with Toolbox support.

Combo Box – VS 2013

This sample demonstrates how to create combo boxes on Visual Studio’s toolbars. Four types of combo boxes that can be created are shown in this sample.

MSDN Search – VS 2013

This sample demonstrates how to extend Quick Launch and add a search provider to search outside Tools Options / Menus / Open Documents (the built-in providers).

Basic Source Control Provider – VS 2013

This sample demonstrates how to create a source control provider that registers with Visual Studio and can be selected as active source control provider.

Alternatively, you can download the entire set of above samples from:

Visual Studio 2013 SDK Samples.

VS 2013 Isolated Shell generates an error when attempting to load a custom project type

Ed Dore — Wed, 16 Apr 2014 10:17:00 GMT

After adding support for a custom project type to a VS 2013 Isolated Shell project, you may encounter the following error dialog.

This error message is displayed when the the isolated shell instance loads the wrong version of msbuild assemblies. In particular, the isolated shell’s .exe.config file (in my specific case, my MyShellony.exe.config) was generated without some critical binding redirects for some msbuild components. Consequently, my isolated shell instance, would display the above message whenever I attempted to load an instance of my custom project type.

This is a known bug in the VS 2013 Isolated Shell project template.

To fix this issue, you will need to add the following binding redirects in the section of your shell’s .exe.config (located in the Isolated Shell project’s “Source Files” folder)

   <dependentAssembly>
     <assemblyIdentity name="Microsoft.Build.Framework" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
     <bindingRedirect oldVersion="2.0.0.0-4.0.0.0" newVersion="12.0.0.0" />
   dependentAssembly>

   <dependentAssembly>
     <assemblyIdentity name="Microsoft.Build" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
     <bindingRedirect oldVersion="2.0.0.0-4.0.0.0" newVersion="12.0.0.0" />
   dependentAssembly>

   <dependentAssembly>
     <assemblyIdentity name="Microsoft.Build.Engine" publicKeyToken="b03f5f7f11d50a3a" culture="neutral" />
     <bindingRedirect oldVersion="2.0.0.0-4.0.0.0" newVersion="12.0.0.0" />
   dependentAssembly>

Managed Package Framework (MPF) for Projects released for VS 2013

Ed Dore — Wed, 11 Dec 2013 11:21:24 GMT

Last night the VS team uploaded a new version of MPF_Proj for VS 2013 to CodePlex, which can be used to facilitate building custom project types for Visual Studio 2013.

Links to earlier versions can be found in my earlier blog entry.

Building a VSIX Deployable Single File Generator

Ed Dore — Wed, 27 Nov 2013 14:48:42 GMT

A recent post on the VS Extensibility Forum related to deploying a Single File Generator (also called a “Custom Tool”), inspired me to write a new VSIX Deployable Single File Generator Sample to the MSDN Code gallery.

The existing samples were written a few releases back, and none of them take advantage of VSIX deployment. To create the new sample, I opted to create the initial project using the Visual Studio SDK’s “Visual Studio Package” project template. This ensured I ended up with the project settings and build rules that would automatically generate and include the .pkgdef to register the Single File Generator, and package it into a .VSIX file.

I used VS 2010 here, as I also wanted to also verify that you could build a Single File Generator with an older version of the Visual Studio tools, and then simply tweak the .vsixmanifest to target more recent versions of Visual Studio as well. If you happen to be using a newer version of VS, you can use these same steps to produce a similar project.

Install the Visual Studio SDK that matches the version of VS you have installed. You can find a link to all the published versions in the Welcome post of this blog.
Create a new “Visual Studio Package” project, selecting C# as the language, and then removing/deselecting all other options in the project wizard.
Remove the VSPackage.resx, GlobalSuppressions.cs, and Guids.cs files from project.
Rename the xxxxPackage.cs to something more fitting your project; MyCodeGenerator.cs for example.
Replace the code in MyCodeGenerator.cs with something similar to the code found in the SimpleFileGenerator.cs.
Edit the source.extension.vsixmanifest to include the versions of VS you want to target.
Build and test in the experimental instance using F5.
Use the resulting .VSIX file to deploy your Single File Generator to other machines.

One interesting discovery made while writing this, was that you can successfully target Express versions of Visual Studio, by removing the reference to Microsoft.VisualStudio.MPF from the source.extension.vsixmanifest file. For example:

        Visual Studio MPF

You’ll still see a warning during the build due to the VSIX containing non-template content. But this can be ignored, and the assembly and .pkgdef for your Single File Generator will be properly installed even for the Express SKUs you list in the .vsixmanifest. For example:

https://schemas.microsoft.com/developer/vsx-schema/2010">

    SimpleFileGenerator
    Microsoft
    1.0
    Demo implementation of a Single File Generator
    1033
    false


        Pro
        Express_All


        Pro
        Express_All


        Pro
        Express_All




    |%CurrentProject%;PkgdefProjectOutputGroup|

Note, this is an extremely bare boned sample, and it’s primary purpose is to illustrate how to go about leveraging the VSSDK package project to create a VSIX deployment for a Single File Generator. An internet search will turn up a good number of examples/articles on this topic. But one of my favorites was recently published by Qwertie on Code Project entitled “Writing a Single-File Generator”.

How to change solution icon in the Visual Studio Isolated Shell

Ed Dore — Tue, 18 Dec 2012 11:54:27 GMT

This question posted to the VS Extensibility Forum recently caught my attention. Initially, I initially suspected this would have a simple answer, but it turns out the shell pulls this icon directly from a resource in msenv.dll.

After examining the underlying IVsHierarchy implementation of the root solution node, it looked like the icon could be changed by setting the VSHPROPID_IconHandle property on the solution node. The next question to solve was “when” to set this. You cannot set the property from the shell stub, and package assemblies are typically loaded on demand.

So the best solution is to force one of your isolated shell packages to load at startup, by applying a couple of ProvideAutoLoad attributes one of your VSPackage objects. Specifically:

    [ProvideAutoLoad(UIContextGuids.SolutionExists)]     
    [ProvideAutoLoad(UIContextGuids.NoSolution)]

Note, this is generally frowned upon in most instances. To keep startup time and memory footprint to a minimum, packages should be loaded on demand. Especially when targeting the integrated shell. But this is an isolated shell scenario, and it’s certain you’ll have to have at least one package loaded.

Now that we have the package configured to load at startup, we could just set the property from the package’s overridden Initialize method. But that would be a mistake. Various shell services are also implemented with packages, and there is no guarantee to the order in which packages are loaded. So we need to wait until all prescribed packages are loaded.

To do that, we need to wait until the VSSPROPID_ShellInitialized property is set. And this can be done by implementing IVsShellPropertyEvents and calling IVsShell.AdviseShellPropertyChanges.

Below, is a slightly modified AboutBoxPackage (initially generated with the isolated shell project wizard), that I created as a quick proof of concept to verify that the solution icon can actually be changed for an isolated shell application.

Code Snippet
using System;

using System.Diagnostics;

using System.Drawing;

using System.Globalization;

using System.Reflection;

using System.Runtime.InteropServices;

using System.ComponentModel.Design;

using Microsoft.Win32;

using Microsoft.VisualStudio;

using Microsoft.VisualStudio.Shell.Interop;

using Microsoft.VisualStudio.OLE.Interop;

using Microsoft.VisualStudio.Shell;

namespace MyShellony.AboutBoxPackage

{

    [PackageRegistration(UseManagedResourcesOnly = true)]

    [ProvideMenuResource("Menus.ctmenu", 1)]

    [Guid(GuidList.guidAboutBoxPackagePkgString)]

    // ensure package is loaded on startup

    [ProvideAutoLoad(UIContextGuids.SolutionExists)]

    [ProvideAutoLoad(UIContextGuids.NoSolution)]

    public sealed class AboutBoxPackage : Package, IVsShellPropertyEvents

    {

        private static Icon solutionIcon;

        private uint propChangeCookie;

        public AboutBoxPackage() 

        {

            solutionIcon = new Icon(Assembly.GetExecutingAssembly().GetManifestResourceStream("MyShellony.AboutBoxPackage.Resources.SolutionIcon.ico"));

        }

        protected override void Initialize()

        {

            base.Initialize();

            // watch for VSSPROPID property changes

            IVsShell vsShell = (IVsShell)GetService(typeof(SVsShell));

            vsShell.AdviseShellPropertyChanges(this, out propChangeCookie);

            OleMenuCommandService mcs = GetService(typeof(IMenuCommandService)) as OleMenuCommandService;

            if (null != mcs)

            {

                CommandID menuCommandID = new CommandID(GuidList.guidAboutBoxPackageCmdSet, (int)PkgCmdIDList.cmdidHelpAbout);

                MenuCommand menuItem = new MenuCommand(ShowAboutBox, menuCommandID);

                mcs.AddCommand(menuItem);

            }

        }

        // when shell is fully initialized, set the icon on the solution explorer's root node.

        public int OnShellPropertyChange(int propid, object var)

        {

            if (propid == (int)__VSSPROPID4.VSSPROPID_ShellInitialized && Convert.ToBoolean(var) == true)

            {

                // set VSHPROPID_IconHandle for Solution Node

                IVsHierarchy solHierarchy = (IVsHierarchy)GetService(typeof(SVsSolution));

                int hr = solHierarchy.SetProperty((uint)VSConstants.VSITEMID.Root, (int)__VSHPROPID.VSHPROPID_IconHandle, solutionIcon.Handle);

                // stop listening for shell property changes

                IVsShell vsShell = (IVsShell)GetService(typeof(SVsShell));

                hr = vsShell.UnadviseShellPropertyChanges(propChangeCookie);

                propChangeCookie = 0;

            }

            return VSConstants.S_OK;

        }

        private void ShowAboutBox(object sender, EventArgs e)

        {

            AboutBox aboutBox = new AboutBox();

            aboutBox.ShowModal();

        }

    }

}