Writing Post Deployment Actions to Copy Office 2010 Documents Using ClickOnce

  • Article

Office Visual How To

Summary:  You can deploy an Office solution by using ClickOnce deployment. You can also perform post-deployment actions such as copying a document to the user's computer during install. Creating the post-deployment action requires writing some code and modifying the application manifest.

Applies to: Excel 2010 | Office 2010 | Open XML | PowerPoint 2010 | VBA | Word 2010

Published:  August 2010

Provided by:  Robert Green, MVP, MCW Technologies

Overview

Scenario: You created a Microsoft Word 2010 document-level solution by using Microsoft Visual Studio 2010. You tested the solution on your computer and now you want to deploy it to users. You can use ClickOnce to deploy the customization assembly. You want to deploy both the document and the customization assembly at the same time, saving users from having to download the document separately. The Visual Studio Tools for Office runtime can perform post-deployment actions after a user installs an Office solution. These actions can include copying a document to the user’s computer, creating registry keys, creating databases and many other possibilities.

ClickOnce uses an application manifest to determine what to install and how to install it. The application manifest can contain instructions on run post-deployment actions. Visual Studio cannot add post-deployment actions to the application manifest. You must modify it yourself. This article describes you how to create a post-deployment action to copy a document to the user's computer when he or she installs a Word document-level solution. For more information about how to deploy Office solutions using ClickOnce, see the links in the Explore It section.

Code It

Follow these steps to configure ClickOnce to run a post-deployment action.

To create the post deployment action

  1. In Visual Studio 2010, load the original sample project, Post Deployment Actions Start\PostDeploymentActions.sln.

  2. On the File menu, select Add and then click New Project.

  3. In the Add New Project dialog box, select Windows in the Installed Templates pane. Select Class Library in the Templates pane. Name the project PostDeploymentAction and then click OK to add the project to the solution.

  4. On the Project menu, select Add Reference to display the Add Reference dialog box. Select the .NET tab of the dialog box.

  5. If your solution is targeting Word 2007, select Microsoft.VisualStudio.Tools.Applications.Runtime.v10.0 and Microsoft.VisualStudio.Tools.Applications.ServerDocument.v10.0.

  6. If your solution is targeting Word 2010, select Microsoft.VisualStudio.Tools.Applications.Runtime and Microsoft.VisualStudio.Tools.Applications.ServerDocument.

  7. Click OK to add the reference and close the dialog box.

  8. In the Solution Explorer window, right-click Class1.vb or Class1.cs and select Rename. Rename the file to CopyWordDocument.vbor CopyWordDocument.cs.

  9. In the Code Editor, add the following code to the top of the file.

    Imports Microsoft.VisualStudio.Tools.Applications.Deployment
Imports Microsoft.VisualStudio.Tools.Applications
Imports System.IO
    using Microsoft.VisualStudio.Tools.Applications.Deployment;
using Microsoft.VisualStudio.Tools.Applications;
using System.IO;

  10. A post-deployment action implements the IAddInPostDeploymentAction interface. Change the declaration of the CopyWordDocument class so that it implements this interface. The class declaration should resemble the following code.

    Public Class CopyWordDocument
  Implements IAddInPostDeploymentAction
    class CopyWordDocument: IAddInPostDeploymentAction

  11. In Visual Basic, press Enter to create the necessary procedure stubs required by the interface. In C#, right-click the interface name, and select Implement Interface, and then Implement Interface (again) to generate the stubs.

  12. The Execute method of the IAddInPostDeploymentAction interface performs the post-deployment action. If you are using C#, remove the code in the Execute method. Add the following code to the Execute method.

    Dim docsDirectory As String = "Docs\MyFabrikamWordDocument.docx"
Dim documentFile As String = "MyFabrikamWordDocument.docx"
Dim sourcePath As String = args.AddInPath
Dim deploymentManifestUri As Uri = args.ManifestLocation
Dim destPath As String = _
  Environment.GetFolderPath(Environment.SpecialFolder.DesktopDirectory)
Dim sourceFile As String = _
  System.IO.Path.Combine(sourcePath, docsDirectory)
Dim destFile As String = System.IO.Path.Combine(destPath, documentFile)

