Deploying Office 2003 Solutions with Auto-update Functionality

• Download source - 5.77 KB

Introduction

I happened to read many articles and posts saying that VSTO add-ins targeting Office 2003 cannot auto update themselves using click once technology. The objective of this post is to provide a method to send future updates/upgrades of your Office 2003 solutions to your end user seamlessly without any user intervention. This post attempts to provide an end to end walk through to achieve this in your Office 2003 VSTO solutions. Office 2007 and above support click once technology and can handle auto updates automatically.

Background

Office 2003 solutions can be deployed in two ways.

• Publish wizard - The Publish Wizard enables you to deploy Visual Studio Tools for Office solutions to a Web site, network file share, or your local computer. It automatically creates an application manifest and a deployment manifest for the solution during the first deployment, or updates existing manifests.
• Visual Studio Setup project - When you create an add-in project by using Visual Studio Tools for Office, a Setup project is automatically added to the solution. The Setup project for add-ins generates a Windows Installer (.msi) file that configures the target computer and installs the add-in.

Both of these methods have their own advantages and disadvantages. Before getting into it, let us see what is required in order to successfully deploy Office 2003 solutions.

• Preparing end user computers – Your users must have several pre-requisite components installed before the solution will run. Therefore, you have to see if all required pre-requisites are installed in the end user computers. If not, you have to install them in the end user computers. This particular requirement can be achieved only using “Setup” projects. For more information, see this link.
• Granting Security Trust – You must update the security policy of every end user to allow the Visual Studio Tools for Office solution to run. As a developer, when you create a Visual Studio Tools for Office solution, your local security policy is updated automatically to allow the code in your project to run. The required permission set is Full Trust. Office solutions do not run managed code extensions that have partial trust or no trust. Code Access Security Policy tool (Caspol.exe) can be used to grant security trust via command line. Alternatively, the .NET Framework Configuration Tool can also be used to grant security trust using a graphical user interface.
• Creating Registry Entries – You must also create all required registry entries on each of your client computer. For more information, see this link.

Coming to the deployment methods, the main advantage of the “Publish” method is that it can support future updates/upgrades for your Office 2003 solution automatically. But, this method is not capable of doing any of the above mentioned steps as the publish wizard assumes that the users have the pre-requisites. Whereas, the “Setup” project is capable of doing all the above steps but cannot support automatic updates/upgrades. You have to distribute a new MSI file every time you make a change.

The approach here will use a combination of the above two methods (Publish wizard and VS Setup project) to achieve what we wanted, i.e., sending automatic updates of your Office 2003 solutions to end user computers. The following section will walk you through this method.

Walk through

This walk-through assumes that you are using Microsoft Visual Studio 2008 and .NET Framework 3.5 to create Office 2003 solutions. The method demonstrated here will create and deploy an Excel 2003 solution to a web site.

Creating an Excel 2003 Add-in Project

1. 

2. The above action will create a solution with two projects. One will be the actual add-in project and the other one will be the setup project. Open Excel2003AutoUpdateDemo.csproj file in a text editor such as “Notepad” and add the following XML element below the <PublishUrl> tag.
   XML

   <UpdateUrl>http://yourproject.yoursite.com/</UpdateUrl> 

3. Now let us add some very basic functionality to this add-in to run and test this sample. Add the following code to ThisAddin.cs file inside the “ThisAddIn_Startup” method:
   C#

   MessageBox.Show("Version: 1.0.0.1"); 

Enhancing the Setup Project

Some instructions presented in this section have been taken from here.

1. Adding pre-requisites to the Setup project - Add the prerequisites that the bootstrapper will install. A later step addresses adding launch conditions.
   1. In Solution Explorer, right-click Excel2003AutoUpdateDemo Setup, and then click Properties.
   2. In the Property Pages dialog box, click Prerequisites.
   3. In the list of prerequisites, select the following items:
      1. Windows Installer 3.1
      2. .NET Framework 3.5 SP1
      3. Microsoft Office 2003 Primary Interop Assemblies
      4. Microsoft Office 2007 Primary Interop Assemblies
      5. Microsoft Visual Studio 2005 Tools for Office Second Edition Runtime
      6. Visual Studio Tools for the Office system 3.0 Runtime Service Pack 1
   4. Click OK twice.
2. Adding a Custom Action to Grant Trust to the Assembly
   Grant trust to the customization assembly using the supplied custom action project. This project was initially taken from MSDN samples and is re-written to our needs. This custom action will grant FullTrust to all the code that exists on a particular web site.
   1. To add the custom action project
      1. Download the SetSecurity project, which is embedded in this article.
      2. In Solution Explorer, right-click Excel2003AutoUpdateDemo.
      3. Point to Add on the shortcut menu, and then click Existing Project.
      4. Select the SetSecurity project.
      5. Click OK.
      6. In Solution Explorer, right-click the SetSecurity project, and then click Build.
   2. To add the primary output of the custom action project to the Setup project. This enables the Windows Installer file to run the custom action that edits the application manifest.
      1. In Solution Explorer, right-click Excel2003AutoUpdateDemo.
      2. Point to View on the shortcut menu, and then click Custom Actions.
      3. In the Custom Actions editor, right-click Custom Actions, and then click Add Custom Action.
      4. In the Look In list, click Application Folder, and then click Add Output.
      5. The Add Project Output Group dialog box opens.
      6. In the Project list, click SetSecurity.
      7. Select Primary output from the list of output types, and then click OK.
      8. Verify that Primary output from SetSecurity (Active) is added to the list of primary outputs for the Setup project.
   3. To add the custom action data for the Install method
      1. In the Custom Actions editor, expand Install.
      2. Right-click Primary output from SetSecurity (Active), and then click Properties Window.
      3. In the Properties window, set the CustomActionData property to the following string. Enter this as one long string:
         

         /site="yourproject.yoursite.com" 
         /solutionCodeGroupName="YourProjectName" 
         /solutionCodeGroupDescription="Code group for YourProjectName" 
         /allUsers=[ALLUSERS] 

   4. To add the custom action data for the Rollback method
      1. In the Custom Actions editor, expand Rollback.
      2. Right-click Primary output from SetSecurity (Active), and then click Properties Window.
      3. In the Properties window, set the CustomActionData property to the following string:
         

         /solutionCodeGroupName="YourProjectName" 

   5. To add the custom action data for the Uninstall method
      
      1. In the Custom Actions editor, expand Uninstall.
      2. Right-click Primary output from SetSecurity (Active), and then click Properties Window.
      3. In the Properties window, set the CustomActionData property to the following string:

         /solutionCodeGroupName="YourProjectName"  

