Walkthrough: Deploying Multiple Office Solutions in a Single ClickOnce Installer for the .NET Framework 4

  • Article

You can deploy multiple Office solutions in a single package to simplify the installation and update process. This requires that you modify and re-sign the application and deployment manifests after publishing and before installation.

Applies to: The information in this topic applies to document-level projects and application-level projects for Microsoft Office 2010 and the 2007 Microsoft Office system. For more information, see Features Available by Office Application and Project Type.

This walkthrough illustrates the following tasks:

  • Creating two Office solutions to deploy, and one Office solution as the installer project.

  • Modifying the application manifest of the installer project to install two Office solutions.

  • Re-signing the application and deployment manifests.

Note

Your computer might show different names or locations for some of the Visual Studio user interface elements in the following instructions. The Visual Studio edition that you have and the settings that you use determine these elements. For more information, see Visual Studio Settings.

Prerequisites

You need the following components to complete this walkthrough:

-

An edition of Visual Studio 2010 that includes the Microsoft Office developer tools. For more information, see [Configuring a Computer to Develop Office Solutions](bb398242\(v=vs.100\).md).

  • Word 2007 or Word 2010.

  • Outlook 2007 or Outlook 2010.

  • Excel 2007 or Excel 2010.

  • A test computer.

Creating Multiple Office Solutions

Start by creating three Office projects, one of which functions as the installer. The other two will be deployed to the end user computer.

To create and develop new Word, Outlook, and Excel projects

  1. Create a Word document-level project for the .NET Framework 4. Name the project ContosoInstaller, and save the project to the %USERPROFILE%\Documents\Visual Studio 2010\Projects directory.

    The ContosoInstaller project will be used as the installer. For more information, see How to: Create Office Projects in Visual Studio.

  2. In the ContosoInstaller solution, add an Outlook application-level project with the name ContosoOutlookAddIn, and add your code to the Outlook project.

  3. In the ContosoInstaller solution, add an Excel document-level project with the name ContosoExcelWorkbook, and add your code to the Excel project.

Publishing the Office Solutions

Use the Publish Wizard or the Project Page of the Project Designer to publish the Office solutions to the development computer.

To publish the Word, Outlook, and Excel projects

  1. Publish the ContosoInstaller project to c:\publish folder. For more information, see How to: Publish an Office Solution by Using ClickOnce.

  2. Publish the ContosoOutlookAddIn project to the c:\publish folder.

  3. Publish the ContosoExcelWorkbook project to the c:\publish folder.

Modifying the Application Manifest

Use the XML editor in Visual Studio to add install dependencies, files, entry points, and assemblies to the application manifest. The content of an application manifest is similar to a bill of materials, which lists the entire contents of a box; an application manifest lists all dependent and prerequisite assemblies, as well as files needed by the application. The application manifest for an Office solution also lists the assemblies that should be loaded by an Office application for application-level add-ins and document-level customizations.

Adding the Install Dependencies

Modify the application manifest to install the ContosoOutlookAddin and ContosoExcelWorkbook assemblies, and remove references to the ContosoInstaller assembly.

