The Add-In Project

Add-ins are DLLs, so the Add-in Wizard creates a Class Library project for your add-in. This project contains a source file named Connect, which defines the add-in class, also named Connect. The Connect class implements the IDTExtensibility2 interface, which serves as the main conduit for add-in/IDE communication. (Connect also implements IDTCommandTarget if you select the user interface option in the Add-in Wizard.) Table 6-1 lists the five methods of the IDTExtensibility2 interface.

Table 6-1: IDTExtensibility2 Interface Methods

Method	Description
OnConnection	Called when the add-in is loaded
OnStartupComplete	Called when Visual Studio finishes loading
OnAddInsUpdate	Called whenever an add-in is loaded or unloaded from Visual Studio
OnBeginShutdown	Called when Visual Studio is closed
OnDisconnection	Called when the add-in is unloaded

The Connect.cs file in Listing 6-1 shows the code (minus some comments) that the Add-in Wizard generates for a typical C# add-in with a menu command. We'll walk through the source code, pointing out any interesting features along the way.

Listing 6-1: Connect.cs, the add-in source code generated by the Add-in Wizard

   using System;   using Extensibility;   using EnvDTE;   using EnvDTE80;   using Microsoft.VisualStudio.CommandBars;   using System.Resources;   using System.Reflection;   using System.Globalization;   public class Connect : Object, IDTExtensibility2, IDTCommandTarget   {       public Connect()       {       }       public void OnConnection(object application,           ext_ConnectMode connectMode, object addInInst,           ref Array custom)       {           _applicationObject = (DTE2)application;           _addInInstance = (AddIn)addInInst;           if(connectMode == ext_ConnectMode.ext_cm_UISetup)           {               // Generate the add-in's menu item...           }       }       public void OnDisconnection(ext_DisconnectMode disconnectMode,           ref Array custom)       {       }       public void OnAddInsUpdate(ref Array custom)       {       }       public void OnStartupComplete(ref Array custom)       {       }       public void OnBeginShutdown(ref Array custom)       {       }       public void QueryStatus(string commandName,           vsCommandStatusTextWanted neededText, ref vsCommandStatus status,          ref object commandText)       {           if(neededText ==               vsCommandStatusTextWanted.vsCommandStatusTextWantedNone)           {               if(commandName == "MyAddin1.Connect.MyAddin1")               {                   status = (vsCommandStatus)                       vsCommandStatus.vsCommandStatusSupported |                       vsCommandStatus.vsCommandStatusEnabled;               }           }       }       public void Exec(string commandName, vsCommandExecOption executeOption,           ref object varIn, ref object varOut, ref bool handled)       {           handled = false;           if(executeOption ==               vsCommandExecOption.vsCommandExecOptionDoDefault)           {               if(commandName == "MyAddin1.Connect.MyAddin1")               {                   handled = true;                   return;               }           }       }       private DTE2 _applicationObject;       private AddIn _addInInstance;   } 

At the top of the listing, you'll see that the Add-in Wizard generates a set of using statements for the programmer's convenience. The three most important namespaces in the using statements are Extensibility, EnvDTE, and EnvDTE80; the first namespace defines the types used by IDTExtensibility2, and the latter two define the types in the automation object model.

The first method in the listing, OnConnection, wins the prize for "most important add-in method." Visual Studio calls this method when it loads the add-in, and it passes the add-in a reference to the root object of the automation object model through the application parameter. The code generated by the Add-in Wizard casts the application parameter to the EnvDTE80.DTE2 type and stores the result in a private variable named applicationObject. All further interaction between the add-in and the automation object model takes place through the applicationObject variable.

Visual Studio also passes the add-in a reference to its corresponding AddIn object through the addInInst parameter; the add-in stores this reference in a private variable named addInInstance.

The rest of the code in OnConnection creates an add-in menu command on the Tools menu. (This code is absent if you forgo the user interface option in the Add-in Wizard.) The menu-creation code executes conditionally, depending on the following if statement:

 if (connectMode == ext_ConnectMode.ext_cm_UISetup) 

The connectMode parameter holds a value that describes how the add-in was loaded. For add-ins that create a menu command, Visual Studio passes in the Extensibility.ext_ ConnectMode. ext_cm_UISetup value the first time the add-in loads after being installed, which signals to the add-in that this is a good time to add its commands to the IDE.

The Add-in Wizard doesn't generate any code in the bodies of the other four IDTExtensibility2 methods: OnStartupComplete, OnAddinsUpdate, OnBeginShutdown, and OnDisconnection. The two IDTCommandTarget methods, QueryStatus and Exec, have some boilerplate code that helps manage the add-in's menu command and menu command clicks, respectively. To handle menu command clicks, you add code to the Exec method in the second if statement, which begins with

 if (commandName == "MyAddin1.Connect.MyAddin1") 

There isn't much code in Connect.cs, even if you've selected every option in the Add-in Wizard, but the code that's there creates a fully functional add-in that you can build on.