3. Adding Launch Conditions to the Windows Installer File
   When the user runs Setup.exe, the Windows Installer checks for the prerequisites, and installs them if necessary. Alternatively, the user can double-click the .msi file to install the solution. In that case, the prerequisites are not installed and the solution cannot run. In other cases, Setup might fail because resources it needs are not present; for example, custom actions might require the .NET Framework. This section shows you how to use the Launch Conditions editor to add launch conditions to the .msi file to prevent installation if certain dependencies are not installed.
   1. To view the Launch Conditions editor
      1. In Solution Explorer, right-click Excel2003AutoUpdateDemo.
      2. Point to View on the shortcut menu, and then click Launch Conditions.
   2. To add a launch condition for the VSTO 2005 SE runtime
      1. In the Launch Conditions editor, right-click Requirements on Target Machine, and then click Add Registry Launch Condition.
      2. Select the newly added search condition, Search for RegistryEntry1.
      3. Rename the search condition to Search for VSTO 2005 SE Runtime.
      4. In the Properties window, change the value of Property to VSTORTVERSION.
      5. Also in the Properties window, set the value of RegKey to the following string:

         Software\Microsoft\vsto runtime Setup\v2.0.50727 

      6. Leave the Root property set to vsdrrHKLM and change the Value property to Update.
      7. Select the newly added launch condition, Condition1.
      8. Rename it to Display message if the Visual Studio 2005 Tools for Office SE Runtime is not installed.
      9. In the Properties window, change the value of the Condition property to the following string:

         VSTORTVERSION >= "#3" 

      10. Change the value of the Message property to The Visual Studio 2005 Tools for Office SE Runtime is not installed. Please run Setup.exe.
4. Removing the Primary Output of the add-in from the Setup project
   This step is important because your solution assemblies need not be packed with the installer file and is not required to be installed in the client system. Your solution assemblies and dependant files will be published to a web site and future updates will also be published in the same web site. Only the application manifest generated by the Publish wizard needs to be included in the setup project.
   
   
   1. Expand Excel2003AutoUpdateDemoSetup project
   2. Right click “Primary output from Excel2003AutoUpdateDemo (Active)” and click “Remove” to remove it.
5. Adding the Application Manifest of the add-in project to the Setup project
   The application manifest can be generated by publishing the initial version of the add-in. The publish wizard will generate both deployment manifest as well as application manifest. To generate the application manifest and add it to the setup project, do the following:
   1. Right click Excel2003AutoUpdateDemo project, select Properties and go to Publish tab.
   2. Change the Publish Location to a temporary local folder in your system.
   3. Click the “Publish Now” button.
   4. After the Publish operation is successful, go to the temporary local folder you selected. You should see the following folder structure:

      

   5. Go into the Excel2003AutoUpdateDemo_1.0.0.0 project and you should see the following files:

      

   6. Right click Excel2003AutoUpdateDemoSetup project, select Add and then select File. In the Browse dialog box, select Excel2003AutoUpdateDemo_1.0.0.0\ Excel2003AutoUpdateDemo.dll.manifest file and Press OK to add this file.

Testing the Solution

1. Build the Solution.
2. Move the files and folders generated while publishing the add-in to the web site, i.e., http://yourproject.yoursite.com.
3. Build the Excel2003UpdateDemoSetup project to create the installer file.
4. Distribute the setup.exe and Excel2003UpdateDemoSetup.msi file to another computer where you are going to test the add-in.
5. Run the setup.exe in the test computer to install the add-in.
6. Open Excel and you will see the following popup:

   

7. Again, go to your development computer and open the ThisAddin.cs file and change the code inside the “ThisAddIn_Startup” method:
   C#

   MessageBox.Show("Version: 1.0.0.2"); 

8. Build the solution.
9. Right click Excel2003AutoUpdateDemo project, select Properties and go to Publish tab.
10. Change the Publish Location to a temporary local folder in your system.
11. Click the “Publish Now” button.
12. After the Publish operation is successful, go to the temporary local folder you selected and copy all the contents and move it to the same web site, i.e., http://yourproject.yoursite.com. Now, your folder structure in your website should look like the one shown below:

    

13. Go to the development computer and just close and open Excel again. The add-in will be automatically updated to the latest version and the following message box will popup:

    

Summary

Visual Studio Tools for Office includes something called the VSTOLoader which is actually responsible for loading the VSTO add-ins into Excel. It goes into the registry to find out the list of add-ins and finds out the whereabouts of the add-in using a registry entry called “Manifest”. If this entry points to an application manifest, it will directly load the add-in from that location. If this entry points to a deployment manifest, it will read the deployment manifest to locate the application manifest and then load the actual add-in which in our case is placed in a web site. So, if we keep updating the deployment manifest in the web site, Microsoft Excel will always load the application manifest that is being pointed to.

History

• Version 1.0 - May 5, 2010