Deploying a Visio 2007 or 2010 VSTO add-in with Visual Studio 2010

I like extending Visio with custom code, and I have been doing it a long time. I progressed from VBA within Visio documents, to VB executable, using a C++ wrapper to register as Visio Add-ons, through VB.net COM add-ins to C# VSTO add-ins. Which ever language and method I use, it seems to me that deployment is always far more more difficult than it should be. Even though it has got simpler with VS 2010, there are still some gotchas…

I always seem to spend far too long creating a Setup and Deployment project for Visio solutions, so I thought I should document what is required (currently). I have clients who have Visio 2007 and Visio 2010, running on PCs that have .Net Framework 3.5 sp1 or .Net Framework 4, so I have to cater for all of these permutations. I do still have clients with Visio 2003 too, but that is another story (and I need to use VS 2008 to deploy to them).

I guess I should explain why I need to have different solutions for Visio 2007 and Visio 2010?: The answer is that even though the main code is the same for both, the UI handling is different because Visio 2007 has CommandBars and Visio 2010 has a Ribbon. I decided to do this by having two separate projects with shared code (and some compilation symbols). Therefore, I needed two different installations. Moreover, Visio 2010 is available as 32bit or 64bit, and, even though the code project can be targeted to either, you need to make a choice when you compile a Setup and Deployment project. So, I eventually ended up with three installation sets!

