Deploying Visual Studio Tools for the Office System 3.0 Solutions for the 2007 Microsoft Office System Using Windows Installer (Part 2 of 2)

Summary: Learn how to deploy a Microsoft Visual Studio Tools for the Office system 3.0 add-in or document-level solution using a Visual Studio 2008 setup project to create a Windows Installer package that targets the 2007 Microsoft Office system. (12 printed pages)

Wouter van Vugt, Code Counsel

Ted Pattison, Ted Pattison Group

Applies to: Microsoft Visual Studio Tools for the Microsoft Office system 3.0, 2007 Microsoft Office system, Visual Studio 2008

Download:http://code.msdn.microsoft.com/VSTO3MSI

  • Contents

  • Overview

  • Download Samples Provided with this Article

  • Handling Trust as Part of the Installation

  • Deploying Additional Components

  • Additional Requirements for Document-level Solutions

  • Deploying to the ClickOnce Cache

  • Adapting the Setup Project for Windows Vista

  • Known Issues

  • Additional Resources

  • About the Authors

Overview

This article, the second of two, provides three additional walkthroughs that show how to deploy a Visual Studio Tools for Office solution using a Visual Studio 2008 Windows Installer package. These walkthroughs only apply to solutions developed for the 2007 Microsoft Office system and the VSTO 3.0 runtime.

NoteNote

These walkthroughs do not apply to projects in Visual Studio 2008 that are based on applications in Microsoft Office 2003, which use the code access security policy for granting trust to solutions.

The first walkthrough Handling Trust as Part of the Installation provides steps to grant trust to your Office solutions by using either a known and trusted certificate or an inclusion list entry. The second walkthrough Deploying to the ClickOnce Cache provides steps to deploy additional assemblies with your Office solution. Finally, the third walkthrough Additional Requirements for Document-level Solutions demonstrates how to deploy the document and assembly in separate locations. The instructions only apply to Office solutions created for the VSTO 3.0 runtime and the 2007 Microsoft Office system.

Important: Before you start these walkthroughs, read and follow the instructions in Deploying Visual Studio Tools for the Office System 3.0 Solutions for the 2007 Microsoft Office System Using Windows Installer (Part 1 of 2).

Download Samples Provided with this Article

The walkthroughs provided in this article use various sample files contained in the download. The download contains the source code for the following components:

  • All sample projects created in this article.

  • Bootstrapper configuration files for the Redistributable Primary Interop Assemblies for the 2007 Microsoft Office system.

  • Custom action classes for the Setup projects used to deploy the Visual Studio Tools for Office solution.

By default, these files are installed into the following folder:

%ProgramFiles%\Microsoft Visual Studio Tools for the Office system 3.0 Resources\Windows Installer Sample\

This article refers to this installation folder as {SamplesDir}.

Download:http://code.msdn.microsoft.com/VSTO3MSI

Handling Trust as Part of the Installation

You can use two options to trust the solution during the installation process. First, you can sign the application and deployment manifests using a certificate trusted by the user. Second, you can add the location of the deployment manifest and the certificate that you used to sign the manifests to the list of trusted solutions.

The preferred solution to handling security is to sign the manifests using a known and trusted publisher’s certificate. You should request a certificate from a certificate authority trusted by both you and the user. For more information about how to obtain a certificate for signing, see ClickOnce Deployment and Authenticode. After a real certificate is obtained, the certificate must be explicitly trusted by adding it to the Trusted Publishers list. For more information, see How to: Add a Trusted Publisher to a Client Computer for ClickOnce Applications.

To change the certificate used to sign the manifests

  1. In the Solution Explorer, right-click ExcelAddIn and click Properties to show the properties of the ExcelAddIn project.

  2. In the ExcelAddIn property pages, select the Signing tab.

  3. On the Signing tab, ensure that Sign the ClickOnce manifest is checked. Click either Select from Store or Select from File to select the certificate you want to sign the deployment manifest. Make sure that you choose a certificate that is trusted by the user.

  4. Compile and deploy the ExcelAddInSetup project.

    NoteNote

    Signing the ClickOnce manifest is different from signing an assembly using a strong-name. Strong-naming provides a mechanism for identifying and versioning .NET assemblies. Signing with a certificate assures users that they know where the code came from and verifies that the code has not been tampered with since its publication.

You can use the inclusion list API provided by Visual Studio Tools for Office to trust the add-in during the installation process. Using this API, you define a trust relationship based on the location of the deployment manifest and the public key of the certificate used to sign the manifest. You can use a custom action to call into this API during the installation process.

The download accompanying this article contains a Visual Studio 2008 solution with all custom actions used in the procedure. The custom action uses the UserInclusionList class to create the trust relationship for the add-in.

To add the custom action project to your Visual Studio solution

  1. In the Windows Explorer, navigate to the {SamplesDir}\projects folder. Copy the language specific InclusionListCustomActions folder to the root folder of your add-in.

  2. In the Solution Explorer, right-click the Solution VSTO v3 Deployment Demo solution, expand Add and click ExistingProject. Navigate to the folder inside the solution root directory containing the InclusionListCustomActions project, select either InclusionListCustomActions.vbproj or InclusionListCustomActions.csproj depending on your language choice and click Open to add the project to the solution.

    Figure 23. Inclusion List Custom Actions

    Inclusion List Custom Actions

The public key of the certificate used to sign the deployment manifest is necessary for the inclusion list API to validate that the solution is trusted. You must add the public key as part of a custom action.

To retrieve the public key of the deployment manifest signature

  1. In the Solution Explorer, select the ExcelAddIn project.

  2. In the Solution Explorer toolbar, click Show All Files to show the files that are not part of the project but reside in the project directory.

  3. Expand ExcelAddIn, next expand bin and finally expand release.

  4. Right-click the ExcelAddIn.vsto file, and click Open to open a file editor for the deployment manifest.

  5. Inside the ExcelAddIn.vsto editor, locate the Signature element that has an ID with the value StrongNameSignature.

    Figure 24. <RSAKeyValue> element

    <RSAKeyValue> element

  6. Inside the Signature element, locate the KeyInfo element that has an ID with the value StrongNameKeyInfo. Copy the entire contents of the KeyValue child element to a temporary location such as Notepad. Do not copy the KeyValue element itself, only the content. Remove the newline characters from the string. The following sample shows the final result. Note that the text is wrapped.

    <RSAKeyValue><Modulus>0VjTVM/DV60EG+n1FvletQlhgsvxny0FrqqApTHfr+Tjvokfpftqg3f30NF0J+HwLHeCJsoGMvKtVntRbvO0j/iriBivPIMXIBjZoea/OT+TlBvS1kH3w3H+TmIcQosQ1Nf1J7gfO3X6WGHBu8GhWb2llJJ3sK+s6xIIUgQzzh0=</Modulus><Exponent>AQAB</Exponent></RSAKeyValue>
    

The inclusion list API requires two pieces of information: the location of the deployment manifest and the public key of the certificate you used to sign the manifest. These values are used to verify the integrity of the deployment manifest. The public key is hardcoded in the custom action class.

To configure the custom action

  1. In the Solution Explorer, expand InclusionListCustomActions. Right-click TrustInstaller.vb or TrustInstaller.cs, and click ViewCode to edit the code of the custom action class.

  2. In the TrustInstaller code editor, locate the RSA_PublicKey constant inside the TrustInstaller class.

  3. Change the value of the RSA_PublicKey constant to the value copied from the deployment manifest in the previous step. Make sure that there are no newline characters in the value.

    <RunInstaller(True)> _
    Public Class TrustInstaller
        Inherits Installer
        Private Const RSA_PublicKey As String = "<RSAKeyValue>..</RSAKeyValue>"
    End Class
    
    [RunInstaller(true)]
    public class TrustInstaller
        : Installer
    {
        const string RSA_PublicKey = "<RSAKeyValue>..</RSAKeyValue>";
        ..
    }
    

