Mathias Brandewinder on .NET, F#, VSTO and Excel development, and quantitative analysis / machine learning.
by Mathias 15. July 2010 12:14

Time to wrap this series on VSTO add-ins for Excel 2007. Now that we have a working application-level add-in, we want to deploy it on the user machine. There are two ways to do that: ClickOnce and Windows Installer. In this post, I will go over creating a basic installer using Windows installer with Visual Studio 2008. Very soon, we’ll have a VIP guest blogger who will tell you all you need to know about ClickOnce deployment and VSTO.

This post borrows heavily from the Microsoft white paper linked below, which is absolutely excellent. I mostly paraphrased it, focusing on the how and not the why. I strongly encourage you to go to the source and read it for more details:

Deploying a VSTO 3.0 Solution for Office 2007 System Using Windows Installer

The white paper comes with sample code, covering a few scenarios:

VSTO installer sample code 

Note: the following applies to Office 2007 projects. If your add-in needs to run on Excel 2003, you should follow this guidance instead: Deploying VSTO Solutions Using Windows Installer (Part 2 of 2)

Surgeon General Warning: prolonged reading of material pertaining to msi deployment can cause drowsiness or confusion; absolutely no risk whatsoever of euphoria is to be expected.

This post is not going to be sexy. My goal is to have a check-list of what to do to get your add-in to install correctly. The steps require no thinking, and are frankly rather boring. I find some steps pretty obscure, and recommend patience and soothing music; you may consider also having  some sacrificial offering ready to appease the Great Installer Voodoo deity (a nice chicken will usually do). 

Prepare the add-in

We will start from where we left off, with a working add-in (download the add-in here). Let’s first fill in the fields describing our assembly, by right-clicking on the project:

ClearLines.Anakin > Properties > Application > Assembly information:

AssemblyInfo

Next, let’s set the configuration to Release, so that we feed the optimized release version to the installer. Right-click on the Solution (not the add-in project), select Configuration Manager, and set ClearLines.Anakin to Release instead of Debug.

ReleaseMode

Add a Setup project

Now we need to add a setup project to the solution. Right-click on the Solution again, select Add Project, pick Setup Project in the Other Project Types > Setup and Deployment section, and name it “AnakinSetup”:

CreateSetupProject

Next we need to tell the setup that we want to deploy the Add-In. First, we build the add-in by right-clicking the project ClearLines.Anakin, and selecting build. Then, we right-click AnakinSetup, and select Add > Project Output, and picking ClearLines.Anakin / Primary Output:

AddProjectOutput

Once this is done, you should see the following: the installer contains the output of the add-in project, as well as all the dependencies it relies on:

ProjectAndDependencies

Two other files are required with the deployment, the VSTO deployment manifest and application manifest. Let’s add these files, by right-clicking AnakinSetup > Add > Files, and browsing to ClearLines.Anakin > Bin > Release:

AddManifestFiles

Before we forget, let’s also set the Properties of the installer project: click on AnakinSetup, and in the Properties window, edit Author and Manufacturer to ClearLines, and ProductName and Title to Anakin.

Installing the prerequisites on the user machine

At that point, in our setup project, we have the Primary output of our project (the add-in dll), together with the manifest files. If you expand the Detected Dependencies folder, you will see a long list of all the dlls that the add-in requires to run. We need to make sure that these components are present on the user machine before we install the add-in; in order to do that, we will exclude these dependencies from the setup project, and have the installer check whether they are already installed on the user machine, and install them if not.

We need first to exclude these dependencies from the setup. In AnakinSetup / Detected Dependencies, select all the dependencies except for Microsoft.Net Framework, right-click, and select exclude. At that point, your project should look like this:

ExcludeDependencies

Next, we need to add these components as Prerequisites to the installer, so that it knows what to look for on the user machine. Right-click AnakinSetup > Properties, and click the Prerequisites button.

You should see a list like this one appear, with Windows Installer 3.1 and .NET Framework 3.5 already selected.

InitialPrerequisites

The complete list of prerequisites we need to add is the following:

  • Windows Installer 3.1
  • .NET Framework 3.5
  • 2007 Microsoft Office Primary Interop Assemblies
  • Visual Studio Tools for the Office system 3.0 Runtime

Usually the 3rd prerequisite, 2007 Microsoft Office Primary Interop Assemblies, is not available by default. Don’t panic if that’s the case, the next section explains how to handle that situation.

Keep the top box “Create setup program to install prerequisites components” selected, and change the install location for prerequisites to the second option, “Download prerequisites from the same location as my application”.