To add installation dependencies to the application manifest

  1. From the c:\publish\Application Files folder, move the contents of the ContosoOutlookAddIn_1_0_0_0 and ContosoExcelWorkbook_1_0_0_0 directories to the ContosoInstaller_1_0_0_0 directory.

  2. Open the ContosoInstaller.dll.manifest, ContosoOutlookAddIn.dll.manifest, and ContosoExcelWorkbook.dll.manifest files in an XML editor.

  3. From the ContosoOutlookAddIn.dll.manifest file, copy all install and file dependencies including ContosoOutlookAddIn.dll. That is, copy all dependencies that start with <dependentAssembly dependencyType="install" or <file name="app.config">. The following code is what you should be looking for: only the <dsig:DigestValue> element will vary.

      <dependency>
    <dependentAssembly 
       dependencyType="install"
       allowDelayedBinding="true" 
       codebase="Microsoft.Office.Tools.Common.v4.0.Utilities.dll" 
       size="30816">
      <assemblyIdentity 
        name="Microsoft.Office.Tools.Common.v4.0.Utilities" 
        version="10.0.0.0"
        publicKeyToken="B03F5F7F11D50A3A"
        language="neutral"
        processorArchitecture="msil" />
      <hash>
        <dsig:Transforms>
          <dsig:Transform
            Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" />
        </dsig:Transforms>
        <dsig:DigestMethod 
          Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <dsig:DigestValue>Ki0…</dsig:DigestValue>
      </hash>
    </dependentAssembly>
  </dependency>
  <dependency>
    <dependentAssembly
      dependencyType="install"
      allowDelayedBinding="true" 
      codebase="Microsoft.Office.Tools.Outlook.v4.0.Utilities.dll"   
      size="47200">
      <assemblyIdentity 
        name="Microsoft.Office.Tools.Outlook.v4.0.Utilities" 
        version="10.0.0.0"
        publicKeyToken="B03F5F7F11D50A3A"
        language="neutral" 
        processorArchitecture="msil" />
      <hash>
        <dsig:Transforms>
          <dsig:Transform
            Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" />
        </dsig:Transforms>
        <dsig:DigestMethod 
          Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <dsig:DigestValue>050...</dsig:DigestValue>
      </hash>
    </dependentAssembly>
  </dependency>
  <dependency>
    <dependentAssembly
      dependencyType="install" 
      allowDelayedBinding="true"
      codebase="ContosoOutlookAddIn.dll"
      size="10240">
      <assemblyIdentity
        name="ContosoOutlookAddIn" 
        version="1.0.0.0" 
        language="neutral" 
        processorArchitecture="msil" />
      <hash>
        <dsig:Transforms>
          <dsig:Transform Algorithm=
            "urn:schemas-microsoft-com:HashTransforms.Identity" />
        </dsig:Transforms>
        <dsig:DigestMethod Algorithm=
          "http://www.w3.org/2000/09/xmldsig#sha1" />
        <dsig:DigestValue>i4e</dsig:DigestValue>
      </hash>
    </dependentAssembly>
  </dependency>
  <file name="ContosoOutlookAddIn.dll.config" size="77">
    <hash>
      <dsig:Transforms>
        <dsig:Transform Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" />
      </dsig:Transforms>
      <dsig:DigestMethod 
         Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <dsig:DigestValue>w7W...</dsig:DigestValue>
    </hash>
  </file>

  4. In the ContosoInstaller.dll.manifest file, paste the ContosoOutlookAddIn.dll install dependency at the end of the dependency section.

  5. From the ContosoExcelWorkbook.dll.manifest file, copy all install and file dependencies, including ContosoExcelWorkbook.dll and Microsoft.Office.Tools.Common.v4.0.Utilities.dll. That is, copy all dependencies that start with <dependentAssembly dependencyType="install" or <file name="app.config">. The following code resembles what you should be looking for: only the <dsig:DigestValue> element will vary.

      <dependency>
    <dependentAssembly
      dependencyType="install"
      allowDelayedBinding="true"
      codebase="ContosoExcelWorkbook.dll"
      size="12800">
      <assemblyIdentity
        name="ContosoExcelWorkbook" 
        version="1.0.0.0"
        language="neutral"
        processorArchitecture="msil" />
      <hash>
        <dsig:Transforms>
          <dsig:Transform Algorithm=
            "urn:schemas-microsoft-com:HashTransforms.Identity" />
        </dsig:Transforms>
        <dsig:DigestMethod Algorithm=
          "http://www.w3.org/2000/09/xmldsig#sha1" />
        <dsig:DigestValue>i4e</dsig:DigestValue>
      </hash>
    </dependentAssembly>
  </dependency>
  <dependency>
    <dependentAssembly dependencyType="install" allowDelayedBinding="true" codebase="Microsoft.Office.Tools.Common.v4.0.Utilities.dll" size="30816">
      <assemblyIdentity name="Microsoft.Office.Tools.Common.v4.0.Utilities" version="10.0.0.0" publicKeyToken="B03F5F7F11D50A3A" language="neutral" processorArchitecture="msil" />
      <hash>
        <dsig:Transforms>
          <dsig:Transform Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" />
        </dsig:Transforms>
        <dsig:DigestMethod Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <dsig:DigestValue>Ki0A9wOpes1YX5NaAvjmUeFSh0g=</dsig:DigestValue>
      </hash>
    </dependentAssembly>
  </dependency>
  <dependency>
    <dependentAssembly
      dependencyType="install"
      allowDelayedBinding="true" 
      codebase="Microsoft.Office.Tools.Excel.v4.0.Utilities.dll" 
      size="235104">
      <assemblyIdentity 
        name="Microsoft.Office.Tools.Excel.v4.0.Utilities" 
        version="10.0.0.0"
        publicKeyToken="B03F5F7F11D50A3A"
        language="neutral"
        processorArchitecture="msil" />
      <hash>
        <dsig:Transforms>
          <dsig:Transform
           Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" />
        </dsig:Transforms>
        <dsig:DigestMethod 
          Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
        <dsig:DigestValue>Te/...</dsig:DigestValue>
      </hash>
    </dependentAssembly>
  </dependency>
  <file name=" ContosoExcelWorkbook.dll.config" size="77">
    <hash>
      <dsig:Transforms>
        <dsig:Transform
         Algorithm="urn:schemas-microsoft-com:HashTransforms.Identity" />
      </dsig:Transforms>
      <dsig:DigestMethod 
        Algorithm="http://www.w3.org/2000/09/xmldsig#sha1" />
      <dsig:DigestValue>w7W...</dsig:DigestValue>
    </hash>
  </file>

  6. In the ContosoInstaller.dll.manifest file, paste the install dependencies at the end of the dependency section.

  7. In the ContosoInstaller.dll.manifest file, remove the ContosoInstaller.dll and Microsoft.Office.Tools.Word.v4.0.Utilities.dll install dependencies. Also remove any duplicate dependencies. For example, you may have copied multiple install dependencies for Microsoft.Office.Tools.Common.v4.0.Utilities.dll.

    Note

    If you are deploying a Word document-level solution, leave Microsoft.Office.Tools.Word.v4.0.Utilities.dll in the final manifest.

