VSTO Outlook: the Complete Setup Solution

[Disclaimer: this is currently work in progress.. expect to find partial solution and some explanation]

UPDATE: Solution at the end:-)

UPDATE: http://weblogs.asp.net/mnissen/archive/2010/05/20/creating-office-add-ins-with-vsto-with-add-in-express.aspx

 

The past week has gone and it feels as if I’ve moved one inch. Started with upgrading a Beta 2 solution to RC1. Not entirely trivial. If you can create a new project and move your code as much as possible to avoid problems with the VSTO vs. VS2005 stuff.

 

This means that what you’re about to read is RC1 based. Make no assumptions on this related to neither beta 2 or RTM.

 

CAS

Code Access Security is the primary issue on deployment. A lot of people have noticed the Code Access Security installerclass I wrote earlier and now it’s updated to also handle uninstall. It also creates more logical codegroup names and the code is easy to “steal” with all settings in private strings.

 

Get the C# source here.

Get the VB.NET source here.

 

In my opinion this type of class (possibly subclassed from Installer) should be an optional item for the VSTO Outlook VS2005 project template given that FullTrust is absolutely required for them to run. I know some admin should set the CAS policy in most cases, but in a lot of scenarios this is not viable. Administrators in small companies have no clue about CAS unfortunately, and for public domain scenarios end users sure won’t have a clue.

 

CAS is sadly just a small part of the picture of getting your plugin running. Read on to learn about your days work my last weeks work:

 

Prerequisites

There are a lot of questions related to VSTO Outlook deployment. The main reason is that there are so many actions that are completed for you when you’re debugging, and the client environment is a real jungle compared to the safe grounds of your devbox. In addition any faults in the prereq setup will cause a range of errors from subtle disabling of your plugin to brutal crashes.

 

The deployment of Outlook solutions are described at msdn2 here. Prerequisites are described here.

 

In short (?!) you’ll need to make sure these things are in place for your plugin to work:

  1. .NET Framework 2.0 (RC1)
  2. Microsoft Office 2003 w/Outlook
  3. Microsoft Office 2003 SP1 (or later)
  4. Microsoft Office 2003 Primary Interop Assemblies (O2003PIA.exe) (how-to)
  5. Visual Studio Tools for Office Runtime (vstor.exe) (Same version as .NET Framework!)
  6. Language pack for vstor (Optional)
  7. Registry keys for Outlook plugin (fixed by default VSTO Setup project)
  8. Code Access Security FullTrust grant to your assemblies

Any developer with normal instincts should react to this. So many things which are not in your power can make you get the blame for your software not working. This calls for some validating action.

 

The new VS2005 Setup Bootstrapper

In Visual Studio 2005 there is a new kid in town called the Bootstrapper. It’s revamped to handle more than just the .NET Framework and it’s customizable. MSDN Magazine posted an article which will give you the picture.

 

The idea here is to create and add Custom Prerequisites for everything that your plugin can possibly require to run. In my case I want to assert that the install only can run if the list above is verified. I also want to enable the user to install the missing parts with ease (at least the publicly available components) by deploying prerequisites either with my application or allowing for them to be downloaded from the vendor.

 

In my opinion custom prerequisites (at least validators) should be provided for Office related installs as part of the VSTO development experience. As you will learn, custom prerequisites is not really fun not that bad.

 

First go at Custom Prerequisites in Visual Studio 2005

I started out creating custom prerequisites for the Office 2003 PIAs and the VSTO Runtime.

 

Custom Prerequisites are defined in two main xml files located on the development box under the directory “\Program Files\Microsoft Visual Studio 8\SDK\v2.0\BootStrapper\Packages\”.

 

The main part of the template is a product.xml file and a package.xml file. Their schema is described here, but it seems like the documentation is somewhat out of sync with the RC1 bits. The templates can define do various checks and install prerequisites. You can define search for registry keys, the filesystem, search for assemblies in the GAC and so forth. You can also define validation rules on operating system and usermode (admin). Anything you can’t do out of the box can be done by writing an unmanaged util to do some checking and calling it from the custom prerequisite (like dotnetfxchk.exe). All in all you’ve got the tools to validate things before the bootstrapper allows your msi to run.

 

The custom prerequisites will appear in the Prerequisites dialog (click to view) of the Setup Project properties.

 

