This article explains how to use correctly the OnConnection method of an add-in, which can be called at several times with different values in the connectMode parameter.

Add-ins can be loaded:

• On startup, when Visual Studio starts and the add-in is marked in the Add-In Manager (under the Tools menu) to load on startup. In this case the OnConnection method is called with connectMode=ext_ConnectMode.ext_cm_Startup.
• On demand, when the add-in is not marked to load on startup but the user loads it manually with the Add-In Manager. In this case the OnConnection method is called with connectMode=ext_ConnectMode.ext_cm_AfterStartup.
• From the command-line (using devenv.exe to build a solution). In this case the OnConnection method is called with connectMode=ext_ConnectMode.ext_cm_CommandLine. Be aware that there are some bugs in some old versions of Visual Studio and this only seems to work correctly in Visual Studio 2008.
• When the add-in uses permanent toolbars, commandbars and buttons (permanent meaning that the user interface appears even if the add-in is not loaded) and Visual Studio requires the add-in to initialize such permanent user interface. In this case the OnConnection method is called (only once) with connectMode=ext_ConnectMode.ext_cm_UISetup. This connect mode should be handled differently to the  ext_ConnectMode.ext_cm_Startup and ext_ConnectMode.ext_cm_AfterStartup cases. See HOWTO: Adding buttons, commandbars and toolbars to Visual Studio .NET from an add-in.
• When a specific solution is loaded, if the add-in is specific to a solution and not a general add-in. In this case the OnConnection method is called with connectMode=ext_ConnectMode.ext_cm_Solution. See How to: Create Solution Add-ins.

So, there are two connect modes, ext_ConnectMode.ext_cm_Startup and ext_ConnectMode.ext_cm_AfterStartup, that should be handled in the same way because generally there should be no difference whether the add-in is loaded automatically on startup, or manually some minutes later. Therefore you may be tempted to use this code:

 Public Sub OnConnection(ByVal application As Object, ByVal connectMode _ 
   As Extensibility.ext_ConnectMode, ByVal addInInst As Object, _
   ByRef custom As System.Array) _
   Implements Extensibility.IDTExtensibility2.OnConnection 

   applicationObject = CType(application, EnvDTE.DTE)
   addInInstance = CType(addInInst, EnvDTE.AddIn

   Select Case connectMode
      Case ext_ConnectMode.ext_cm_UISetup
      ...
      Case ext_ConnectMode.ext_cm_Startup, ext_ConnectMode.ext_cm_AfterStartup 
      ...
   End Select

End Sub

However, when the add-in is loaded on startup and the OnConnection method is called by Visual Studio with the ext_ConnectMode.ext_cm_Startup connect mode, Visual Studio is not fully initialized. While many add-ins can be initialized correctly at this point, some things will fail. For example, if your add-in shows a toolwindow when loaded, the toolwindow won't be shown when the add-in is loaded on startup, but it is shown when the add-in is loaded by hand with the Add-In Manager.

While it would be nice that Visual Studio called the OnConnection method when it is fully initialized, the IDTExtensibility2 interface provides instead an OnStartupComplete method that Visual Studio calls when the IDE is fully initialized. So, the correct code to use is the following:

 Public Sub OnConnection(ByVal application As Object, ByVal connectMode _ 
   As Extensibility.ext_ConnectMode, ByVal addInInst As Object, _
   ByRef custom As System.Array) _
   Implements Extensibility.IDTExtensibility2.OnConnection 

   applicationObject = CType(application, EnvDTE.DTE)
   addInInstance = CType(addInInst, EnvDTE.AddIn

   Select Case connectMode
      Case ext_ConnectMode.ext_cm_UISetup
      ...
      Case ext_ConnectMode.ext_cm_Startup
         ' The add-in was marked to load on startup 
         ' Do nothing at this point because the IDE may not be fully initialized 
         ' Visual Studio will call OnStartupComplete when ready 

      Case ext_ConnectMode.ext_cm_AfterStartup 
         ' The add-in was loaded after startup 
         ' Initialize it in the same way that when is loaded on startup calling manually this method:
         OnStartupComplete(Nothing)

    End Select

End Sub

Public Sub OnStartupComplete(ByRef custom As System.Array) _
   Implements Extensibility.IDTExtensibility2.OnStartupComplete

   ' Initialize the add-in
   ...
End Sub

Related articles

• HOWTO: Adding buttons, commandbars and toolbars to Visual Studio .NET from an add-in.

Go back to the 'Resources for Visual Studio .NET extensibility' section for more articles like this

You can code, design, locate code and document your apps much faster using VB.NET, C#, C++ or Visual J#: