Troubleshooting Outlook COM Addins - Introduction
I have decided to start a series called ‘Troubleshooting Outlook COM Addins’. I want to outline tips and tricks to finding the root cause of COM Addin issues. Mainly, why the Addin doesn’t load. I would say that this is the biggest call generator for our team at Microsoft so I thought having a series of blog posts about this topic may be helpful. And since I have to commonly write the same thing over and over again, it’s worth my while to blog it. Living up to the old adage of blogs “Write once, refer everywhere”. I am going to try to write down techniques that are applicable for all types of Addin implementations ( C++, VSTO, Shared COM Addins, Shim based, etc). If there are specific troubleshooting techniques for a given implementation I will make sure to note that.
Without further ado, let’s get started. I would like to start off with the Addin architecture for Office. This makes the most sense because most of the Addin code is in a shared office component called MSO.DLL and not in a particular Office product. This is important to know because that means that the techniques I offer here can be used elsewhere in other Office applications.
Office Addins use a standard COM Interface for addins. This Interface is called _IDTExtensibility2. It has 5 methods OnConnection, OnDisconnection, OnAddinsUpdate, OnStartupComplete, and OnBeginShutdown. The most commonly used methods are OnConnection and OnDisconnection. These two methods are called when the Addin is loaded and unloaded. Depending on what the LoadBehavior is of your Addin determines when these will be called.
Office uses COM to activate (create) your component. If looks at two places in the registry to determine the Addins to load. The first is at HKEY_LOCAL_MACHINE\Software\Microsoft\Office\Outlook\Addins\<ProgId> and HKEY_CURRENT_USER\Software\Microsoft\Office\Outlook\Addins\<ProgId>. In pre-Office 2007 versions the HKEY_LOCAL_MACHINE hive was used for Addins that you didn’t want to the user to know about or disable. These Addins would not be seen from the COM Addins dialog that the user can view in the respective Office application. In Office 2007 we removed this and now show all Addins. Addins registered in HKEY_LOCAL_MACHINE also enabled the ability to deploy Addins at the machine level instead of the user level. This eases deployment as well. We use the ProgId to create the component using standard COM activation via CoCreateInstance. Once created we call QueryInterface to get a pointer to the _IDTExtensibility2 interface. If that is successful we store the information we need about your Addin and then call your _IDTExtenstibility::OnConnection implementation. In the case of a VSTO solution, VSTO’s runtime engine handles this for you, initializes itself and calls into your AddIn.Startup event handler.
Now that we know the general architecture this feeds in nice into our my first troubleshooting step, which is to confirm that COM can create your component.