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

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.

This post is both the continuation of part I and part II installments but it also addresses new product that has shipped since VSTO 2005 SE and this is VSTO 2008 (which is also known as VSTO 3.0 - see the complete matrix of VSTOs in this post by Andrew Whitechapel ).

Here is a quick recap of the last 2 episodes:
Traditionally Microsoft Office has allowed All Users installation of COM Add-Ins by the virtue of registering the add-in under HKLM\Software\Microsoft\Office\<Application>\AddIns registry key. There were few problems with managing HKLM add-ins - in particular non-admin users could not disable an add-in explicitly as well as crashing add-ins could not have been disabled automatically for such users. So, when managed add-ins were introduced in Office 2007 it was decided to break the cycle and disallow registering managed add-in under HKLM.

Today only those managed add-ins registered under HKCU registry hive are activated by Office 2007. This creates a different kind of problem - "how an administrator can deploy an Office add-in so that every user on the machine can use it?".

The part I post introduced an internal Office 2007 registry replication mechanism. The very sketchy part II post described, at a very high level, how to take advantage of the registry replication and modify the VSTO 2005 SE add-ins setup projects to be deployable to all users (The technique is a mixture of moving registry keys around in the deployment project itself coupled with creating custom actions similarly to those described in Darryn's VSTO 2005 SE deployment article). As a side note: I really should have invested more time into part II and make it a full walkthrough article. Now I am paying for my laziness since I need to answer a lot of "please clarify" comments on that post. But hey, on the flip side, trying to connect the sketchy pieces together and build the nice deployment package does build character - doesn't it?

If you are just learning this stuff - please understand there is no quick fix solution and before trying what I am going to describe below - please make sure to read all 4 articles I just mentioned: start with the deployment article (which by itself consists of 2 articles, then post I and post II).

VSTO 2008 significantly improves over VSTO2005SE deployment experience by introducing ClickOnce based deployment. The idea is that, as it is the case for ClickOnce deployment of Windows Forms project, you can now "publish" VSTO 2008 projects. This will create a setup.exe file you can give to your users to deploy your VSTO add-in.

The problem is that ClickOnce is also a per-user solution. Notice that there is no such thing as ClickOnce for All Users. And, if you are an administrator running a server and you want to deploy VSTO solution to all users on your server - you really need an MSI based setup project. This is, of course, not something we do anymore in VSTO 2008.

Let's see what can be done about it though. First of all, go and take a look into samples at https://code.msdn.microsoft.com/VSTO3MSI. These samples show how to create an MSI based deployment package for VSTO 3.0. The samples target single user - not All Users - but this is a very good start.

UPDATE: The above sample has been converted into a tutorial called "Deploying a Visual Studio Tools for the Office System 3.0 Solution for the 2007 Microsoft Office System Using Windows Installer" . So, instead of starting with a sample - just click the link above and follow the steps to create the MSI-based deployment project for VSTO 3.0 add-ins.

Key difference between VSTO 3.0 MSIs and VSTO 2.0 MSIs is that security model has changed. In VSTO 3.0 we no longer rely on CAS for security - both us and our users did have their share of problems with CAS so enough is enough. This was replaced with a concept of "Inclusion List" based security. Consequently, one of the things you will find in the site above is an InclusionListCustomActions - custom actions that call InclusionList APIs to pre-trust your solution.

So, now supposedly you have followed the VSTO3MSI samples and created an MSI based deployment package.

Next step for you is to follow general guidelines in the part II article and modify this solution to use Office's replication mechanism for All User deployment by moving registry entries from HKCU under HKLM\Software\Microsoft\Office\12.0\ User Settings\MyCompany.MyAddIn\Create registry key. Also, same post describes how to add a custom action to set up Count registry value the replication mechanism is based in and as well as handling the uninstallation of the add-in.

Next step is to remove the InclusionListCustomActions - these CAs are not good for All Users deployment.

But what do you need to do instead? Read on.

“Inclusion list” is just reg entries under HKEY_CURRENT_USER\Software\Microsoft\VSTO\Security\Inclusion – notice it is under HKCU not HKLM. The format of those registry entries is pretty self-describing – we use some random GUID to create a unique entry in the list, the entry contains the path to add-ins .vsto file and manifest's public key. Although "inclusion list" APIs create these registry entries for you but only under HKCU hive. That is not good for all users deployment. Instead your setup needs to install those registry keys into HKLM\Software\Microsoft\Office\12.0\ User Settings\MyCompany.MyAddIn\Create\Software\Microsoft\VSTO\Security\Inclusion and rely on Office’s replication mechanism to copy those into HKCU.

So, first go to HKEY_CURRENT_USER\Software\Microsoft\VSTO\Security\Inclusion and find the entry in the list that pre-trusts your solution. Export this entry into a .reg file. This file should look like this:

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\Software\Microsoft\VSTO\Security\Inclusion\30b8e0dd-8ff5-4828-a53b-4933424888fd]
"Url"="file:<SOMEPATH>/ExcelWorkbook1.vsto"
"PublicKey"="<RSAKeyValue><Modulus>nPAT3uo/l/ba+L74Am8cHuxNwe50oXwpVgdKyKQOjskBkZWMMb8vcFzN91NxMj3p7CehgQeGZNuuy64wmvwiFRRq20lKXca3Iv7dkWgED6rkG20EGp4je0E1LrxdwYQg5tj5OO0gn4+nXR201tBy2BuqV1hI1ydxCPNZ+jDX+Gk=</Modulus><Exponent>AQAB</Exponent></RSAKeyValue>"

Next, change the highlighted text to

HKEY_LOCAL_MACHINE\Software\Microsoft\Office\12.0\User Settings\<MyCompany.MyAddIn>\Create

Next, change <SOMEPATH>\     to      [TARGETDIR]   and save .reg file.

Your .reg file now should look something like this:

Windows Registry Editor Version 5.00

[HKEY_LOCAL_MACHINE\Software\Microsoft\Office\12.0\User Settings\<MyCompany.MyAddIn>\Create\Software\Microsoft\VSTO\Security\Inclusion\30b8e0dd-8ff5-4828-a53b-4933424888fd]
"Url"="file:[TARGETDIR]ExcelWorkbook1.vsto"
"PublicKey"="<RSAKeyValue><Modulus>nPAT3uo/l/ba+L74Am8cHuxNwe50oXwpVgdKyKQOjskBkZWMMb8vcFzN91NxMj3p7CehgQeGZNuuy64wmvwiFRRq20lKXca3Iv7dkWgED6rkG20EGp4je0E1LrxdwYQg5tj5OO0gn4+nXR201tBy2BuqV1hI1ydxCPNZ+jDX+Gk=</Modulus><Exponent>AQAB</Exponent></RSAKeyValue>"

Go into your Visual Studio deployment project, open the Registry View, right click on "Registry on Target Machine" root node in the view and click "Import ..." to import the .reg file.

That's it - you should now have the functioning MSI based deployment package for VSTO 3.0 solution. Use it!

As usual, the post is not a complete walkthrgough and might be sketchy in parts - so if you have something to add or you have found a mistake in the post - please leave a comment.

 UPDATE: Several people has commented on this post and the the "part I" post that registry propagation does not happen when booting MS Project. I have confirmed this. The workaround is to ask users to start some other Office application first e.g. Excel or Word.