Adding the Entrypoints

Modify the application manifest to load the ContosoOutlookAddin and ContosoExcelWorkbook assemblies into the <vstav3> namespace.

To add the entrypoints in the vstav3 namespace to the application manifest

  1. In the ContosoInstaller.dll.manifest file, remove the text between the <vstav3:entryPointsCollection> and </vstav3:entryPointsCollection> elements.

  2. From the ContosoOutlookAddIn.dll.manifest file, copy the text between the <vstav3:entryPointsCollection> and </vstav3:entryPointsCollection> elements. The following code resembles what you should be looking for.

          <vstav3:entryPoints>
        <vstav3:entryPoint
          class="ContosoOutlookAddIn.ThisAddIn">
          <assemblyIdentity
            name="ContosoOutlookAddIn"
            version="1.0.0.0"
            language="neutral"
            processorArchitecture="msil" />
        </vstav3:entryPoint>
      </vstav3:entryPoints>

    Note

    If the Outlook application-level add-in uses a form region, the Outlook entry point must be the last one listed in the <vstav3:entryPoints> section.

  3. In the ContosoInstaller.dll.manifest file, paste the code after the <vstav3:entryPointsCollection> element.

  4. Add the id attribute to the <vstav3:entryPoints> element to differentiate this entrypoint from others.

          <vstav3:entryPoints id="ContosoOutlook">

  5. From the ContosoExcelWorkbook.dll.manifest file, copy the text between the <vstav3:entryPointsCollection> and </vstav3:entryPointsCollection> elements. The following code resembles what you should be looking for.

          <vstav3:entryPoints>
        <vstav3:entryPoint 
          class="ContosoExcelWorkbook.ThisWorkbook">
          <assemblyIdentity
            name="ContosoExcelWorkbook"
            version="1.0.0.0"
            language="neutral"
            processorArchitecture="msil" />
        </vstav3:entryPoint>
        <vstav3:entryPoint
           class="ContosoExcelWorkbook.Sheet1">
          <assemblyIdentity
            name="ContosoExcelWorkbook"
            version="1.0.0.0"
            language="neutral"
            processorArchitecture="msil" />
        </vstav3:entryPoint>
        <vstav3:entryPoint
          class="ContosoExcelWorkbook.Sheet2">
          <assemblyIdentity
            name="ContosoExcelWorkbook"
            version="1.0.0.0"
            language="neutral"
            processorArchitecture="msil" />
        </vstav3:entryPoint>
        <vstav3:entryPoint
          class="ContosoExcelWorkbook.Sheet3">
          <assemblyIdentity
            name="ContosoExcelWorkbook"
            version="1.0.0.0"
            language="neutral"
            processorArchitecture="msil" />
        </vstav3:entryPoint>
      </vstav3:entryPoints>

  6. In the ContosoInstaller.dll.manifest file, paste the code after the <vstav3:entryPointsCollection> element.

  7. Add the id attribute to the <vstav3:entryPoints> element to differentiate this entry point from other entry points.

          <vstav3:entryPoints id="ContosoExcel">