What if 2007 Office Primary Interop Assemblies is missing from Prerequisites?

Unfortunately, unless you are lucky, by default, this list should contain only 3 of the 4 required prerequisites, so we will have to take an extra step to make the 2007 Microsoft Office Primary Interop Assemblies (PIA in short) available in the prerequisites list. Note that this needs to be performed only once; after we are done with the next step, the PIA will be available as a prerequisite for other VSTO projects you need to deploy.

The prerequisites that populate the box come from the following location:

C:\Program Files (x86)\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages

If you open it, you will find a few folders, each corresponding to one of the items in the Prerequisites list. We need to create a similar folder for the Office PIA with the relevant contents, and drop it in that folder, so that it gets detected by Visual Studio, and added to the list.

BootstrapperPackages

First, download the sample code which accompanies the white paper mentioned earlier, from the link below, and unzip the files; the whole project should be contained in a folder named VSTO_v3_Deployment_Whitepaper_downloads:

VSTO installer sample code download

For convenience, I’ll rename that folder, and the one inside it, Sample.

Then, download the Redistributable Primary Interop Assemblies for the 2007 Microsoft Office System from here. Running it extracts a file called o2007pia – copy that file in Sample/Sample/Packages/Office2007PIA:

Office2007PiaInPackage

In the sample project we downloaded, there is a folder named projects/ComponentCheck, which contains a file ComponentCheck.cpp. We need to build that C++ file and add the output to the Office2007PIA folder where we just added the o2007pia file. To do this, launch the Visual Studio 2008 Command Prompt from the start menu:

VisualStudioCommandPrompt

Navigate through the folders (using cd myfolder to navigate in a folder, cd .. to navigate up a level, and dir to display the contents of a folder) until you are located in the folder that contains ComponentCheck.cpp; at that point, your console should look similar to this:

Console

Type in the following instructions after the prompt:

cl.exe /Oxs /MT /GS ComponentCheck.cpp advapi32.lib

ConsoleAfterBuild

This will build ComponentCheck.exe in the same folder where ComponentCheck.cpp was located. Close the console, copy that file to Sample/Sample/Packages/Office2007PIA, and copy the folder Office2007PIA and its contents (ComponentCheck.exe, o2007pia.msi, product.xml, and the /en folder) to C:\Program Files (x86)\Microsoft SDKs\Windows\v6.0A\Bootstrapper\Packages, with the other prerequisites packages.

Note: when I first tried this step, it failed miserably; it took me a bit to realize that I had installed Visual Studio 2008 with C# and VB.NET only, because I never work with C++, and there was no compiler to do the job…

We are now done – when you click the Prerequisites button, the Office 2007 primary interop assemblies will show up in our list, and you can go back to the previous section and complete adding the correct 4 prerequisites to the setup project.

Configuring the registry keys

Right-click AnakinSetup, select View> Registry; you should see an editor looking like this:

InitialRegistry

In HKEY_LOCAL_MACHINE > Software, right-click on the [Manufacturer] key and select delete.

In HKEY_CURRENT_USER > Software, right-click on the [Manufacturer] key and select delete.

In HKEY_CURRENT_USER > Software, right-click and select Add; rename the item named New Key #1 to Microsoft. Repeat the same process, until you have a chain looking like this: HKEY_CURRENT_USER\Software\Microsoft\Office\Excel\Addins\ClearLines.AnakinAddIn

IntermediateRegistry

The final element of the chain, ClearLines.AnakinAddIn, is the key for the add-in. That name should be unique, and a convention like ManufacturingCompany.AddinName is a good approach to avoid collisions.

Note that I named the key for the add-in ClearLines.AnakinAddIn, and not ClearLines.Anakin. I found out the hard way that if the name of the key was the same as the name of the assembly, when running the build, the value for the Manifest (see next paragraphs) was getting corrupted, and mysteriously replaced by ClearLines.Anakin.dll.Manifest – which then prevented the correct installation.

Right-click ClearLines.AnakinAddIn, select New > String Value, and name the new value Description. Right click Description, select Properties Window, and set the Value to Anakin AddIn.

Similarly, create 3 more entries, to end up with the following list:

Type Name Value
String Description Anakin AddIn
String FriendlyName Anakin AddIn
DWORD LoadBehavior 3
String Manifest [TARGETDIR]ClearLines.Anakin.vsto|vstolocal
(where ClearLines.Anakin.vsto is the VSTO deployment manifest file, one of the 2 files we added to the setup project earlier on)

At that point, you should see something like this:

FinalRegistry