My current templates can be downloaded here and here. Currently they got a couple of problems causing them not to install prereqs, but you’ll get the idea of the xml format. Be aware of the references between elements. For example the DisplayName attribute of the Package element refers to the String element with the Name attribute set to DisplayName.

 

There also seems to be some overlap that I do not yet comprehend between the product.xml schema and the package.xml schema. The package.xml is for localized stuff. Try only using this for strings as long as you can. The rest goes into the product.xml.

 

When you’ve selected the prerequisites the Setup Project will include them in the bootstrapper setup.exe file. The setup.exe will then assert all the rules of the prerequisites before running the msi.

 

I’ve created custom prerequisites for “O2003PIA.exe” and “vstor.exe”. You can have a look at them here and here. To test them you’ll need to extract to the directory mentioned above and add the binaries yourself. Links to download are in the package.xml files.

 

They’re not completely functional yet, and I’m hoping to get some feedback on them.

 

The problem right now is that the bootstrapper don’t run the prerequisite packages, neither if I include them with the install or direct to vendors website. I suspect there is something wrong in the package.xml files. The log from the install not behaving but calling at least one of my custom prerequisites can be found here.

 

Friday night: to be continued…

 

UPDATE: Saturday morning: Peter Jausovec modified the vstor custom prerequisite and now it downloads from the appropriate url. However, the install fails because the publishers url cannot be verified. Peter is pulling the binary straight off Microsoft and he is reusing the public key I appended to my xml. This public key is simply the same as for many other microsoft packages and I was uncertain about how to obtain it. All exes published by Microsoft have a certificate associated however, and they tend to have the same Public Key.  

 

Peter had the same problems as I did with the AssemblyCheck task in the prerequisite. Problem is that when a component is not found in the gac is that the property is not set. An option for checking this in package.xml would be to do a <BypassIf Property="propAssemblyCheckMightHaveSet" Compare="ValueExists" /> in the InstallConditions.

 

It's saturday afternoon: to be continued...

 

Wednesday: The solution

 

Finally with the help of Peter and Bob I've made a complete set of Custom Prerequisites to make it completely impossible to get a VSTO solution installed without all the prereqs in place. This solves bulletpoints 1-7 above:

 

Get the solution here: Custom Prerequisites for Office 2003 (SP2), Outlook 2003 (SP2), Office 2003 PIA, Visual Studio Tools for Office 2005 Runtime

 

Included in this package are prerequisite definitions enabeling you to have the setup fail for missing Office 2003 with SP2 or only missing Outlook 2003 with SP2. The reason why it's all SP2 when VSTO really requires only SP1 is that I simply didn't locate the correct version number for SP1. Feel free to add your own SP1 prerequisites.

 

The prerequisites for Office does not (for not-going-to-jail reasons) include any binaries and simply fails setup if stuff is not in place. If you've selected "Download missing components from vendors website" for your setup project it will simply redirect to http://office.microsoft.com. You can easily customize the prerequisites for internal use to make them force install of Office 2003/SP2/Outlook from a network share if required. I really just wanted it to fail if it was missing (*stupid end-user installing a Outlook plugin without Office*).

 

The prerequisites for VSTO (pias and vstor) supports both the download from vendor and download from same location models. You'll need to supply the VSTOR.EXE and O2003PIA.MSI if you want to set up your installer for download from same location. I've included placeholderfiles in the package. Note that O2003PIA is distributed in a compressed EXE format which tends to autoinstall when you run it. Try winzip (I got a hold of the msi after running the exe through the bootstrapper which unzipped it instead of installing it).

 

After doing all this the prerequisites dialog of your setup projects property window should come up more or less like this:

 

 

For a VSTO Outlook solution you really only need the Microsoft Office Outlook 2003 (SP2) prereq, but I thought the office one would be nice to include aswell.

 

Finally you'll still need to cover bulletpoint 8 above, so get the CAS code and include it in your VSTO project as a separate sourcefile and make sure you call it through a CustomAction in your setup project. 

 

Get the C# source here (VB.NET version will be posted happily if anyone cares to translate!).

 

Troubleshooting

Make sure you're on the right version. This is done on pure RC1 stuff. If you've ported a beta2 project make sure to correct your registry settings in the setup project to reference the new AddinLoader.dll file and that you remove any added dlls (that you might have done by my advice or maybe from KjellSJ).

 

