The art and science of creating SSMS 2012 add-ins – Part 1 – Laying the Foundation

This article is a tutorial for creating SQL Server Management Studio 2012 add-ins. We will show you how to create and debug a simple SSMS add-in using Microsoft Visual Studio 2012, and explain the main parts of the add-in structure in more detail. In the first part of this article we will cover the processes of creating a Visual Studio add-in project and loading the add-in into SSMS, and we will describe the structure of the .Addin file. We will also cover the process of setting up debugging for the add-in project. In the second part of the article we will cover the code generated by Visual Studio, main parts of the Connect class and we will go through the process of creating simple menu items for the add-in

SSMS vs. Microsoft Visual Studio add-in support

Although Microsoft officially supports writing add-ins for Visual Studio, for some odd reason that is not the case with SSMS. Luckily, since SSMS2012 is based on Visual Studio 2010 shell, the add-in loading mechanism is roughly the same and it doesn’t imply tampering with the registry values (which is the case with SSMS 2008 R2 and earlier versions). Let’s take a closer look at that mechanism

The .Addin files

SSMS 2012 (same as Visual Studio) searches for XML .Addin files at specific locations on startup in order to load an add-in. The list of folders that the SSMS scans can be found in the registry key:

HKEY_CURRENT_USER\Software\Microsoft\SQLServerManagementStudio\11.0_Config\AutomationOptions\
LookInFolders

So, run Regedit and go to the specified key. You will see something like this:

*Note: This list is fixed and recreated each time SSMS 2012 is started

Two mains paths that interest us are:

1. C:\ProgramData\Application Data\Microsoft\MSEnvShared\Addins

   Use this path if you want to install the add-in for all users. Note that the Application Data is a Junction folder and that the path in which the .Addin file is placed should be:

   C:\ProgramData\Data\Microsoft\MSEnvShared\Addins

2. C:\Users\\AppData\Roaming\ Microsoft\MSEnvShared\Addins

   Use this path if you want to install the add-in for a specific user

Structure of the .Addin file

Now, let’s take a look at the structure of the .Addin file:

Important elements for SSMS are:

• Assembly in which you define the path to the .dll containing the main class that implements the OnConnection method of the IDTExtensibility2 interface
• FullClassName in which you define the name of that class
• LoadBehavior defines how add-in should be loaded (e.g. 0 – do not load at startup, 1 – load at startup…)
• CommandPreload defines which parameters should be passed to the OnConnection method (important for temporary and permanent commandbars which we will cover in the second part of the article)
• CommandLineSafe defines if the add-in is safe for CLI usage (e.g. does not create UI elements)

Creating the Visual Studio Addin project

OK, now that we know the details behind the mechanism for loading up add-ins into SSMS 2012, we can start creating one using Visual Studio 2012

• Open up Visual Studio and Go to File–>New–>Project…
• Expand Other Project Types in the Templates list and click on Extensibility
• Choose Visual Studio add–in, type the name and folder that you like and press OK
• You will be presented with the add-in wizard welcome message. Press Next

• Through the wizard you choose the programming language, host application (for SSMS 2012 choose MSVS 2012), name and description of the add-in

  You are then presented with the following screen:

  

  These options define the values for the elements in the .Addin file. Besides that, the first one generates code for creation of a command with your add-in name inside the Tools menu item

  Choose the first one and click Next

• The About box is not for SSMS 2012 so just click Next and then Finish. MSVS will generate necessary files and create a solution

Setting up debugging

Now we need to set the project properties and the .Addin file

• Go to the Project properties and open Debug tab. In the Start external program type the path to the SSMS 2012 executable. Default one is:

  C:\Program Files\Microsoft SQL Server\110\Tools\Binn\ManagementStudio\Ssms.exe

• Delete any command-line arguments as they are meant for MSVS and won’t work in our case
• Build the add-in
• Go to Debug–>Exceptions–>Managed Debugging Assistant and uncheck PinvokeStackImbalance

Customizing the .Addin file

• Open the .Addin file. Change the Host Application Name and Version elements according to the .Addin file structure shown above
• Change the Assembly path to point to the .dll file of your add-in
• Set the LoadBehavior value to 1 since we want our add-in to load on host application startup
  Note: In case that an error occurs while loading the add-in into host application, this value will be changed to 0 and after you fix the cause of the error you will have to change it to 1 in order for your add-in to load again
• Set the CommandPreload value to 0 since we want to recreate our UI elements each time that the add-in is loaded
• Move edited .Addin file to one of the folders listed in the beginning of the document
  *Note: Filename is not important, only the extension

That is it. The foundation is ready and now we can concentrate on the interesting part, add-in code, which will be covered in the next part of this article

See also:
The art and science of creating SSMS 2012 add-ins – Part 2 – Customizing the add-in
The art and science of creating SSMS 2012 add-ins – Part 3 – Creating Toolbars and new Windows