You need to add the custom action assembly to the setup project. This involves a similar step as including the primary add-in assembly.

To add the custom action to the setup project

  1. In the Solution Explorer, right-click ExcelAddInSetup, click Add and then ProjectOutput.

  2. In the Add Project Output Group dialog box, select the InclusionListCustomActions project and the PrimaryOutput option.

  3. Click OK to close the dialog box.

    Figure 25. Inclusion List Custom Action - Add Project Output Group

    Inclusion List Custom Action

  4. In the Solution Explorer, right-click ExcelAddInSetup. Expand View and click CustomActions to view the custom action editor for ExcelAddInSetup.

  5. In the CustomActions (ExcelAddInSetup) editor, right-click CustomActions and click AddCustomAction.

  6. In the Select Item in Project dialog box, in the Look in list, select Application Folder.

  7. Select Primary Output from InclusionListCustomActions(active) and click OK to register the custom actions contained in the InclusionListCustomActions assembly for execution during installation of the Windows Installer package.

  8. Right-click Primary Output from InclusionListCustomActions(Active) under the Install node and click Rename. Change the name of the custom action under the Install node to Add add-in to inclusion list.

  9. Change the name of the custom action under the Uninstall node to Remove add-in from inclusion list.

    Figure 26. ExcelAddInSetup Custom Actions

    ExcelAddInSetup Custom Actions

    Note

    It is important to add your custom action to all the four installation phases to allow the custom action environment to function properly, even though your custom action performs no task for certain phases.

  10. Right-click the Add add-in to inclusion list custom action and click Properties Window.

  11. In the Properties window, set the value of the CustomActionData property to /deploymentManifestLocation="[TARGETDIR]ExcelAddIn.vsto".

    Figure 27. Inclusion List Custom Action Properties

    Inclusion List Custom Action Properties

Referencing the InclusionListCustomActions project includes all the components that the custom action depends on. Exclude these components from the setup project.

To exclude the InclusionListCustomActions project dependencies

  1. In the Solution Explorer, expand ExcelAddInSetup and then expand DetectedDependencies.

  2. Select Microsoft.VisualStudio.Tools.Applications.Hosting.v9.0.dll and Microsoft.VisualStudio.Tools.Office.Runtime.v9.0.dll. Right-click the selection and click Properties.

  3. In the Properties window, change the Exclude property to True to exclude the dependent assemblies from the setup project.

    Figure 28. Excluding Dependencies

    Excluding Dependencies

The setup project is not compiled as part of a general solution compilation because the build can take a long time on larger projects. You need to manually compile the setup project and copy the resulting files to a location that is accessible to the user.

To build the setup project

  1. In the Solution Explorer, right-click the ExcelAddInSetup project and click Build.

  2. Using WindowsExplorer, navigate to the output directory of the ExcelAddInSetup project found in the VSTO v3 Deployment Demo\ExcelAddInSetup\Release folder. Copy all files to a location that users can access like a network share, CD, or USB stick.

Deploying Additional Components

While a simple add-in consists of only the primary assembly and the manifest files, a real-world add-in will most likely use separate assemblies that form the parts of the add-in as well as resources such as configuration files on disk. In this section, you will learn how to deploy these additional files with the Visual Studio 2008 Setup Project.

In this following procedure, the message box display is performed by a helper assembly instead of the add-in assembly.

To add a helper assembly and add a reference

  1. On the File menu, expand Add and click New Project to add a new project to the VSTO v3 Deployment Demo solution.

  2. In the Add New Project dialog box, in the Project types pane, select Visual C# or Visual Basic depending on your language preference.

  3. In the Templates pane, select Class Library from the Visual Studio installed templates group.

  4. In the Name dialog box, type ExcelAddInLibrary.

  5. Ensure that the folder identified by the Location box is inside the VSTO v3 Deployment Demo folder created for the solution,

  6. Click OK to create the new class library. Visual Studio opens the code editor for the Class1.vb or Class1.cs file.

    Figure 29. Solution Explorer - ExcelAddInLibrary

    Excel Addin in Solution Explorer

    The helper assembly shows the message box instead of the main add-in assembly. You now need to add a reference the System.Windows.Forms assembly.

  7. In the Solution Explorer, right-click ExcelAddInLibrary and click Add Reference.

  8. In the Add Reference dialog box, on the .NET tab, select System.Windows.Forms and click OK.

