In a previous post I gave you a brief description of Click-Once vs. Windows Installer based deployment choices and how to choose between the two.
In this post I will describe in detail how to setup a Windows Installer (MSI) based project for deploying your VSTO 3.0 Visio 2007 add-in. This MSDN article has more detailed information for VSTO 3.0 Add-Ins using an Excel add-in as the example project.
Creating the Setup project
I assume at this point you have a solution in Visual Studio that contains a VSTO 3.0 based add-in project for Visio 2007.
The first step is to add a new Setup project to your solution. To do this simple choose File > New > Project… from the menu and in the New Project dialog choose ‘Setup and Deployment’ from the ‘Other Project Types’ category. From the Templates list choose ‘Setup Project’ as shown below.
Project Properties
Right after I create the new setup project I usually set all the properties for the setup project. These are all standard properties and do not relate specifically to Visio based add-ins, however I typically set…
InstallAllUsers = False – Make sure this is False as Office 2007 no longer support HKLM registered add-ins. See the X section below for more information.
Version = x.x.x.x – I always make sure this is updated and in sync with the version of the add-in assembly. The main reason for this is to update the ProductCode so that each new build can install over the old build. Visual Studio will detect that you changed this value and prompt you to update the ProductCode value. If you build your MSI via a script you will need to update the Version and ProductCode values manually after the MSI is generated.
Adding Prerequisites
Prerequisites can be installed by the bootstrapper (setup.exe) if the target machine does not already have them installed. These are separate from Launch Conditions but I typically create Launch Conditions for each prerequisite in case the user launches the MSI without running the setup.exe bootstrapper.
For a VSTO 3.0 based Add-In the following prerequisites are required
- .NET Framework 3.5
- Windows Installer 3.1
- VSTO 3.0 runtime
- 2007 Microsoft Office Primary Interop Assemblies – specifically the Visio 2007 PIA
Most of the prerequisites listed above are already available in the list of available prerequisites. The 2007 PIA prerequisite is probably not in your list but can be added. Check out this article for steps to add this to your list.
Launch Conditions
As I mentioned above, Launch Conditions are separate from Prerequisites but you should really use them together. It is possible for the user to run the MSI to install the application instead of using the setup.exe bootstrapper which might result in the application crashing or not even loading because of missing prerequisites. The most common situation for Visio add-ins is the add-in will not be loaded…
You can prevent this support issue by adding appropriate launch conditions to keep your add-in from installing if your requirements are not met. Launch conditions also provide an InstallURL property so that if the launch condition is not met, the user can be directed to the location of an install package that will help them meet the condition.
It is important to note that you cannot determine the order for the Launch Conditions.
.NET Framework 3.5 launch condition
This launch condition is added to the setup project for you so don’t worry too much about this one.
VSTO runtime launch condition
To search for the VSTO 3.0 runtime you can use either the registry method or the ComponentID method.
Registry Search
ComponentID Search
RegKey = Software\Microsoft\vsto runtime Setup\v9.0.21022
ComponentID = {AF68A0DE-C0CD-43E1-96DD-CBD9726079FD}
In this case we did not set the InstallUrl property, we provided a message to inform the user to run setup.exe:
[ProductName] requires Visual Studio Tools for Office 3.0 runtime. Please run setup.exe to install the prerequisites for this application.
If we were to provide the InstallUrl property to take the user to the download location for the VSTO 3.0 Runtime we would set this property to:
http://www.microsoft.com/downloads/details.aspx?FamilyId=54EB3A5A-0E52-40F9-A2D1-EECD7A092DCB&displaylang=en
Office 2007 / Visio 2007 PIA launch condition
The Visio Primary Interop Assembly is needed for any Visio add-in created using .NET.
The PIA for Visio may already be installed if the machine had .NET Framework installed on it prior to installing Visio. The Visio installation would have detected this and automatically installed the PIA. If .NET was installed to the machine after Visio, chances are that the PIA for Visio is not installed.
For this launch condition we will use a ComponentID search item and search for the ComponentID for the Visio PIA. The Visio PIA is either installed by the installation of Visio or from the Office 2007 PIA redistributable package.
Visio 2007 PIA Component ID = {C1F1028F-D91A-43E8-A117-4F7CAFD7A041}
For a complete list of ComponentIDs for the PIAs for each Office application see this article.
Again, if we were to provide the InstallURL property to take the user to the download location for the Office 2007 PIA redistributable we would set this property to:
http://www.microsoft.com/downloads/details.aspx?familyid=59daebaa-bed4-4282-a28c-b864d8bfa513&displaylang=en
Visio 2007 launch condition
In addition to launch conditions that back up the prerequisites I also add a launch condition to check for the installed version of Visio on the target machine. Check out my blog article for detail on this specific launch condition.
File System
The file system is fairly straight forward. Define the location of the Application Folder for the target machine and add your project output to this folder. You can get more detailed for supporting files and content but this is up to you.
If you added Visio templates, stencils and other content to the project you can simple use the ‘Content Files’ option to include those files in your setup project automatically.
In addition to the project output and any additional content you have to make sure and install the application manifest (*.manifest) and the deployment manifest (*.vsto) files in the Application Folder with the project output. These files replace the old COM Add-In registry entries and tell the VSTO runtime about any dependencies.
Registry
Above we mentioned that the manifest files were the replacement for the old COM Add-In registry keys so what gives? The add-in is no longer registered for COM but we still need to inform the VSTO runtime of our add-in so that it loads correctly, and this is done via the registry.
As you can see in the sample below, all we care about is the Addins key. Description, FriendlyName and LoadBehavior are still used however for VSTO we add the additional key named ‘Manifest’ which points to the deployment manifest file (*.vsto).
It is important to note the ‘|vstolocal’ value appended to the end of the Manifest value. This informs the VSTO runtime that it is locally installed and to not invoke the ClickOnce installer.
User Interface
The only item I want to discuss about the User Interface is the setting to disable the ‘Install for All Users’ option. In the registry section above we specifically put our settings in the User/Machine Hive section. Now we want to make sure that our add-in installs for only the current user because Office 2007 does not support add-ins installed for HKLM.
To configure a single-user installation
- In the Solution Explorer, right-click the Setup project, expand View and select User Interface.
- In the User Interface (Setup) editor, right-click Installation Folder and select Properties Window.
- In the Properties window, set the value of the InstallAllUsersVisible property to False.
PublishComponents
Because this setup project produces an MSI we can use the Visio Solution Publishing tool (vissolpublish.exe) to update the MSI with additional information about the templates and stencils contained in our MSI so they become available on the Visio Getting Started task pane and menus.
Check out my blog article on running the Visio Solution Publishing tool as a Post Build action on the Setup project.