Building and deploying an Outlook 2010 Add-in (part 2 of 2)

In the first part of this series, we went through the steps to create a simple Outlook 2010 add-in, how to build a custom ribbon, and finally the backstage area. But what use is your add-in unless other people can use it too? In part 2, we will look at the steps to create a setup package so that you can distribute your add-in to others.

Setup Project

Returning to the solution you started in part 1, you will now need to add a Setup Project. I’ll call mine “SetupMyOutlookAddIn”. When the project has loaded in, Visual Studio will bring up the File System screen of your Setup Project. We will need to make a few changes here:

  • Select Application Folder, and open the Properties window (you will probably find it easier to have the properties window open the whole time – we will be using it a lot!)
  • In the Properties window, under DefaultLocation, change [ProgramFilesFolder][Manufacturer]\[ProductName] to [AppDataFolder][Manufacturer]\[ProductName]
  • Now, right click Application Folder – Add – Project Output… and on the dialog that appears, choose “Primary Output”.

We’ve now effectively told the setup project to install all our application goodness to the user’s AppData folder (Normally C:\Users\[username]\AppData in Windows 7, for example). We are doing this as this is a safe, sandboxed location that requires a minimum of privileges to install to. Here’s roughly how your screen should look now…

FileSystem_25D70833

Now, we need to remove some of the .dll files that were added as Primary Output (because we do not need them). In Solution Explorer:

  • Expand ‘Detected Dependencies’ in your Setup Project.
  • Right click and ‘Exclude’ everything under this folder except for:
    • Microsoft.NET Framework
    • Microsoft.Office.Tools.Common.v4.0.Utilities.dll
    • Microsoft.Office.Tools.Outlook.v4.0.Utilities.dll

There are now 2 files you need to reference explicitly in your setup project. These are files that are created when you build your solution – so you will need to point to the release folder. You may use debug if you wish – just remember you are pointing there. For production software, you should point to release. So, in the File System window of your setup project:

  • Right-click the Application folder and select Add – File…
  • Browse to your application folder, and then bin\Release
  • Select the .dll.manifest, and .vsto files that reside there.

Your File System window should now look something like this:

FileSystem2_17988F43

Registry

To get our add-in working, we will need to add registry keys. When you are developing the solution in Visual Studio, this happens automatically in the background, so it can be a surprise that you will need to do it explicitly! The keys we are creating will be saved to: HKCU\Software\Microsoft\Office\Outlook\Addins.

Open the Registry Panel in your Setup Project, then:

  • Expand the HKEY_CURRENT_USER key, then Software, and rename [Manufacturer] to Microsoft (because we are adding this key to the Microsoft Office section of the Registry).
  • Create a tree of key values underneath Microsoft: Office\Outlook\Addins
  • Finally, create a key for your add-in. Give it a unique name, such that it is different from the add-in project name (so you can identify keys created by the installer, and keys created by Visual Studio).
  • In that key, set the following values:
    • String – “Description”
    • String – “FriendlyName”
    • String – “Manifest” – set this to “[TARGETDIR]MyOutlookAddIn.vsto|vstolocal”
    • DWORD – “LoadBehavior” – set this to “3”
  • Select your new key (the one you just set values for) and in the Properties window, set DeleteAtUninstall to be true (important: do not set it for any keys higher up in the tree!)

Here’s how your Registry screen should now look:

Registry_17988F43

Prerequisites

Now, we need to make sure that the Setup.exe you produce will check for prerequisites on the client system. This can be done by:

  • Right-click your add-in project (not your setup project) and select properties
  • Ensure the following are ticked:
    • Microsoft .NET Framework 4 Client Profile (x86 and x64)
    • Microsoft Visual Studio 2010 Tools for Office Runtine (x86 and x64)

Prerequisites_17988F43 

Finishing Touches

We’re pretty much done! A few things you may want to change:

  • Open the properties panel of your setup project and update the values there such as Version and Product Name.
  • Open the User Interface editor of your setup project, and delete the Installation Folder screen. This will stop users from installing the add-in to a different location (that may stop your add-in from running).

Build your add-in, and then right-click your Setup Project and select Install. The next time you open Outlook, you should be prompted to allow your new add-in to run!

Written by Matthew Farmer