Adding the assemblies

Modify the application manifest to load the ContosoOutlookAddin and ContosoExcelWorkbook assemblies into the <vstov4> namespace.

To add the assemblies to the vstov4 namespace in the application manifest

  1. In the ContosoInstaller.dll.manifest file, remove any text between the <vstov4:customizations xmlns:vstov4="urn:schemas-microsoft-com:vsto.v4"> and </vstov4:customizations> elements.

  2. In the ContosoOutlookAddIn.dll.manifest file, copy the text between the <vstov4:customizations xmlns:vstov4="urn:schemas-microsoft-com:vsto.v4"> and </vstov4:customizations> elements. The following code is what you should be looking for.

            <vstov4:customization>
          <vstov4:appAddIn
            application="Outlook"
            loadBehavior="3"
            keyName="ContosoOutlookAddIn">
            <vstov4:friendlyName>
              ContosoOutlookAddIn
            </vstov4:friendlyName>
            <vstov4:description>
              ContosoOutlookAddIn - Outlook add-in created with
              Visual Studio Tools for Office
            </vstov4:description>
          </vstov4:appAddIn>
        </vstov4:customization>

  3. In the ContosoInstaller.dll.manifest file, paste the code after the <vstov4:customizations xmlns:vstov4="urn:schemas-microsoft-com:vsto.v4"> element.

  4. Add the id attribute to the <vstav3:customization> element to differentiate this customization from others. This id is the same id that was added to the <vstav3:entryPoints> element in the previous procedure.

            <vstov4:customization id="ContosoOutlook">

  5. From the ContosoExcelWorkbook.dll.manifest file, copy the text between the <vstov4:customizations xmlns:vstov4="urn:schemas-microsoft-com:vsto.v4"> and </vstov4:customizations> elements. The following code resembles what you should be looking for: only the <solutionId> element will vary.

            <vstov4:customization>
          <vstov4:document
            solutionId="73e" />
        </vstov4:customization>

  6. In the ContosoInstaller.dll.manifest file, paste the code after the <vstov4:customizations xmlns:vstov4="urn:schemas-microsoft-com:vsto.v4"> element.

  7. Add the id attribute to the <vstov4:customizations xmlns:vstov4="urn:schemas-microsoft-com:vsto.v4"> element to differentiate this customization from others. This id is the same id that was added to the <vstav3:entryPoints> element in the previous procedure.

            <vstov4:customization id="ContosoExcel">

Modifying the Document-Level Project

For all document-level projects in a multi-project deployment, you must append the id to the _AssemblyLocation custom document property. This section demonstrates how to update the _AssemblyLocation property in the ContosoExcelWorkbook.xlsx file, and this step must be repeated for all document-level projects.