To add code to the helper assembly

  1. In the Solution Explorer, right-click Class1.vb or Class1.cs and click Rename.

  2. Rename the class Helper.vb or Helper.cs.

  3. Click OK to rename the actual class defined in the file.

  4. If the Helper code file is not currently open, in the Solution Explorer, right-click the Helper.vb or Helper.cs file, and click Viewcode to open the code file.

  5. In the code editor, locate the Helper class. Add a shared (or static) method called ShowMessage. This method should take one parameter of type string with the name message.

  6. In the ShowMessage method, add a call to System.Windows.MessageBox.Show. Pass in the parameter received in the ShowMessage method.

    Public Class Helper
        Public Shared Sub ShowMessage(ByVal message As String)
            System.Windows.Forms.MessageBox.Show(message)
        End Sub
    End Class
    
    public class Helper
    {
        public static void ShowMessage(
            string message)
        {
            System.Windows.Forms.MessageBox.Show(message);
        }
    }
    

Configure the message that is displayed by the helper assembly by using a .NET configuration file.

To add a configuration file

  1. In the Solution Explorer, right-click ExcelAddIn, expand Add and then click New Item.

  2. When using Visual Basic, in the Add New Item – ExcelAddIn dialog box, in the Categories pane, select General.

  3. In the Templates pane, select Application Configuration File and click Add to add the configuration file to the ExcelAddIn project. The configuration file is automatically opened by Visual Studio.

  4. In the app.config file editor, within the configuration element, add the appSettings element.

  5. Within the appSettings element, create a new add element. Add two attributes to this element named key and value. Set message as the value for the key attribute, and hello world for the value attribute.

    <?xml version="1.0" encoding="utf-8" ?>
    <configuration>
      <appSettings>
        <add key="message" value="Hello World"/>
      </appSettings>
    </configuration>
    

To use the helper assembly, add a reference from the add-in. After the assembly is referenced, the add-in can read the message from the configuration file and call the helper assembly with that message.

To reference the helper assembly

  1. In the Solution Explorer, right-click ExcelAddIn and click AddReference.

  2. In the Add Reference dialog box, on the Projects tab, select ExcelAddInLibrary and click OK to add the reference to the ExcelAddInLibrary assembly.

  3. Perform a similar step to add a reference to System.Configuration, which is located on the .NET tab of the Add Reference dialog box.

To call the helper assembly from the add-in

  1. In the Solution Explorer, expand ExcelAddIn and then Excel. Right-click ThisAddIn.vb or ThisAddIn.cs and click View Code.

  2. Add using statements for the System.Configuration and ExcelAddInLibrary namespaces.

    Imports System.Configuration
    Imports ExcelAddInLibrary
    
    using System.Configuration;
    using ExcelAddInLibrary;
    
  3. Locate the ThisAddIn_StartUp method, where the call to MessageBox.Show was added earlier.

  4. Replace the body of the ThisAddIn_StartUp method with the following block of code. The code reads the message from the configuration file and calls the Helper class with that message.

    Private Sub ThisAddIn_Startup(ByVal sender As Object, ByVal e As System.EventArgs)
        Dim message As String = ConfigurationManager.AppSettings("message")
        Helper.ShowMessage(message)
    End Sub
    
    private void ThisAddIn_Startup(object sender, System.EventArgs e)
    {
        string message = ConfigurationManager.AppSettings["message"];
        Helper.ShowMessage(message);
    }
    

