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:-)
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:
- .NET Framework 2.0 (RC1)
- Microsoft Office 2003 w/Outlook
- Microsoft Office 2003 SP1 (or later)
- Microsoft Office 2003 Primary Interop Assemblies (O2003PIA.exe) (how-to)
- Visual Studio Tools for Office Runtime (vstor.exe) (Same version as .NET Framework!)
- Language pack for vstor (Optional)
- Registry keys for Outlook plugin (fixed by default VSTO Setup project)
- 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.