A final note on Custom Prerequisites

Although custom prerequisites and the boostrapper feature of VS2005 is an incredible powerful feature I feel it's misplaced. Application prerequisites are not a part of the development machine nor the IDE, it's a part of the solution. I would really like to see how this could be integrated with sourcecontrol and used for automated builds of setup projects. Hopefully MSBuild has features for compiling bootstrappers and parsing custom prerequisite definitions (haven't researched that yet). Ideally Custom Prerequisites should have been a Item type in visual studio that could be added to a setup project, but then again, the setup project really needs a makeover anyways.

 

Comments

# KjellSJ said:

Thanks for making this work and sharing with the community. It's a pity that Microsoft does not provide these essential parts of a professional product deployment themselves.

Wednesday, October 26, 2005 2:39 PM
# Digvijay said:

Hi,

I am developing a Outlook 2003 Addin in VS2005/.NET 2.0. Now when i needed to deploy it i landed at this page. It really gives a nice introduction and pointers to deployment and related issues.

However, i downloaded the solution and did exactly as asked but i could not get the Office 2003 PIA, Office 2003, Office 2003 SP1 in the prerequisite dialog.

Any idea how can that happen and how to correct it? I have VS 2005 and Office 2007 only. I have not installed office 2003 at all.

Regards,

Digvijay

Wednesday, August 22, 2007 12:07 AM
# Planza said:

Thanks for the info. Your site was the best resource that I have found for information on deploying VSTO add-ins.

Friday, September 21, 2007 11:33 AM
# Simon said:

I seem to have a problem following the links in this post... says some dll is missing!

Wednesday, November 21, 2007 8:13 AM
# Sven Cipido said:

I have created a VSTO app in VS2005 to Word2003.  After creating the msi, it installs.  But when opening the DOT file, the action pane doesn't come up.  If I run the DOT file from within VS, there's no problem.

So, do you have a solution for this problem ?

txs in advance.

Thursday, November 29, 2007 10:04 AM
# John said:

Boy is using .Net and Office a MESS!!!

Friday, December 21, 2007 10:39 AM
# Oleh said:

Mega useful article!!!

Wednesday, January 9, 2008 10:16 AM
# Søren said:

Hi.

Great article!

When trying the download link (for the solution), I am prompted for credentials for the web server?

/Søren

Wednesday, January 16, 2008 3:02 AM
# saurabh kumar singh said:

dear sir

              it,s password protected how can i download it

Thursday, January 31, 2008 5:07 AM
# Tjaard said:

The pictures do not load and I cannot download anything, could you please put them up again?

Tuesday, February 12, 2008 10:38 AM
# jerry said:

Yeah... what happened to the sample? :(  

Sunday, May 18, 2008 3:51 AM
# thexray said:

what a bummer... :(

Thursday, June 26, 2008 9:47 AM
# chnswam2 said:

Hi,

I have developed a VSTO SE Outlook 2007 add-in with Visual Studio 2005.

I used the default setup project to create the setup files.

Upon installation, the Add-in works fine in all operating systems, except Windows Vista :(

The add-in doesn't load. To check, when I view it in the ‘Tools->Trust center->Add ins->Com Add-in’ of Outlook 2007, the message it gives is "Load Behavior: Not loaded.The Managed Add-in Loader failed to initialize"

I have implemented CAS too. I have also created a project called "SetSecurity" to use Caspol to give FullTrust permissions for all the assemblies.

In my SetSecurity Project, in a file called CaspolSecurityPolicyCreator.cs, I have the following code:

// Add the solution code group. Grant no permission at this level.

           string arguments = policyLevel + " -q -ag " + parentCodeGroup + " -url \"" + solutionInstallationUrl + "\" Nothing -n \"" + solutionCodeGroupName + "\" -d \"" + solutionCodeGroupDescription + "\"";

As it says, not granting trust at this, is that the problem?

If so how to grant trust at this level too?

Any ideas/suggestions from anyone on how to get it to work under Vista?

(Chandra.Mohan@skelta.com)

Thursday, August 28, 2008 9:51 AM
# chnswam2 said:

Hi,

I have developed a VSTO SE Outlook 2007 add-in with Visual Studio 2005.

I used the default setup project to create the setup files.

Upon installation, the Add-in works fine in all operating systems, except Windows Vista :(

The add-in doesn't load. To check, when I view it in the ‘Tools->Trust center->Add ins->Com Add-in’ of Outlook 2007, the message it gives is "Load Behavior: Not loaded.The Managed Add-in Loader failed to initialize"

I have implemented CAS too. I have also created a project called "SetSecurity" to use Caspol to give FullTrust permissions for all the assemblies.

In my SetSecurity Project, in a file called CaspolSecurityPolicyCreator.cs, I have the following code:

// Add the solution code group. Grant no permission at this level.

           string arguments = policyLevel + " -q -ag " + parentCodeGroup + " -url \"" + solutionInstallationUrl + "\" Nothing -n \"" + solutionCodeGroupName + "\" -d \"" + solutionCodeGroupDescription + "\"";

As it says, not granting trust at this, is that the problem?

If so how to grant trust at this level too?

Any ideas/suggestions from anyone on how to get it to work under Vista?

Chandra Mohan

(Chandra.Mohan@skelta.com)

Thursday, August 28, 2008 9:51 AM
# Nick said:

Hello!

For [chnswam2]: First do You need to set full trust on just an assembly? You need to know that SetSecurity sets FullTrust only over just 1 assembly by default, you need to modify the project to set up full trust for more assemblies. Or, just to test it to see that this is the problem, You can change "Nothing" in string arguments = policyLevel + " -q -ag " + parentCodeGroup + " -url \"" + solutionInstallationUrl + "\" Nothing -n \"" + solutionCodeGroupName + "\" -d \"" + solutionCodeGroupDescription + "\"";

with "FullTrust". Anyway, this is not recommended to do on a client(end user) machine because every assembly put in that location will grant Full Trust. Just for testing ok but change back to "Nothing" after.

I dunno If I was very clear.

Regards,

Nick

Friday, October 3, 2008 8:45 AM
# Mark B said:

We have an Outlook 2007 Add-in.

We want to make the installer completely silent and include all pre-requisites in it:

-VSTO

-.Net 3.5

-The Add-in itself

I haven't learned about Trust levels . We want the setup.exe available for download on the internet to a variety of companies (commercial app) so it needs to be seemless, robust etc so network admins could easiult roll it out to all their Outlook 2007 boxes.

How can we make it silent and install everthing O

K?

Saturday, November 1, 2008 2:00 AM
# KOrayem said:

All download links aren't working

Thursday, December 11, 2008 10:48 PM
# ... said:

Interessante Informationen.

Friday, March 6, 2009 1:34 PM
# Bandya said:

I am surprised with the 5th requirement for the prerequisites above there. For Outlook 2003 add-on's you must install VSTO 2005 tools for Office runtime (VSTO 2005 SE) without which the add-on will refuse to load at first place. It won't run on VSTO 3.0 runtime.

I would request you to update this. It doesn't matter what version of .NET framework you have vs. what version of VSTO runtime you install. What all is dependent is that for OL 2003 -> VSTO 2005 runtime & OL 2007 -> VSTO 2008 runtime (VSTO 3.0 runtime) is required. Add-on's won't work in a cross case.

Monday, October 12, 2009 2:23 AM
# Arjun K said:

We have an Word 2003 Add-in.

We want to make the installer completely silent and include all pre-requisites in it:

-VSTO

-.Net 3.5

-The Add-in itself

The Net3.5 and the add-in is getting installed on the client m/c but VSTO is not installed .. so the addin is not working . We need to run vsroe.exe manually and then only plugin works.

- In the prerequisites of the  setup exe are as follows -

Microsoft Visual Studio 2005 Tools for Office Second Edition runtime

-. installation location is selected as - Download prerequisites from the component vendor's web site

Is there any other setting available in set up where we can force to download VSTO before installation.

Tuesday, March 30, 2010 5:50 AM
# Frode Nilsen said:

Fix link please. CustomPrerequisites_Final.zip.

Almost five years later, developing Office plugins is just as frustrating as then. Can't belive this sh*t.

Thursday, May 20, 2010 3:27 PM
# ipad said:

I still can't get it right, can't update ;(

Anyone care to share how to fix it? It is so frustrating for me, I need it to be working immediately...

Monday, August 16, 2010 1:50 PM