To modify the _AssemblyLocation in Excel or Word 2010

  1. In Excel, click the File tab.

  2. Click Info.

  3. Click the Properties drop-down arrow, and then click Advanced Properties.

  4. Click the Custom tab.

  5. In the Properties pane, click _AssemblyLocation.

  6. In the Value textbox, edit the text to remove |vstolocal (if the text exists) and add |id=ContosoInstaller.

  7. Click OK.

To modify the _AssemblyLocation in Excel or Word 2007

  1. In Excel, click the Microsoft Office Button.

  2. Point to Prepare, and then click Properties.

  3. Click the Document Properties drop-down arrow, and then click Advanced Properties.

  4. Click the Custom tab.

  5. In the Properties pane, click _AssemblyLocation.

  6. In the Value textbox, edit the text to remove |vstolocal (if the text exists) and add |id=ContosoInstaller.

  7. Click OK.

Re-signing the Manifests

Sign the application and deployment manifests with a certificate. This ensures that the files have not been tampered with.

To re-sign the application and deployment manifests

  1. Copy the ContosoInstaller_TemporaryKey.pfx certificate file from the %USERPROFILE%\Documents\Visual Studio 2010\Projects\ContosoInstaller\ContosoInstaller solution directory into the c:\publish\Application Files\ContosoInstaller_1_0_0_0directory.

  2. Open the Visual Studio command prompt.

  3. Change to the c:\publish\Application Files\ContosoInstaller_1_0_0_0 directory.

  4. Sign the modified application manifest with the following command:

    mage -sign ContosoInstaller.dll.manifest -certfile ContosoInstaller_TemporaryKey.pfx

    The message "ContosoInstaller.dll.manifest successfully signed" appears.

  5. Change to the c:\publish directory.

  6. Update and sign the deployment manifest with the following command:

    mage -update ContosoInstaller.vsto -appmanifest "Application Files\ContosoInstaller_1_0_0_0\ContosoInstaller.dll.manifest" -certfile "Application Files\ContosoInstaller_1_0_0_0\ContosoInstaller_TemporaryKey.pfx"

    The message "ContosoInstaller.vsto successfully signed" appears.

  7. Copy the ContosoInstaller.vsto file to the c:\publish\Application Files\ContosoInstaller_1_0_0_0 directory.

Testing the Multi-Project Deployment

The following procedure ensures that the manifest installs the Outlook add-in and the Excel workbook.

To test the multi-project deployment

  1. Copy the c:\publish directory to a test computer.

  2. Run the Setup program to install the multi-project deployment.

    The Microsoft Office Customization Installer appears.

  3. Click Install.

    The Microsoft Office Customization Installer dialog box shows the following message: "The Microsoft Office customization was successfully installed."

  4. Open Outlook to verify that the add-in works.

  5. Open the Excel workbook file to verify that the document-level customization works.

  6. Verify that the multi-project deployment has a single entry in the list of installed applications.

    The Add/Remove Programs in Windows XP or Programs and Features in Windows Vista shows ContosoInstaller.

Cleaning up the Publish Directory

The following procedure removes any unnecessary files from the publish directory.

To clean up the publish directory

  1. Remove the following files from the c:\publish\Application Files\ContosoInstaller_1_0_0_0 directory.

    • ContosoExcelWorkbook.dll.manifest

    • ContosoExcelWorkbook.vsto

    • ContosoInstaller.dll.deploy

    • ContosoInstaller.docx

    • ContosoInstaller_TemporaryKey.pfx

    • ContosoOutlookAddIn.dll.manifest

    • ContosoOutlookAddIn.vsto

  2. Remove the following files from the c:\publish directory.

    • ContosoExcelWorkbook.vsto

    • ContosoInstaller.docx

    • ContosoOutlookAddIn.vsto

See Also

Tasks

How to: Re-sign Application and Deployment Manifests

Concepts

Securing ClickOnce Applications

Advanced Office Solution Deployment

Other Resources

Deploying Office Solutions