Select Case args.InstallationStatus
  Case AddInInstallationStatus.InitialInstall, _
    AddInInstallationStatus.Update
    If File.Exists(destFile) Then
      File.Delete(destFile)
    End If
    File.Copy(sourceFile, destFile)
    ServerDocument.RemoveCustomization(destFile)
    ServerDocument.AddCustomization(destFile, deploymentManifestUri)
    Exit Select
  Case AddInInstallationStatus.Uninstall
    If File.Exists(destFile) Then
      File.Delete(destFile)
    End If
    Exit Select
End Select
    string docsDirectory = "Docs\\MyFabrikamWordDocument.docx";
string documentFile = "MyFabrikamWordDocument.docx";
string sourcePath = args.AddInPath;
Uri deploymentManifestUri = args.ManifestLocation;
string destPath = Environment.GetFolderPath(
  Environment.SpecialFolder.DesktopDirectory);
string sourceFile = System.IO.Path.Combine(sourcePath, docsDirectory);
string destFile = System.IO.Path.Combine(destPath, documentFile);

if ((args.InstallationStatus == 
  AddInInstallationStatus.InitialInstall) || 
  (args.InstallationStatus == AddInInstallationStatus.Update))
{
  if (File.Exists(destFile))
  {
    File.Delete(destFile);
  }
  File.Copy(sourceFile, destFile);
  ServerDocument.RemoveCustomization(destFile);
  ServerDocument.AddCustomization(destFile, deploymentManifestUri);
  return;
}
else if (args.InstallationStatus == 
  AddInInstallationStatus.Uninstall)
{
  if (File.Exists(destFile))
  {
    File.Delete(destFile);
  }
  return;
}

If you are using Visual Basic and you are targeting the .NET Framework 4, you do not need the underscores in this code.

This code copies the Word document to the user’s desktop when the solution is installed or updated. If the document already exists, the code deletes it first. The code then updates the document’s _AssemblyLocation property so the copied document can locate the customization assembly. The code deletes the document when the solution is uninstalled.

Note

At release, the uninstall code cannot run if you are targeting the .NET Framework 4. The user must manually delete the document when the solution is uninstalled. A service update scheduled for post release changes this behavior so that uninstall actions execute.

To publish the solution

  1. In the Solution Explorer window, select the MyFabrikamWordDocument project.

  2. On the Project menu, select Add Reference to display the Add Reference dialog box. Select the Projects tab of the dialog box.

  3. Select the PostDeploymentActions project.

  4. Click OK to add the reference and close the dialog box.

  5. In the Docs folder of the project, select MyFabrikamWordDocument.docx.

  6. In the Properties window, notice the Build Action property is set to Content and the Copy to Output Directory property is set to Copy if newer.

  7. Save your changes and build the solution.

  8. On the Build menu, select Publish MyFabrikamWordDocument. Visual Studio displays the Publish Wizard.

    Figure 1. Use the Publish Wizard to publish an Office solution


    Publish Wizard

  9. Enter a location where you want to publish the application.

  10. Click Finish to publish the solution and close the Publish Wizard.

  11. In the Windows Explorer, navigate to the publish folder.

    Figure 2. Contents of the publish folder


    Publish folder contents

    The publish folder contains the document and the Setup program. It also contains the deployment manifest (MyFabrikamWordDocument.vsto). This describes how the application is deployed. It includes the location of the application manifest, and the version of the application that clients should run.

  12. Double-click the Application Files folder. This contains a MyFabrikamWordDocument_1_0_0_0 folder. This contains the files that you need to install version 1.0.0.0 of the solution.

  13. Double-click MyFabrikamWordDocument_1_0_0_0 folder.

    Figure 3. Contents of the MyFabrikamWordDocument_1_0_0_0 folder


    Contents of folder

    This folder contains the document, the customization assembly (MyFabrikamWordDocument.dll.deploy) and the post-deployment actions assembly (PostDeploymentAction.dll.deploy). It also contains the deployment manifest (MyFabrikamWordDocument.vsto) and the application manifest (MyFabrikamWordDocument.dll.manifest).

The application manifest contains a list of the prerequisite and dependent assemblies needed to run an Office solution. It also list the assemblies required by the specific document-level or application-level customization. You can modify this file and add a section that relates to the post-deployment action. After modifying it, you must re-sign it. You then must update and re-sign the deployment manifest.

