It's been quite a while I am thinking about writing a blog on "VSTO 3.0 Deployment". I faced some serious problems in my inital stages of VSTO deployment as there was no clear path to all users deployment. I have to chase more than 3-4 articles/blogs to understand the concept of deploying the solution for all users. So, I thought of providing the deployment solution for all users in one single article which might be helpful for starters.
What we are going to see in this section?
1. Create a WordAddin
2. Create Setup Project
3. Configuring prerequisites
4. Configuring Registry Keys
5. Trusting solution for All Users
1. Create a WordAddin:
Open Microsoft Visual Studio 2008.
On the File menu, expand New and click Project to create a new Visual Studio project.
In the New Project dialog box, in the Project types pane, expand Visual Basic, expand Office, and then select 2007.
In the Templates pane, select Word 2007 Add-in.
In the Name box, type SampleWordAddin.
Select Create Directory for Solution, and click OK to create the new Word 2007 add-in. The Solution Explorer displays the opened solution.
If the code file for the ThisAddIn class is not currently open, in the Solution Explorer, right-click the ThisAddIn.vb file and click View code to open the main code file for the SampleWordAddin add-in.
In the code editor, locate the ThisAddIn_StartUp method. Add a call to the System.Windows.Forms.MessageBox.Show method to display a custom message when the add-in starts.
Public Class ThisAddIn
Before you create the setup project for the SampleWordAddin add-in, first build the project so the project output is available for the setup project. Building the add-in generates the deployment and application manifests required for the deployment and installation of the add-in. Also, Visual Studio provides two build configurations out of the box. You should make sure only to distribute release builds because these assemblies are optimized. Be aware that release builds might hinder debugging of your solution because of optimizations in the execution order.
To set the build configuration to release, See Solution Explorer, right-click Solution 'SampleWordAddin' (1 project) and click Configuration Manager to show the build configuration manager for the Visual Studio solution.
In the Configuration Manager dialog box, for Active Solution Configuration, select Release and Close the dialog box.
Before we create the setup project for the SampleWordAddin add-in, first build the project so the project output is available for the setup project. Building the add-in generates the deployment and application manifests required for the deployment and installation of the add-in.
To build the SampleWordAddin project, Click Build menu, select Build Solution to compile the add-in. Make sure that there are no compilation errors.
2. Create Setup Project
The next step is to create setup project for deployment. To add the setup project to the Word Addin, Select File menu, expand Add and click New Project to add a new project to the "SampleWordAddin" solution.
In the Add New Project dialog box, in the Project types pane, expand Other Project Types and then select Setup and Deployment.
In the Templates pane, select Setup Project from the Visual Studio installed templates group.
In the Name box, type "SampleWordAddinSetup".
Ensure that the folder identified by the Location box is inside the VSTO v3 Deployment Demo folder created for the solution, and click Open to create the new setup project.
Now, we need to add project output of our SampleWordAddin. In the Solution Explorer, right-click SampleWordAddin, click Add and then Project Output.
In the Add Project Output Group dialog box, confirm that the SampleWordAddin project is selected, and the Primary Output option is selected.
Click Open to add the project output to the setup project.
The setup project needs to deploy the deployment manifest and application manifest. You can add these two files to the setup project as stand-alone files from the output folder of the SampleWordAddin project.
To add the deployment and application manifests:
In the Solution Explorer, right-click SampleWordAddin, click Add, and click File.
In the Add Files dialog box, navigate to the SampleWordAddin output directory. Usually the output directory is the bin\release subfolder of the project root directory, depending on the selected build configuration.
Select the SampleWordAddin.vsto and SampleWordAddin.dll.manifest files and click OK to add these two files to the setup project
Referencing the SampleWordAddin includes all the components that SampleWordAddin requires. These components must be excluded and deployed using prerequisite packages to allow them to be registered correctly.
To exclude the SampleWordAddin project dependencies
In the Solution Explorer, in the SampleWordAddin node, select all dependency items beneath the Detected Dependencies item except for Microsoft .NET Framework.
Right-click the group and select Properties.
In the Properties window, change the Exclude property to True to exclude the dependent assemblies from the setup project.
3. Configuring prerequisites
The Windows Installer package should install the prerequisite components. The setup project can include and install the redistributables provided by the component vendors, a process called bootstrapping. For the SampleWordAddin, the following prerequisites must be installed before the add-in can run correctly.
a) Microsoft .NET Framework 3.5
b) Microsoft Visual Studio Tools for the Microsoft Office system (version 3.0 Runtime)
c) Redistributable Primary Interop Assemblies for the 2007 Microsoft Office system.
d) Windows Installer 3.1
Configure dependent components as prerequisites
In the Solution Explorer, right-click the SampleWordAddinSetup project and select Properties.
The SampleWordAddinSetup Property Pages dialog box appears.
In the Prerequisites dialog box, perform the following tasks.
Select Create setup program to install prerequisite components. This creates the setup.exe bootstrapper together with the MSI file.
In the Choose prerequisites to install list, select the following:
a) Windows Installer 3.1
b) .NET Framework 3.5
c) 2007 Microsoft Office Primary Interop Assemblies
d) Visual Studio Tools for the Office system 3.0 Runtime
To specify the install location for prerequisites, select Download prerequisites from the same location as my application.
Click OK to close the Prerequisites dialog box
Click OK to close the property pages of SampleWordAddinSetup.
4. Configuring registry keys
Microsoft Office locates the application-level add-in by using registry keys in the HKEY_CURRENT_USER hive. The Visual Studio setup project is capable of configuring the required registry keys
The keys live in a user specific key hive, which makes the add-in available only to the user running the setup. But in this walkthrough we are going to deploy the add-in to all users.
In the Solution Explorer, right-click SampleWordAddInSetup.
Click Registry to open the registry editor window.
In the Registry(SampleWordAddInSetup) editor, expand HKEY_CURRENT_USER and then Software.
Delete the [Manufacturer] key found under HKEY_CURRENT_USER\Software. This key is automatically added when the setup project is created and is not used by the add-in.
Expand HKEY_LOCAL_MACHINE and then Software.
Delete the [Manufacturer] key found under HKEY_ LOCAL_MACHINE\Software. This key is also added automatically and isn’t used by the add-in.
Right-click the Software key under HKEY_LOCAL_MACHINE, select New and then Key. Use the text Microsoft for the name of the new key.
Use a similar process to create the entire key hierarchy required for the add-in registration. The following key hierarchy is used for the SampleWordAddIn add-in.
HKEY_LOCAL_MACHINE\Software\Microsoft\Office\12.0\User Settings\SampleCompany.SampleWordAddIn\ Create\Software\Microsoft\Office\Word\Addins\SampleCompany.SampleWordAddIn
Also, don’t forget to set Create's key “DeleteOnUninstall” property in the Properties Window to True to make sure it is always deleted on uninstall
Now, on the SampleCompany.SampleWordAddin key, create the registry entries as follows:
You need to create a "Count" property under "HKEY_LOCAL_MACHINE\Software\Microsoft\Office\12.0\User Settings\SampleCompany.SampleWordAddIn". This value will be incremented on install and repair.
The increment of this registry entry will be done using a custom action. I will be updating this section soon.
5. Trusting the Solution for All Users:
We have setup all the registry entries needed and now we need to trust the add-in. The “Inclusion List” project provided in the MS article is nothing but the creation of registry keys. This registry key resides under HKEY_CURRENT_USER\Software\Microsoft\VSTO\Security\Inclusion.
Since this key resides in HKCU hive, it is useless for All Users deployment. The setup should create the key as mentioned below in order to make this add-in available to all users.
HKLM\Software\Microsoft\Office\12.0\ User Settings\SampleCompany.SampleWordAddIn\Create\Software\ Microsoft\VSTO\Security\Inclusion
To do this change, follow the procedure given below:
Go to HKEY_CURRENT_USER\Software\Microsoft\VSTO\Security\Inclusion and find the entry in the list that pre-trusts your solution. Export this entry into a .reg file. The exported file should look like this:
Windows Registry Editor Version 5.00
Now, change HKEY_CURRENT_USER to HKEY_LOCAL_MACHINE, and
Then, go to Visual Studio deployment project, open the Registry View, right click on "Registry on Target Machine" root node in the view and click “Import” to import the .reg file.
Now the registry entries will be created under HKLM hive and should be functioning for all users.
Build the solution and try installing this to an end user machine and the add-in should be available to all users.
To configure the development computer for deploying Office 2007 solutions, see Deploying a Visual Studio Tools for the Office System 3.0 Solution for the 2007 Microsoft Office System Using Windows Installer (Part 1 of 2). This includes prerequisites to include in your Setup project.
To see examples on how to deploy Office 2007 solutions with a Setup project, Deploying a Visual Studio Tools for the Office System 3.0 Solution for the 2007 Microsoft Office System Using Windows Installer (Part 2 of 2) provides and how to combine ClickOnce and Windows Installer.
Deploying your VSTO 2008 Add-In to All Users (Part III)