The OnConnection method and ext_ConnectMode.ext_cm_UISetup of Visual Studio add-ins

Without doubt, the most confusing area each newbie add-in developer faces when starting to write an add-in for Visual Studio, is the OnConnection method and theĀ  ext_ConnectMode.ext_cm_UISetup value of the connectMode parameter. I think that every week I answer at least one question about this in the MSDN forums. There are several things contributing this confusion:
  • It is not intuitive that you have commands, and you have buttons, and that while commands should created only once in the lifetime of the add-in to preserve keyboard shortcuts, etc. (and they should not be recreated each time that the add-in is loaded), buttons can be recreated or not, depending on whether you are using a permanent user-interface approach, or a temporary user-interface approach. These approaches are not well documented in the MSDN docs.
  • The ext_ConnectMode.ext_cm_UISetup is used by the OnConnection method, and since the OnConnection method (as its name implies) is called each time the add-in is loaded, it gives the impression that the ext_ConnectMode.ext_cm_UISetup flag is passed also each time the add-in is loaded, while in fact it is not passed each time, only the very first time (if you think otherwise, wait until the following bullet). The ext_ConnectMode.ext_cm_UISetup mode would deserve its own OnUISetup mehod rather than sharing the OnConnection method, as I explained in my post Regarding the IDTExtensibility2 interface.
  • In one of those decisions that cause more harm than good, in VS 2005 Microsoft added the /resetaddin command-line flag to the devenv.exe process in the project properties window of an add-in project to get a new ext_ConnectMode.ext_cm_UISetup phase each time that the add-in is debugged, creating the (false) impression that each time that the add-in is run, you should get an ext_ConnectMode.ext_cm_UISetup phase, and therefore the forums are populated with questions like “my add-in works on my machine, but not when I run it on other machine”, or “my add-in works on Windows XP, but not on Vista”, or “my add-in works when debugging it, but not when it runs standalone”, or “my add-in seems to work sometimes, but it seems that never on Mondays” and the like :-)

So, if you have reached this post searching for a solution for your OnConnection/ext_ConnectMode.ext_cm_UISetup problem, please read the following article of mine and the related ones at the end of it three or four times, without skipping a line of them, and then read the code samples, and then create a couple of add-ins with either approach in the samples, and then run them within Visual Studio to check that they work, and then run then outside Visual Studio, and then create a setup and run them on another machine, and all this will take you an hour or two, but you will fully understand how it works and how it doesn’t work, and why, and then you can return to the faulting code of your original add-in and it should be crystal clear for you what’s wrong :-)

HOWTO: Adding buttons, commandbars and toolbars to Visual Studio .NET from an add-in
http://www.mztools.com/articles/2005/MZ2005003.aspx