To build the solution

  • To verify that everything is set up correctly, compile the solution. On the Build menu, click Build Solution to compile the modified add-in. Make sure that there are no compilation errors.

Using the project reference that you have added earlier to the ExcelAddIn project, the ExcelAddInSetup can locate the helper assembly. The configuration file is tagged as a content file and is added to the setup project as such.

To modify the setup project

  1. In the Solution Explorer, expand ExcelAddInSetup. Right-click DetectedDependencies and click Refresh Dependencies. This detects the reference from ExcelAddIn to ExcelAddInLibrary and automatically includes this helper assembly in the Windows Installer package.

  2. In the Solution Explorer, right-click ExcelAddInSetup, click Add and then Project Output.

  3. In the Add Project Output Group dialog box, confirm that the ExcelAddIn project is selected and select the Content Files option.

  4. Click OK to close the dialog box. This adds the configuration file to the Windows Installer package.

    You can now build the setup project and deploy it to the user computer using the steps described earlier in this article.

Additional Requirements for Document-level Solutions

Deploying document-level solutions require a few different configuration steps in the Windows Installer setup project.

Document-level solutions do not make use of the registry. Instead, the location of the deployment manifest is defined using custom document properties in the Microsoft Office file. By default, the location uses a relative path to the deployment manifest, meaning that if the document is installed into the same folder as the customization assembly you do not need to alter the manifest location contained within the document. However, if you intend to deploy the document to a different folder as the customization assembly, you need to update the document properties to a fully qualified path.

For more information about document properties used by Visual Studio Tools for Office, see Custom Properties Overview

The setup project for document-level solutions requires the same steps as detailed in the walkthrough for a simple installer. However, you do not have to create the registry keys because the Office application does not use them to locate the customization for the document. The download accompanying this article provides a sample document-level solution named ExcelDocumentSolution.

The following list outlines the basic steps required for a document-level solution. Details on how to perform these tasks are found in the Creating a basic installer procedure in Part 1 of this article.

  • Create the Visual Studio 2008 Setup Project.

  • Add the primary output of your document-level solution. The Microsoft Office document itself is also part of the primary output so you do not add it separately to the setup project.

  • Add the deployment and application manifests as loose files.

  • Exclude the dependent components from the installer package.

  • Configure prerequisite packages.

  • Configure launch conditions.

  • Build the setup project and copy the results to the deployment location.

  • Deploy the document-level solution on the user computer by executing the setup.

Changing the Location of the Deployed Document

Using Windows Installer gives you one major advantage: you can move the Microsoft Office document on the user computer to a suitable location such as the user’s My Documents folder. However, you also have to update the location of the deployment manifest inside the document. You can do this with a custom action during installation.

The following steps assume you have created a similar setup project for a document-level solution called ExcelDocumentSolution with a setup project called ExcelDocumentSolutionSetup. The document-level solution sample provided in the download accompanying this article is based on the Excel 2007 Workbook template. The setup project has been configured according to the steps outlined in the Creating a basic installer walkthrough, except for the registry keys that are not used by document-level solutions.

The download accompanying this article contains a sample custom action you use to move the document to the My Documents folder and re-attach the customization. The custom action uses the ServerDocument class to re-attach the customization.

To add the custom action project to your Visual Studio solution

  1. In Windows Explorer, navigate to the {SamplesDir}\projects folder.

  2. Copy the language-specific DocumentManifestCustomActions folder to the root folder of your document-level solution.

  3. In the Solution Explorer, right-click the Solution VSTO v3 Deployment Demo solution

  4. Expand Add and click Existing Project.

  5. Navigate to the folder inside the solution root directory that contains the DocumentManifestCustomActions project.

  6. Select DocumentManifestCustomActions.vbproj or DocumentManifestCustomActions.csproj.

  7. Click Open to add the project to the solution.

    Figure 30. Solution Explorer - Document Manifest Custom Actions

    Solutions Explorer

The custom action requires the solution ID of your Visual Studio Tools for Office document-level solution. This value is retrieved from the Visual Studio 2008 project file. To begin, compile the document-level solution to add the solution ID to this project file.