To modify the application manifest

  1. In Visual Studio, on the File menu, select Open File.

  2. In the Open File dialog box, navigate to the Application Files\MyFabrikamWordDocument_1_0_0_0 folder in the publish folder.

  3. Select MyFabrikamWordDocument.dll.manifest and then click Open to open the file.

  4. Add the following XML after the </vstav3:update> element.

    <vstav3:postActions>
  <vstav3:postAction>
    <vstav3:entryPoint class="PostDeploymentAction.CopyWordDocument">
      <assemblyIdentity name="PostDeploymentAction"
                        version="1.0.0.0" language="neutral"
                        processorArchitecture="msil" />
    </vstav3:entryPoint>
  </vstav3:postAction>
</vstav3:postActions>

  5. Save your changes to the application manifest and close the file.

  6. In the Windows Explorer, navigate to the folder that contains the MyFabrikamWordDocument project.

  7. Copy the MyFabrikamWordDocument_TemporaryKey.pfx file into the Application Files\MyFabrikamWordDocument_1_0_0_0 folder in the publish folder. This file is the temporary certificate created by Visual Studio. When you deploy a solution into production, you should use a certificate obtained from a certification authority.

  8. Open the Visual Studio command prompt.

  9. Change to the Application Files\MyFabrikamWordDocument_1_0_0_0 folder.

  10. Enter the following command all on one line to re-sign the application manifest.
    mage -sign MyFabrikamWordDocument.dll.manifest -certfile MyFabrikamWordDocument_TemporaryKey.pfx

  11. The message "MyFabrikamWordDocument.dll.manifest successfully signed" appears.

  12. Change to the publish folder.

  13. Enter the following command all on one line to update and re-sign the deployment manifest.
    mage -update MyFabrikamWordDocument.vsto -appmanifest "Application Files\MyFabrikamWordDocument_1_0_0_0\MyFabrikamWordDocument.dll.manifest" -certfile "Application Files\MyFabrikamWordDocument_1_0_0_0\MyFabrikamWordDocument_TemporaryKey.pfx"

  14. The message "MyFabrikamWordDocument.vsto successfully signed" appears.

  15. In the Windows Explorer, copy the MyFabrikamWordDocument.vsto file from the publish folder to the Application Files\MyFabrikamWordDocument_1_0_0_0 folder.

To test the post-deployment action

  1. In the Windows Explorer, navigate to the publish folder.

  2. Double-click Setup.exe. The Microsoft Office Customization Installer dialog box appears.

    Figure 4. Customization is installing


    Installing the custmization

  3. If you receive a Publisher cannot be verified warning, click Install to continue.

    Figure 5. ClickOnce warns you if the Publisher cannot be verified


    ClickOnce warning

  4. Click Close when the dialog box informs you that the customization was successfully installed.

  5. Navigate to the Desktop and confirm the MyFabrikamWordDocument.docx file appears.

  6. Open the document and confirm the customization runs.

  7. Close the document.

  8. From the Windows Start menu, open Control Panel and select Programs and Features.

  9. Select the MyFabrikamWordDocument icon and then click Uninstall.

  10. If you are targeting the .NET Framework 3.5, navigate to the Desktop and confirm that the document was removed.

  11. If you are targeting the .NET Framework 4, navigate to the Desktop and delete the document.

Read It

Copying a Word document or Excel workbook to the user's computer is a simple example of a post-deployment action. Nonetheless, it is one of the most useful examples. The customization assembly is not much use without the document or workbook to which it belongs. ClickOnce by default does a very good job of installing the customization assembly. You can now take steps to install the document or workbook using post deployment actions.

The code that you add to the Execute method runs when the application is installed, updated or uninstalled. This provides you with the power to write more complex logic and take more involved actions. Perhaps the Office solution uses a local SQL Server Express database. You can create a post-deployment action that creates the database and populates it with certain information. Or perhaps your action removes test data from the database when the user installs the solution and backs up the database every time that the user updates the solution.

If you built Setup applications by using Windows Installer, you may be familiar with creating custom actions that run during an installation. By using the techniques that you learned here, you can use the same capabilities when you use ClickOnce to deploy Office solutions.

 See It

Watch the video

> [!VIDEO https://www.microsoft.com/en-us/videoplayer/embed/7568a286-6d09-4723-876a-7b56b83e89ff]

Length: 08:42

Click to grab code  

Grab the Code

Explore It

About the Author

Robert Green is a developer, writer, and trainer. He is a senior consultant with MCW Technologies. Robert is a Visual Studio Tools for the Office system MVP and is a co-author of AppDev courseware for Microsoft Visual Basic, Microsoft Visual C#, LINQ and Microsoft Windows Workflow Foundation. Before joining MCW, Robert worked at Microsoft as a Product Manager and also a Program Manager.