Deploying your VSTO Add-In to All Users (Part I)

UPDATE March 11, 2010: Office 2010 does support deploying managed add-ins to HKLM which makes the below article a little bit outdated nowdays. There is also an optional download for Office 2007 containing the same fix. Check this article out for more details.

VSTO Add-Ins aka Managed Office Add-Ins have a major deficiency on the deployment side. Putting it simple, Microsoft has only provided guidance how to deploy these Add-Ins on per-user basis. Machine wide deployment has been our Achilles heel. In this post I will try to explain how this limitation can be worked around.

First, let's start with some background information.

Office 2007 has added built-in support for managed Add-Ins. Office applications use a Manifest registry value to differentiate between traditional COM Add-Ins and managed Add-Ins. This value can be found under HKCU\Software\Microsoft\Office\<App>\AddIns\<AddInName>.

Unlike traditional COM Add-Ins which can be deployed to all users on a machine by registering those under HKLM\ Software\Microsoft\Office\<App>\AddIns, managed Add-Ins can only be registered in HKCU registry hive (those registered under HKLM will be ignored).

It is pretty easy to create a setup package that writes registry keys into HKCU for the user invoking the setup. But setup program duplicating same sets of registry keys for every user on this particular machine requires quite advanced skills in Win32 API. Slightly more advanced skill is required to create a setup that will write those registry entries into HKCU hives of future users of the machine (this is because "template hive" is stored in C:\Documents and Settings\Default User\ntuser.dat file and is not a part of live registry, see more details at Raymond Chen's post on the topic).

There is a solution though and it is reasonably easy one. The trick is to use an internal Office mechanism for propagating registry keys from HKLM to HKCU that is performed during startup of every Office application.

For Office 2007 the magic is in the keys located under HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings. If you have an existing installation of Office 2007 you can examine the content of this registry key you will soon find out that it contains a seemingly random collection of sub-keys which all in turn have either Create or Delete sub-keys. The Create/Delete keys (which are essentially Copy/Delete instructions), in turn, have sub-keys that look like complete registry keys on their own!

What we are looking at is the HKLM-to-HKCU propagation mechanism that can be completely controlled from within the registry itself. Let's examine more closely how this mechanism is working. To start I would suggest the following exercise – copy and paste the below lines into a Notepad application, save the file as testpropagation_create.reg file and run this file to put the corresponding registry keys and values into your registry. Notice that you are adding registry keys to HKLM hive.

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation] "Count"=dword:00000001
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation\Create\Software\Microsoft\Office\TestKey]
"TestValue"="Test"

Now start Excel application. Examine the registry keys in HKCU hive e.g. you will find two interesting registry keys that appear under your HKCU hive:

  • HKCU\Software\Microsoft\Office\TestKey registry key containing registry value TestValue
  • You now also have HKCU\Software\Microsoft\Office\12.0\User Settings\TestPropagation registry key with Count value set to 1

Now, let's see how we can delete a registry key using similar mechanism. Below is the new registry script for you to run (copy&paste these lines into testpropagation_delete.reg)

Windows Registry Editor Version 5.00
[-HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation\Create] [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation]

"Count"=dword:00000002 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\TestPropagation\Delete\Software\Microsoft\Office\TestKey]

I highlighted the changes I made from the testpropagation_create.reg file. In this script we first remove the TestPropagation\Create registry key that we added earlier – notice the hyphen at the beginning of the line which indicate that this is a "delete" instruction. We also changed the Count value to 2 – in order for the instruction to execute we need to make sure that HKLM's Count value is different from HKCU's Count value. Next, Software\Microsoft\Office\TestKey is now placed under TestPropagation\Delete key – this to instructs Office to delete the registry key rather than create it.

After executing testpropagation_delete.reg file and starting Excel you will notice that:

  • HKCU\Software\Microsoft\Office\TestKey registry key is now gone
  • HKCU\Software\Microsoft\Office\12.0\User Settings\TestPropagation registry key has a Count value set to 2

Now, we have seen how Office's registry propagation mechanism works. It now becomes pretty clear how it is possible to take advantage of this behavior in your Add-In's setup. In my next post I will explain how we would go about building a custom action for VSTO 2005 SE Add-In setup package that will use this technique for machine-wide Add-In deployment.