To retrieve the solution ID

  1. On the Build menu, click Build Solution to build the document-level solution and add the solution ID property to the project file.

  2. In the Solution Explorer, right-click ExcelDocumentSolution.

  3. Click UnloadProject to access the project file from inside Visual Studio.

    Figure 31. Unloading Excel Document Solution

    Unloading Excel Document Solution

  4. In the Solution Explorer, right-click ExcelDocumentSolution and click EditExcelDocumentSolution.vbproj or Edit ExcelDocumentSolution.csproj.

  5. In the ExcelDocumentSolution editor, locate the SolutionID element inside the PropertyGroup element.

  6. Copy the GUID value of this element to a temporary location such as the clipboard or notepad.

    Figure 32. Retrieving the SolutionID

    Retrieving the SolutionID

  7. In the Solution Explorer, right-click ExcelDocumentSolution and click Reload Project.

  8. Click Yes in the dialog box that appears to close the ExcelDocumentSolution editor.

Add the solution ID to the custom action for the document-level solution.

To configure the custom action

  1. In the Solution Explorer, expand DocumentManifestCustomActions.

  2. Right-click ChangeManifestInstaller.vb or ChangeManifestInstaller.cs.

  3. Click View code to edit the code for the custom action.

  4. In the ChangeManifestInstaller code editor, locate SolutionID field inside the ChangeManifestInstaller class.

  5. Change the field to use the solution ID of the ExcelDocumentSolution.

    <RunInstaller(True)> _
    Public Class ChangeManifestInstaller
        Inherits Installer
        Shared ReadOnly SolutionID As New Guid("2d58cc4d-44a1-426a-b936-c483e6945be7")
    End Class
    
    [RunInstaller(true)]
    public class ChangeManifestInstaller
        : Installer
    {
        static readonly Guid SolutionID = 
            new Guid("2d58cc4d-44a1-426a-b936-c483e6945be7");
    }
    
  6. On the File menu, click Save ChangeManifestInstaller.vb or SaveChangeManifestInstaller.cs to save your changes to the custom action class.

The last step is to configure the custom action for the Install and Uninstall steps of the Windows Installer package. The Install step copies the document to the My Documents folder and re-attaches the customization. To perform this task, you need to configure the custom action with additional data. The Uninstall step removes the document from the My Documents folder. This task does not require additional configuration data.

To configure the setup project

  1. In the Solution Explorer, right-click ExcelDocumentSolutionSetup, expand Add and click Project Output.

  2. In the Add Project Output Group dialog box, in the Project list, click DocumentManifestCustomActions.

  3. Select Primary Output and click OK to close the dialog box and add the assembly containing the custom action to the setup project. This copies the assembly to the installation folder chosen by the user and allows it to be called as part of the setup process.

    Figure 33. Document Manifest Custom Actions - Add Project Output Group

    Document Manifest Custom Actions

  4. In the Solution Explorer, right-click ExcelDocumentSolutionSetup.

  5. Expand View and click Custom Actions.

  6. In the Custom Actions(ExcelDocumentSolutionSetup) editor, right-click Custom Actions and click Add Custom Action.

  7. In the Select Item in Project dialog box, in the Look In list, click Application Folder. Select Primary Output from DocumentManifestCustomActions(active) and click OK to add the custom action to the Install step.

  8. Under the Installnode, right-click Primary output from DocumentManifestCustomActions(Active) and click Rename. Name the custom action Copy document to My Documents and attach customization.

  9. Under the Uninstall node, right-click Primary output from DocumentManifestCustomActions(Active) and click Rename. Name the custom action Remove document from My Documents folder.

    Figure 34. Document Manifest Custom Actions

    Document Manifest Custom Actions

  10. In the Custom Actions(ExcelDocumentSolutionSetup) editor, right-click Copy document to My Documents and attach customization and click Properties Window.

  11. In the Properties window, for the CustomActionData property, enter the following values. This passes in the location of the customization DLL, the location of the deployment manifest and the location of the Microsoft Office document. Note that the following text has been wrapped.

    /assemblyLocation="[TARGETDIR]ExcelDocumentSolution.dll"/deploymentManifestLocation="[TARGETDIR]ExcelDocumentSolution.vsto"/documentLocation="[TARGETDIR]ExcelDocumentSolution.xlsx"
    

    Figure 35. Custom Action to Copy Document to My Documents

    Custom Action to Copy Document

  12. Compile and deploy the ExcelDocumentSolutionSetup project.

  13. Look in My Documents folder, and open the ExcelDocumentSolution.xlsx file.