Finally, right-click the key ClearLines.AnakinAddIn > Properties Window, and change DeleteAtUninstall to true, so that the key gets removed if the add-in is uninstalled.

Adding Installer launch conditions

When we build our installer, we will get two files: a msi file, which installs the add-in itself, and a Setup file, which when executed will check for the prerequisites, install them if need be, and then run the msi to install the add-in. One potential pitfall is that the user could inadvertently run the msi before running the setup, which would install the add-in without the necessary prerequisites, and result in a potentially non-working add-in. In order to avoid that issue, we will add launch conditions to the msi, preventing it to run if the proper prerequisites are not here.

Let’s add first a check for the VSTO 3.0 runtime. Right-click AnakinSetup, and select View > Launch Conditions.

Right-click Requirements on Target Machine, click Add Registry Launch Condition. This will add an entry Search for RegistryEntry1 search condition; right-click it and select Properties Window. In the properties window, modify the fields to:

(Name) Search for VSTO 3.0 Runtime
Property VSTORUNTIME
RegKey

Software\Microsoft\vsto runtime Setup\v9.0.21022

Root vsdrrHKLM
Value Install

At that point, you should see something like this:

InitialLaunchCondition

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Right-click the Condition1 entry, select Properties Window, and edit the fields to

(Name) Verify VSTO 3.0 Runtime availability
Condition

VSTORUNTIME = "#1"

InstallUrl  
Message

The Visual Studio Tools for Office 3.0 Runtime is not installed. Please run Setup.exe.

Now let’s add a check for the Office Excel 2007 PIA. In a similar fashion, right click Requirements on Target Machine, and select Add Windows Installer Launch Condition. Right-click Search for Component1 > Properties Windows, and edit the fields to

(Name)

Search for Office Excel 2007 PIA

ComponentId {1ABEAF09-435F-47D6-9FEB-0AD05D4EF3EA}
Property HASEXCELPIA

Edit then the corresponding Condition1 in the Property Window to

(Name) Verify Excel 2007 PIA availability
Condition HASEXCELPIA
InstallUrl  
Message A required component for interacting with Excel 2007 is not available. Please run setup.exe.

Finally, let’s add a check for Office 2007 Shared PIAs. Right click Requirements on Target Machine, and select Add Windows Installer Launch Condition. Right-click Search for Component1 > Properties Windows, and edit the fields to

(Name)

Search for Office 2007 Shared PIA

ComponentId {FAB10E66-B22C-4274-8647-7CA1BA5EF30F}
Property HASSHAREDPIA

Edit then the corresponding Condition1 in the Property Window to

(Name) Verify Office 2007 Shared PIA availability
Condition HASSHAREDPIA
InstallUrl  
Message

A required component for interacting with Excel 2007 is not available. Please run setup.exe.

At that point, you should see something like this:

FinalLaunchConditions

These are the 3 checks that will be performed by the msi when run; if one of the 3 components is missing, the installation will fail, and display the corresponding Message we defined in the Launch Condition.

Set the add-in installation folder

By default, VSTO add-ins for Office 2007 are intended to be installed for a single user. If you need to install for all users, this post describes how to do it; I’ll stay on the path of least resistance, and go for the single-user scenario.

The installation wizard, by default, displays a checkbox asking if the installation is for all users. We should disable that. Right-click AnakinSetup > View > User Interface; you should now see a series of nodes, representing the screens of the installation wizard (which you could edit to have a customized installation wizard). For now, select the Installation Folder screen, and in the property window, set InstallAllUsersVisible to False.

Finally, let’s specify that the add-in should be installed in a target folder where the user doesn’t require administrative privileges. Right-click AnakinSetup > View > File System, right-click the Application Folder and in the Properties Window, edit DefaultLocation to [AppDataFolder][Manufacturer]\[ProductName]. This will install the add-in in the folder C:/User/Mathias/AppData/Roaming/ClearLines/Anakin (note that this folder is hidden by default).

Build and install the add-in

We are now ready to build and install the add-in! Right-click on AnakinSetup, and Build, which will hopefully end up with Build Succeeded. Go to the folder where your solution is located, and in ClearLines.Anaking/AnakingSetup/, you should see a Debug folder, with the following contents:

DebugFolder

This is your installation package, which you can now distribute to a user. The user should run Setup.exe, which will check for the prerequisites, use the installers in the 4 folders to install missing prerequisites if any, and then run AnakinSetup.msi to install the add-in itself.

I purposefully removed the VSTO redistributable (VSTOR 3.0) from my machine to illustrate what happens when prerequisites are missing. First, let’s try to run the msi without using the setup:

MissingRuntime