First of all, most Visio solutions involve deploying Visio documents, be it templates or stencils, so you will most probably want to use the Visio Solution Publisher ( see http://www.microsoft.com/download/en/details.aspx?id=12365 – note that it says it is for Visio 2010, but is actually for Visio 2003, 2007 and Visio 2010!). This tool works by modifying the msi file created by Windows Installer projects, therefore you will want to create a Setup and Deployment / Visual Studio Installer project that uses the primary project output from your add-in project.

There is an excellent video on the different requirements for targeting Office 2007 or Office 2010 and .Net 3.5 sp1 or .Net 4 ( How Do I: Deploy Office 2007 and Office 2010 Projects that Target .NET Framework 3.5 and .NET Framework 4? – http://msdn.microsoft.com/en-us/vsto/ff679933.aspx ), but it does not discuss the Setup & Deployment package that is required.

This article , Deploying a Visual Studio 2010 Tools for Office Solution Using
Windows Installer – see http://msdn.microsoft.com/en-us/library/ff937654.aspx, explains the requirements and the components of the Setup & Deployment package. Note that it discusses additional requirements for document level solutions, but generally Visio solutions do not need this because we have the Visio Solution Publisher tool.

You can also see the article Publishing an Office Solution by Using Windows Installer – http://msdn.microsoft.com/en-us/library/cc442767.aspx for an overview.

Chris Hopkin’s blog, A Complete Solution for Visio 2010 and Visio Services – http://blogs.msdn.com/b/chhopkin/archive/2010/05/28/a-complete-solution-for-visio-2010-and-visio-services.aspx, is useful because it is Visio-specific, but is aimed at Visio Services, and his earlier blog Deploying a VSTO 3.0 based Visio add-in using Windows Installer – http://blogs.msdn.com/b/chhopkin/archive/2008/11/13/deploying-a-vsto-3-0-based-visio-add-in-using-windows-installer.aspx is now out of date, but still useful.

A walkthrough of a simple Visio Setup and Deployment project

I created a very simple VSTO add-in using C# and .Net Framework 3.5 sp1.

So, the Target framework is .Net Framework 3.5:

I have gone to the trouble and expense of purchasing a digital certificate, so that my users can be sure that it comes from me, and the add-in does not need to be installed in the Program Files path. The Timestamp server URL is provided by Verisign too:

As this solution will be using the local vsto files, I ensured that the Publish Options / Office Settings were something sensible:

I needed to ensure that the Microsoft Office 2007 Primary Interop Assmblies are ticked in the Publish/ Prerequisites dialog. This is required for .Net Framework 3.5 only. In addition to including the relevant .Net Framework, you also need to include Microsoft Visual Studio 2010 Tools for Office Runtime and Windows Installer 3.1 for both frameworks.

The only code added to my add-in shows a message box when the add-in starts, and another when it closes….

namespace Visio2007OnXp35AddIn
{
    public partial class ThisAddIn {
        private void ThisAddIn_Startup(object sender, System.EventArgs e)
        {
            System.Windows.Forms.MessageBox.Show("Loaded .Net 3.5 addin", "Visio2007OnXp35AddIn");
        }

        private void ThisAddIn_Shutdown(object sender, System.EventArgs e)
        {
            System.Windows.Forms.MessageBox.Show("Unloaded .Net 3.5 addin", "Visio2007OnXp35AddIn");
        }

Now, when you run the add-in in Debug mode, some entries get written into the Registry under the HKCU\Software\Microsoft\Visio\Addins hive.

All this example project does is open a dialog to prove it is loaded:

And when Visio is closed down, the Unloaded message box appears:

After running in Debug mode, you can view the Registry entries that get written (note that you may need to select View \ Refresh first):

The FriendlyName is derived from Publish Options / Office Settings / Solution Name, and Description is derived from Publish Options / Office Settings / Description.

Note that HKLM does not get written to by running the Debug mode.

You can return the Registry back to its original state by choosing Clean from the right mouse menu of the Solution explorer in Visual Studio. If you want to test the installation on your development PC later, then it is important that you do use Clean first.

So, I then added a new Setup and Deployment project to the solution, and edited the DetectNewerInstalledVersion, Manufacturer, ProductName and RemovePreviousVersions poperties:

Note that you CAN set the InstallAllUsers to True for Office 2010 solutions, but it must be False for Office 2007. This took me two days to realise recently!

Note that the TargetPlatform is x86 – when it comes to creating the Visio 2010 installations, I run it once as x86 and then again as x64.

In this case, all of the Detected Dependencies can be marked as Exclude = True.

Now, you need to switch to Release mode and run the project because this will create the *.vsto and *.dll.manifest file in the bin/Release folder. This are needed because you need to add them as files to the File System / Application Folder of the setup project. (Note that these two files will get deleted when you run Clean – as will the Registry entries).

So, there are only three files that will be deployed to the target folder on installation. (Note that there are often templates and folders added to this list in a Visio solution).

Now, you need to create the Registry keys that are required for Visio to recognise the dll as a Visio add-in. These entries are only required to be added to the User/Machine hive in the Registry window of the Setup and Deployment project. Note that these are very similar to the Registry entries that were added automatically when the code was run in Debug mode, but I have added my company name as a prefix to the addin name key – just to ensure uniqueness.

UPDATE : Sice I wrote this article, I came across an issue which was fixed by reading http://msdnrss.thecoderblogs.com/2011/06/vsto-4-0-sp1-will-cause-a-vsto-addin-to-not-find-its-config-file/

Basically, I added file:/// before [TARGETDIR] in the Manifest setting… then it worked again.

Note that you can delete the two Software keys that are automatically created under the HKCU and HKLM hive above.

You should check that the same Prerequisites are selected for the Setup project Property Pages:.

The minimum launch conditions are for the .Net Framework, but the articles describe how to add conditions for the Office 2007 Shared PIA, Visio 2007 , and VSTO 2010 Runtime.

Then, when you Build the Setup project, the output is created within its Release folder by default:

I ran the Setup.exe file, knowing that this will load the bootstrapper, which would install the Office 2000 PIAs, if required, but on my first attempt to install, I checked the option to install for Everyone.

However, the add-in failed to load the expected dialog, and opening the Tools / Trust Center / Add-ins tab showed that the add-in is present but inactive.

The solution is simple … do not install for Everyone if it is for an Office 2007 add-in – it is OK for Office 2010 ones though.

Then I got prompted to install the Office customization when I started Visio (I did not get prompted for this on subsequent installation tests on this PC).

This time, I found the add-in appeared correctly as an Active Application Add-in

The installation correctly installed the required files into the target folder:

The installation correctly created the Registry entries in the HKLM hive:

Well, that demonstrates how I publish Visio solutions to Visio 2007 and Visio 2010 separately. Perhaps I’ll discuss the settings in the Visio Solution Publisher  at another time….