Deploying to the ClickOnce Cache

As a hybrid approach you can combine the benefits of Windows Installer based deployment with the benefits of ClickOnce. To do this, create and configure a basic Windows Installer package that only installs prerequisite components, not the Visual Studio Tools for Office solution itself. After installing the prerequisites and custom components, you can use a custom action to install the solution by using ClickOnce with a tool provided by Visual Studio Tools for Office.

The hybrid approach requires the following:

  • Publish the solution to a location the user can reach using the Publish Wizard.

  • Sign the solution with a certificate issued by a trusted publisher, or a solution that is in the inclusion list. Otherwise, the ClickOnce installation tool returns an error.

The custom action used to call the Visual Studio Tools for Office ClickOnce installation tool is provided in the samples download accompanying this article. The custom action calls the ClickOnce tool for the Install and Uninstall steps of the installation process.

To add the custom action project to your Visual Studio solution

  1. In the Windows Explorer, navigate to the {SamplesDir}\projects folder.

  2. Copy the ClickOnceCustomActions folder from the language specific subfolder of your choice to the root folder of your add-in.

  3. In the SolutionExplorer, right-click the Solution VSTO v3 Deployment Demo solution, expand Add and click ExistingProject.

  4. Navigate to the folder inside the solution root directory containing the ClickOnceCustomActions project, select ClickOnceCustomActions.vbproj or ClickOnceCustomActions.csproj and click Open to add the project to the solution.

    Figure 36. Solution Explorer - ClickOnce Custom Action

    Solution Explorer

You need to add the custom action assembly to the setup project. This involves a step similar to including the primary add-in assembly.

To configure the setup project

  1. In the Solution Explorer, right-click ExcelAddInSetup, click Add and then Project Output.

  2. In the Add Project Output Group dialog box, select the ClickOnceCustomActions project and the Primary Output option. Click OK to close the dialog box.

    Figure 37. ClickOnce Custom Action - Add Project Group Dialog Box

    ClickOnce Custom Action

  3. Ensure that the project output of the ExcelAddIn project (including the manifests) is not added to the setup project. This output is no longer necessary because ClickOnce is used to deploy these files.

  4. In the Solution Explorer, right-click ExcelAddInSetup. Expand View and click Custom Actions to view the custom action editor for ExcelAddInSetup.

  5. In the Custom Actions (ExcelAddInSetup) editor, right-click Custom Actions and click Add Custom Action.

  6. In the Select Item in Project dialog box, in the Look in list, click Application Folder. Select Primary Output from ClickOnceCustomActions(active) and click OK to register the custom actions contained in the ClickOnceCustomActions assembly for execution during installation of the Windows Installer package.

  7. In the Custom Actions(ExcelAddInSetup) editor, under Install, right-click Primary Output from ClickOnceCustomActions(Active) and click Rename. Name the custom action Install into ClickOnce cache.

  8. Under Uninstall, right-click Primary Output from ClickOnceCustomActions(Active) and click Rename. Name the custom action Remove from ClickOnce cache.

    Figure 38. Excel Add-in Setup Custom Actions

    Excell Add-in Setup

  9. Right-click the Install into ClickOnce cache custom action and click Properties.

  10. In the Properties window, set the value of the CustomActionData property to the location where the ExcelAddIn deploys the Publish Wizard.

    Note

    When you use a UNC path you must properly escape some backslash characters so the data is available to the custom action. The following sample shows how to configure the custom action data with a UNC path to the deployment manifest. Note the four slashes at the start of the value and the single slash as intermediary separators. This is due to the automatic escaping of characters in your custom action data.
    /deploymentLocation="\\\\ServerName\ShareName\ExcelAddIn.vsto".

    Figure 39. ClickOnce Custom Actions

    ClickOnce Custom Actions

  11. Compile and deploy the ExcelAddInSetup project.