As expected, the installation is blocked. Now let’s run the Setup; this time, we get prompted to install the missing prerequisites:

VstoPrerequisitesInstallation

 

Once all the prerequisites are installed, the msi installation wizard begins, and walks us through the steps that we saw earlier in the setup user interface:

SetupWizard

Once the installation completes, if we navigate to the AddData folder, we can see that a folder has been created for the add-in, which contains the add-in dll and the 2 manifest files:

InstallationFolder

 

The first time we fire up Excel, the following message box will show up; the add-in is already installed, but Excel needs to know whether it is safe to execute it:

TrustingTheAddIn

Once this last step is completed, our add-in is now present in the Review tab:

RunningAddIn

 

We can also check that the add-in is up and running by clicking the upper-left corner of Excel (the Office logo) > Excel Options > Add-Ins:

InstalledAddIn

That’s it – we have now created a full Excel 2007 VSTO add-in, with a basic installer which we can redistribute to the users. The code at that stage can be downloaded here. Again, I recommend that you check the VSTO deployment white paper, which is absolutely excellent, and covers more advanced scenarios in part 2 – as well as this collection of deployment related links on the VSTO forum. Please do let me know if you have comments, questions or remarks, and stay tuned for a post explaining how to use ClickOnce instead of Microsoft Installer – with a very special mystery guest!

Comments

7/15/2010 8:25:05 PM #

Tobias Viehweger

