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…
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:
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:
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)
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