Adapting the Setup Project for Windows Vista

To install on Microsoft Windows Vista with a Windows Installer file, the MSI must be marked as UAC compliant, otherwise the user is prompted for the credentials of an administrative user. The Windows SDK contains an MSI file editor named Orca that you use to mark MSI files as compliant.

If the Windows Installer package is not set to be UAC compliant, the user receives a security elevation prompt regardless of the tasks being performed by the installer. You must toggle the MSI to be UAC compliant. The ORCA tool is used to create a UAC compliant Windows Installer package. The ORCA tool is installed when following the "Configuring the developer computer for deployment procedure" in Part 1 of this article.

To make the MSI UAC compliant

  1. Build the Setup project.

  2. Exit Visual Studio 2008.

  3. Start Orca and open the MSI from the build folder of the Setup project.

  4. On the View menu, click Summary Information.

  5. Click UAC Compliant.

    Figure 40. Orca Tool - UAC Compliant

    Orca Tool

  6. Click OK.

  7. On the File menu, click Save.

  8. Close Orca.

Known Issues

There is an issue with Visual Studio 2008 RTM and registry keys for application-level add-ins. If the registry key name used for the Visual Studio Tools for Office solution and the name of Visual Studio Tools for Office project inside Visual Studio are the same, then during build time Visual Studio 2008 overwrites the value for the manifest so it matches the Visual Studio 2005 SE manifest format. To avoid this issue make sure that the registry key name differs from the project name such as CompanyName.AddinName. This issue is resolved with Visual Studio 2008 SP1.

Additional Resources

Deploying Visual Studio Tools for the Office System 3.0 Solutions for the 2007 Microsoft Office System Using Windows Installer (Part 1 of 2)

Deploying Solutions for 2007 Office System with ClickOnce Using Visual Studio Tools for the Office System (3.0)

Deploying Solutions for 2007 Office System with ClickOnce Using Visual Studio Tools for the Office System (3.0)

How to: Install the Visual Studio Tools for Office Runtime

Office Primary Interop Assemblies

Registry Entries for Application-Level Add-Ins

Custom Document Properties Overview

Specifying Form Regions in the Windows Registry

Granting Trust to Documents (2007 System)

About the Authors

Wouter van Vugt is a Microsoft MVP with Office Open XML technologies and an independent consultant focusing on creating Office Business Applications (OBAs) with SharePoint, the Office 2007 system and related .NET technologies. Wouter is a frequent contributor to developer community sites such as OpenXmlDeveloper.organd MSDN. He has published several white papers and articles as well a book available on line titled Open XML: Explained e-book. Wouter is the founder of Code-Counsel, a Dutch company focusing on delivering cutting-edge technical content through a variety of channels. You can find out more about Wouter by reading his blog and visiting the Code-Counsel Web site.

Ted Pattison is a SharePoint MVP, author, trainer and the founder of Ted Pattison Group. In the fall of 2005, Ted was hired by Microsoft’s Developer Platform Evangelism group to author the Ascend developer training curriculum for Windows SharePoint Services 3.0 and Microsoft Office SharePoint Server 2007. Since that time, Ted has been entirely focused on educating professional developers on SharePoint 2007 technologies. Ted has just finished writing a book for Microsoft Press titled Inside Windows SharePoint Services 3.0 that focuses on how to use SharePoint as a development platform for building business solutions. Ted also writes a developer-focused column for MSDN Magazine titled Office Space.