Awesome... Thank you so much, I spend 2 days with building an installer (by following the guide on msn), but only had problems.. This one works like charm (even for Outlook addins, only few changes have to be made (i.e. exchange component id for the pia's)..
Thanks!

Tobias Viehweger Germany | Reply

7/16/2010 5:06:24 AM #

Mathias

Thanks Tobias! Deployment is where I have had most of my issues with VSTO; there is documentation, but finding it is not always easy. I wanted a checklist for my own sanity, and I am very glad it was helpful to you!

Mathias United States | Reply

7/16/2010 2:03:28 AM #

ross

Great post!

But what a lot of work! wow!!!

ross United Kingdom | Reply

7/16/2010 5:21:44 AM #

Mathias

Thank you Ross. You know what's more painful than deploying a VSTO project? Writing a blog about deploying a VSTO project Smile In all honesty, the good parts of the post owe a lot to the whitepaper I reference, which is awesome. But this was a bear to write anyways - there is a reason why I postponed writing it for nearly 2 months - because I wanted to be  very explicit (I have been stumped on the most trivial, tiny details), and because checking that things work with an installer is VERY tedious (I did lots of juggling with virtual machines lately!). So thank you for the positive feedback!

Mathias United States | Reply

8/20/2011 1:21:16 PM #

Sam

Mathias,
Excellent piece and everything works fine. As someone used to VBA, just wondering if all the work is worth the hassle. Would be good if you did the same for AKIN.

cheers
Sam

Sam Australia | Reply

7/25/2010 9:24:49 PM #

XL-Dennis

Mathias,

Kudos for publishing the article and for not giving up. In the future when I referencing MSFT's whitepaper I will add a link to this article as well.

Thanks,
Dennis

XL-Dennis Sweden | Reply

7/26/2010 3:47:15 PM #

Mathias

Thanks for the encouragement! This one was a bear to write. I am really looking forward to read what my friend will write on ClickOnce; I confess I never used it, and keep hearing it's much easier,not hard to believe because msi sets the bar pretty low...
Havent' seen many posts from you lately, are you busy with projects?

Mathias United States | Reply

7/26/2010 10:44:53 PM #

XL-Dennis

Mathias,

Once You see what he/she will write You will wonder why You did all that hard work with this article Wink

Yes, I'm very busy at the moment.

Kind regards,
Dennis

XL-Dennis Sweden | Reply

7/28/2010 3:43:51 PM #

trackback

Excel 2007 VSTO add-in: table of contents

Excel 2007 VSTO add-in: table of contents

Clear Lines Blog | Reply

8/26/2010 6:20:01 PM #

Vladimir Mihov

Great article, helped me out a lot.
I have just one comment: in the registry in my case the DWORD item is not "ValueLoadBehavior", but just "LoadBehavior" (without the leading value).

Thanks a lot Smile

Vladimir Mihov Bulgaria | Reply

9/4/2010 6:19:50 AM #

Mathias

Hi Vladimir,
Thank you for the catch, this is indeed a typo, which I will fix! And I am glad this helped.
Mathias

Mathias United States | Reply

12/3/2010 2:22:31 AM #

Jr

I have done everything mentioned here.
After building my setup project and running the files I can see that the add-in has been added to my add/remove programs, and all of the files are stored in my destination folder. However the addin does not load when I start the application and it is not stored in the list of addins. Where might I be going wrong ?

Jr United Kingdom | Reply

8/1/2011 1:33:27 AM #

Sn

I am facing the same problem. Were you able to resolve it?

Sn United States | Reply

12/11/2010 4:48:59 AM #

nathan

I cant find the two manifest file :-
VSTO deployment manifest and application manifest.

Please help me anyone. Im using Visual Studio 2010.

nathan United States | Reply

12/12/2010 11:20:17 PM #

standard

My problem is that after I install the file, the add-in appears in the 'inactive application add-ins" How can I make it active

standard United Kingdom | Reply

12/22/2010 3:47:52 PM #

hengchengfei


when I execute the command:

>cl.exe /Oxs /MT /GS ComponentCheck.cpp advapi32.lib

'cl.exe' is not recognized as an internal or external command,operable program or batch file.

why?

hengchengfei People's Republic of China | Reply

12/22/2010 3:50:49 PM #

hengchengfei

I use VS2008.

help me!

hengchengfei People's Republic of China | Reply

11/2/2011 2:31:41 AM #

David Pendry

Great post..

Really helped me out & saved me a few days work..

Keep up the blogging.

David

David Pendry United Kingdom | Reply

1/6/2011 9:58:03 AM #

Michael

Awesome post Mathias... I discovered a lot about setup projects which I wasn't aware of.  I'm glad I stumbled onto your blog, lots of other good stuff on Excel and VSTO.

Michael United States | Reply

2/20/2011 8:55:57 AM #

trackback

Excel 2007 VSTO add-in: table of contents

Excel 2007 VSTO add-in: table of contents

Clear Lines Blog | Reply

7/26/2011 1:13:55 PM #

Sajan Maharjan

I created a VSTO AddIn for excel 2007. Now i want that add In to work in office 2010 as well. It should have run as i heard that 2007 is compatible with 2010.
Is there something that i am missing? i successfully created the Setup as done above.

Sajan Maharjan Nepal | Reply

8/28/2011 9:15:05 PM #

Aravind

Hi,
I have created a  excel add in and deployed successfully.
But once I copy the excel to another location and open it is asking for the vsto file.
and throwing System.Deployment.Application.DeploymentDownloadException:.

Please help me in resolving this.

Aravind India | Reply

11/15/2011 12:14:31 AM #

Gaurav Huria

Mathias,

Excellent Work!!! I am so glad that I got this article which made my day. I was trying to achieve this but couldn't found out how to do the registry part. I am so happy. You are a BRAVO Smile

I have few things to ask, if you can throw some light on these too. I want my MSI file to check for prerequisites and not my EXE to do so. Is there any way to do so. Its a part of my requirement.

Gaurav Huria India | Reply

2/29/2012 10:15:36 PM #

sjraman

Hi,

Thanks to you clear explanation, I was able to get my VSTO add-in up and running in user machine within a couple of hours.

sjraman India | Reply

5/28/2012 11:11:07 AM #

Lambertus

Your explanation is incredibly complete and clear. So much helping me. Thanks a lot.

Lambertus Indonesia | Reply

8/27/2012 9:32:37 PM #

Monil Suthar

It worked.....I Love you man... u rock !!!
I had wasted so much time on building that installer.....and now finally with your help it is finished.....Thank you so much.......

Monil Suthar India | Reply

9/12/2012 3:31:12 AM #

cyrus

Hi!

Can u write some article like this just with Word2007 addin? (I create an installer and change the important places to word /pia-s, reg codes/ but it still dosnt work.)

cyrus Hungary | Reply

11/19/2012 11:12:24 PM #

Roman K

Thanks a lot!

Roman K Ukraine | Reply

2/20/2013 7:14:41 PM #

clarisonic

most of any country.Individual Americans gave more than $227 billion in 2009, according to the Giving USA report by the Center on Philanthropy at Indiana University, down just 0.4 percent from the previous year despite the U.S.

clarisonic United States | Reply

3/12/2013 8:42:00 PM #

jack

I need to add "file:/" before the value for manifest string in registry like below,
file:/[TARGETDIR]ClearLines.Anakin.vsto|vstolocal ...
and it worked fine for me thank you Smile

jack India | Reply

7/14/2013 3:12:06 PM #

shallet

Excellent article.. it helped me a lot. Thank u so much

shallet India | Reply

Add comment




  Country flag

biuquote
  • Comment
  • Preview
Loading



Comments

Comment RSS