Misha Shneerson : Deployment

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

Misha Shneerson — Thu, 24 Apr 2008 19:24:00 GMT

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 http://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.

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

Misha Shneerson — Thu, 06 Sep 2007 09:01:00 GMT

In this post I am going to discuss how the observations made in the previous post can be incorporated into a setup project for Office 2007 Add-Ins. As with any setup we will need to address installation, un-installation and repair procedures.

Upon the installation of Add-In we will write registry keys that are similar to what testpropagation_create.reg file from the previous post contained. This installation will contain the Create instruction telling Office propagation mechanism to copy the registry key into HKCU profile.
During the uninstall, we will replace the Create instruction with Delete instruction which will cause Office to delete the corresponding registry key in HKCU hive. We will also bump up Count registry value to tell Office that the instruction needs to be carried out.
During the repair we will need to increase Count value. This will cause Office to copy over the registry values from HKLM into HKCU.

Let’s first take care of the installation of the required registry keys. The easiest way to achieve this is by slightly modifying the default setup project that is created alongside the regular VSTO 2005 SE project. Let’s create a new Excel 2007 Add-In called “MyAddIn”. You will notice that in addition VSTO has also created a companion MyAddInSetup project. Let’s open the Registry view and clear out all the registry entries that have been created for you (i.e. completely clear the contents under HKEY_CURRENT_USER). Now we are going to import the registry information as presented below. To achieve this you will need to copy the below lines into a .reg file, then right-click on “Registry on Target Machine” node, select “Import …” and import the .reg file you have just created (notice that first you might want to adjust the highlighted strings for your particular situation).

Windows Registry Editor Version 5.00
[HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Office\12.0\User Settings\MyCompany.MyAddIn\Create\Software\Microsoft\Office\Excel\Addins\MyCompany.MyAddIn]

"Description"="MyAddIn -- an addin created with VSTO technology"
"Manifest"="[TARGETDIR]MyAddIn.dll.manifest"
"FriendlyName"="MyAddIn"
"LoadBehavior"=dword:00000003
"CommandLineSafe"=dword:00000001

After you complete this operation your Registry View should be very similar to this screenshot :

By adding above entries into Registry View we ensure that corresponding keys will be removed when Add-In is uninstalled. I would also suggest to set Create's key “DeleteOnUninstall” property in the Properties Window to True to make sure it is always deleted on uninstall .

Notice that now we need to add a Count value under the MyCompany.MyAddIn key. Using the Registry View to add this value would not work because any registry keys and values added through this view will be removed on uninstall. On opposite, we need Count value not just stay when Add-In is uninstalled, but its value should be incremented.

To achieve the desired effect we will create a Custom Action that will add Count value or, in case it already exists, we will simply increment its value.

Similarly, Custom Action will create a "Delete" instruction when Add-In is uninstalled.

Below I am showing code that Darryn Lavery (who put tremendous amount of effort to design and validate all I am talking about right now) has already written for his future MSDN article on this (yeah, there will be an MSDN article with the full how-to instructions) and he kindly shared it with me and I shamelessly sharing it you, but credit sitll belongs with Darryn.

Now let's move close and see how the particular Custom Action code could look like. First, let's start defining a class RegisterOffice2007AddIn with a couple of private methods:

class RegisterOffice2007AddIn {

#region private methods

private const string userSettingsLocation = @"Software\Microsoft\Office\12.0\User Settings";

public void IncrementCounter(RegistryKey instructionKey) {

int count = 1;

object value = instructionKey.GetValue("Count");

if (value != null) {

if ((int)value != Int32.MaxValue)

count = (int)value + 1;

}

instructionKey.SetValue("Count", count);

}

private string GetApplicationPath(string applicationName) {

switch (applicationName.ToLower()) {

case "excel":

return @"Software\Microsoft\Office\Excel\Addins\";

case "infopath":

return @"Software\Microsoft\Office\InfoPath\Addins\";

case "outlook":

return @"Software\Microsoft\Office\Outlook\Addins\";

case "powerpoint":

return @"Software\Microsoft\Office\PowerPoint\Addins\";

case "word":

return @"Software\Microsoft\Office\Word\Addins\";

case "visio":

return @"Software\Microsoft\Visio\Addins\";

case "project":

return @"Software\Microsoft\Office\MS Project\Addins\";

default:

throw new Exception(applicationName + " is not a supported application", null);

}

# endregion

The code above contains helper method IncrementCounter that is responsible for correctly updating the Count registry value. GetApplicationPath helper method returns application-specific path Add-Ins registration key. Now, we are ready to move to the top-level function that will be called during Install and Repair:

public void RegisterAddIn(string addInName) {

RegistryKey userSettingsKey = null;

RegistryKey instructionKey = null;

try {

userSettingsKey = Registry.LocalMachine.OpenSubKey(userSettingsLocation, true);

if (userSettingsKey == null) {

throw new Exception("Internal error: Office User Settings key does not exist", null);

}

instructionKey = userSettingsKey.OpenSubKey(addInName, true);

if (instructionKey == null) {

instructionKey = userSettingsKey.CreateSubKey(addInName);

} else {

// Remove the Delete instruction

try {

instructionKey.DeleteSubKeyTree("DELETE");

} catch (ArgumentException) { } // Delete instruction did not exist but that is ok.

}

IncrementCounter(instructionKey);

} finally {

if (instructionKey != null)

instructionKey.Close();

if (userSettingsKey != null)

userSettingsKey.Close();

}

In the above method, we first make sure the "Delete" instruction is gone and then we increment the Counter value. Notice that "Create" instruction is not explicitly installed by the Custom Action - this is handled by the installer automatically because of our previous work with the Register View.

And, finally, the function that will be called during uninstall:

public void UnRegisterAddIn(string applicationName, string addInName) {

RegistryKey userSettingsKey = null;

RegistryKey instructionKey = null;

RegistryKey deleteKey = null;

try {

userSettingsKey = Registry.LocalMachine.OpenSubKey(userSettingsLocation, true);

if (userSettingsKey == null) {

throw new Exception("Internal error: Office User Settings key does not exist", null);

}

instructionKey = userSettingsKey.OpenSubKey(addInName, true);

if (instructionKey == null) {

instructionKey = userSettingsKey.CreateSubKey(addInName);

} else {

// Make sure there is no Create instruction

try {

instructionKey.DeleteSubKeyTree("CREATE");

} catch (ArgumentException) { } // Create instruction did not exist but that is ok.

}

string instructionString =

@"DELETE\" +

GetApplicationPath(applicationName) +

@"\" +

addInName;

deleteKey = instructionKey.CreateSubKey(instructionString);

IncrementCounter(instructionKey);

} finally {

if (deleteKey != null)

deleteKey.Close();

if (instructionKey != null)

instructionKey.Close();

if (userSettingsKey != null)

userSettingsKey.Close();

}

This is pretty much it. Assuming you have already experimented with SetSecurity Custom Action you should be able to wrap this code into a Custom Action DLL, set CustomActionData properties as /addinName="MyCompany.MyAddIn" /application="Excel" (again choose the value that fit your particular case), and invoke the above methods on Install, Uninstall and Rollback. I will try to sum it all up in another post though.

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

Misha Shneerson — Wed, 05 Sep 2007 04:08:00 GMT

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.

Must read for everyone trying to deploy VSTO solutions

Misha Shneerson — Fri, 06 Jan 2006 09:21:00 GMT

I am breaking the silence to get the word out (to those loyal souls that still aggregate my blog) about 2 articles on VSTO deployment. First article is an in depth overview of VSTO deployment models and proposed solutions. The second one is a complete walkthrough for setup project creation with code samples. Most important - this is a must read for every VSTO developer. If your setup does not install pre-requisites - tons of people won't be able to use your add-in. If your setup does not make sure PIAs are on the machine - tons of people won't be able to use your add-in. If your setup does not deploy CAS policies correctly - tons of people ... But If your setup does deploy CAS policy incorrectly and allows evil hackers take control over the machine - you are done (if you are not Microsoft, of course:)). The articles address all these points.

Deployment is VSTO's pain point. Part of it is because of the extremely scrutinous security model. Another part is because of our initial desire to support ClickOnce-like capabilities for offline scenarios when ClickOnce was not ready yet to support VSTO-like solutions. The above articles do not remove the pain but help controlling it. In the future we are loooking at removing it at all and making deployment complete part of VSTO experience as it should be - easy and sometimes pleasantly surprising :).

Any development in this area should not go without mentioning some excellent work that has been done by VSTO community. In the past Mads Nissen (helped by Peter Jausovec ) posted a solution for VSTO deployment. What Mads has done is very good work even though it suggested to manipulate CAS policies using the CAS APIs (Peter Torr would not be very happy about this because manipulating security APIs directly is prone to errors. And security bugs may be very costly to both you and your customer).

Finally I wanted to congratulate my colleagues Lubo, Darryn and McLean for getting this article out.