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

Summary: Learn to use the ClickOnce deployment technology to deploy Microsoft Office-based solutions built with Visual Studio 2008 Professional. Note that this article was previously published under the title "Deploying Solutions for 2007 Office System with ClickOnce Using Visual Studio Tools for the Office System (3.0)" (20 printed pages)

Robert Green, MCW Technologies, LLC

Published: October 2007

Updated: November 2008

Applies to: 2007 Microsoft Office system, Microsoft Visual Studio 2008 Professional

Contents

• Publishing Solutions Using ClickOnce

• Creating the Sample Application

• Deploying Solutions with the Publish Wizard

• Installing Microsoft Office Solutions

• Publishing Options

• Updating Solutions

• ClickOnce and Visual Studio Tools for Office Runtime Security Checks

• Conclusion

• About the Author

• Additional Resources

Client applications, such as those using Windows Forms or Windows Presentation Foundation, provide a rich user experience and also provide access to local resources such as storage and printing. They have offline support so users can install applications once and use them anywhere.

Solutions built using Microsoft Visual Studio 2008 Professional are client applications with the user interface (UI) provided by familiar applications, such as Microsoft Office Word 2007 or Microsoft Office Excel 2007.

ClickOnce is a deployment technology that allows you to create self-updating Windows-based applications that can be installed and run with minimal user interaction. ClickOnce brings the benefits of Web-based deployment to client applications. In Visual Studio 2008 Professional, you can now deploy solutions for the 2007 Microsoft Office system using ClickOnce.

Like any applications that use the Microsoft .NET Framework, after you create and test a solution in your development environment, you need to deploy it to users. If you make changes to the solution, you need to deploy those updates.

The questions you need to ask and answer to deploy a Microsoft Office solution are no different from those you would ask and answer to deploy a Windows client application. What do users need on their computers to run the solution? How will you deploy the solution to users? How will you deploy updates?

This article introduces using ClickOnce to deploy solutions for the 2007 Office system. The exercises in this article use document-level solutions. The techniques work the same for application-level solutions.

Publishing Solutions Using ClickOnce

A ClickOnce application is any Windows Presentation Foundation, Windows Forms, console application, or Microsoft Office solution published using ClickOnce technology. You can publish a ClickOnce application in three different ways: from a Web page, from a network file share, or from media such as a DVD. After a ClickOnce application is installed, it can run locally even when the computer is offline, or it can be run in an online-only mode without permanently installing anything on the computer. For more information, see Choosing a ClickOnce Deployment Strategy.

When you publish a solution, you must specify a publishing location. This is where Visual Studio copies the solution files necessary for installing the solution. By default, the publishing location is also the installation path. It is from this location that users install the solution from. You can specify an installation path that differs from the publishing location. For example:

• You can publish to a Web site or network share and have the users install from there.

• You can publish to a staging Web site and then copy the files to another Web site for installation.

• You can publish to a network share to test installations and then have users install from a Web site or build CDs for installation.

The Microsoft Office solution contains the following components:

• The Microsoft Office document if you create a document-level solution.

• The customization assembly and any assemblies upon which it relies.

• A deployment manifest file. This identifies the location and the current version of the solution.

• An application manifest file. This identifies the name, version, and location of the customization assembly.

There are two mechanisms for publishing applications from within Visual Studio. You can publish by using the Publish Wizard or by using the Publish page of the Project Designer. The Publish Wizard prompts you for the basic information required to publish a solution. You can use the Publish page to set additional options and customize the publishing process.

Creating the Sample Application

In this exercise, you create a simple Microsoft Office solution to use in the remainder of this article.

To create a Microsoft Office Solution

1. Start Visual Studio. If you use Windows Vista, make sure you are running Visual Studio as administrator so that you have permission to publish to a Web server.

2. Create a Microsoft Office Word 2007 Template solution named ClickOnce Demo.

3. Open the file ThisDocument.vb.

4. Add the following code to the ThisDocument_Startup method:

   Try
       ' Insert the date into the document.
       Me.Content.InsertAfter(DateTime.Today.ToShortDateString())
       ' Go to the end of the line and add two paragraph returns.
       With Me.Application.Selection
           .EndKey(Word.WdUnits.wdLine)
           .TypeParagraph()
           .TypeParagraph()
       End With
   Catch
       MessageBox.Show( _
           "The date could not be added to the document.")
   End Try
   

5. Run the solution and confirm the customization adds the date to the document and adds two lines below the date.

6. Exit Word 2007.

Deploying Solutions with the Publish Wizard

In this exercise, you deploy the Microsoft Office solution by using the Publish Wizard. In the next exercise, you deploy an update to the solution.

1. To publish the solution, in Solution Explorer, right-click the project name and then click Publish. This displays the Publish Wizard dialog box.

2. Type the location where you want to publish the solution. You can specify a URL, as shown in Figure 1, a disk path, a local folder, or a network share.

   Figure 1. Specify the publishing location

   

3. Click Next.

4. Type the location from which users will install the solution. This can be a Web site or network share, as shown in Figure 2. The Wizard sets the default installation path to be the same as the publish location. You can change this if you want.

   Figure 2. Specify the installation location

   

5. Click Finish. Visual Studio builds the solution before publishing it. Visual Studio displays the message "Publish succeeded" in the lower left after it finishes.

6. In Windows Explorer, navigate to the folder, %systemdrive%\inetpub\wwwroot\ClickOnce Demo. You should see contents similar to those shown in Figure 3.

   Figure 3. Folders and files Visual Studio creates after publishing

   

   Visual Studio copied the template to the publishing location and created the file, ClickOnce Demo.vsto. This file is a copy of the deployment manifest file.

   The deployment manifest file is an XML file that describes the solution deployment and tracks the current version number. The Visual Studio Tools for the Office system runtime queries the deployment manifest file to determine which version of the application manifest file to download.

7. Right-click the ClickOnce Demo.vsto file and select Open With…. In the Open With… dialog box, select Notepad from the Other Programs list and clear Always use the selected program to open this kind of file.

   Click OK to view the deployment manifest. Ordinarily, there should be no need to open the manifest file. In this exercise, you are simply viewing the contents as a way to better understand the published solutions.

   Caution
   Ensure the check box Always use the selected program to open this kind of file is not selected. If you associate .vsto files with Notepad by default, ClickOnce functionality will not launch the Visual Studio Tools for Office runtime to begin the installation or to update functionality.

   You should see the following XML, which identifies to the runtime the location of the application manifest file.

   <dependency>
     <dependentAssembly dependencyType="install" 
       codebase="ClickOnce Demo_1_0_0_0\ClickOnce Demo.dll.manifest" 
       size="11704">
   

8. In Windows Explorer, navigate to the folder, Application Files\ClickOnce Demo_1_0_0_0 folder.

   This folder contains the template and the customization assembly. The customization assembly has a .deploy file name extension.

   The folder also contains the file, ClickOnce Demo.dll.manifest. This is the application manifest file, an XML file that provides the runtime with the information it needs to load and update customization assemblies. The folder also contains a copy of the deployment manifest.

   Figure 4. Files contained in ClickOnce Demo_1_0_0_0 folder

   

9. In Notepad, open the file ClickOnce Demo.dll.manifest.

   The following code example indicates to the runtime to retrieve the 1.0.0.0 version of the customization assembly from the ClickOnce cache.

   <dependency>
     <dependentAssembly dependencyType="install" 
      allowDelayedBinding="true" codebase="ClickOnce Demo.dll" 
      size="18944">
      <assemblyIdentity name="ClickOnce Demo" version="1.0.0.0" 
       language="neutral" processorArchitecture="msil" />
   

Installing Microsoft Office Solutions

You can install a Microsoft Office solution from a Web site, a network share or physical media such as a DVD. This section walks you through installing and uninstalling solutions. You can launch the installation by using a number of ways:

• By opening the document.

• By executing the .vsto file.

• By running the Setup program.

• For more advanced deployment scenarios, is to run the Visual Studio Tools for Office installer, %commonprogramfiles%\microsoft shared\VSTO\9.0\VSTOInstaller.exe, and pass the path of the deployment manifest as an argument.

Installing from Web Sites

When you open a document, the Visual Studio Tools for the Office system runtime downloads the deployment manifest file. In this example, the file is ClickOnce Demo.vsto. If the customization is new or updated, the runtime executes the .vsto file using the execution engine component of Visual Studio Tools for the Office system. You can also execute the .vsto file yourself to install the solution.

The Web server does not recognize the .vsto file type by default. If you published the solution to a Web site, first you must add a MIME type to the Web server.

To add a MIME type to the Web server

1. In Control Panel, click Administrative Tools.

2. Click Internet Information Services Manager, and then double-click MIME Types.

3. In the Actions pane, click Add.

4. In the File Name Extension box, type .vsto.

5. In the MIME Type text box, type application/x-ms-vsto, and then click OK.

To install the solution by opening the document

1. From the publish location, copy ClickOnce Demo.dotx to another location, for example the desktop.

2. Ensure the template is not currently open in Visual Studio.

3. Open the template.

   The Microsoft Office Customization Installer dialog box appears. The installer first downloads the deployment manifest file, ClickOnce Demo.vsto.

   Next, the installer checks if the publisher is recognized and trusted. It is not, so the installer displays the dialog box shown in Figure 5.

   Figure 5. Installer prompting for a trust decision if it cannot verify the publisher

   

4. Click Install.

   The runtime for Visual Studio Tools for the Office system runtime downloads the customization.

5. After the installation completes, click Close.

   The document should display the date. The insertion point should be two lines below that.

6. Exit Word 2007.

7. In Control Panel, click Programs and Features. You should see the ClickOnce Demo application, as shown in Figure 6.

   Figure 6. The ClickOnce Demo solution appears in the Program and Features application

   

8. Uninstall ClickOnce Demo.

To install the solution by executing a .vsto file

1. Open the browser. In the address bar, type: http://computer_name/ClickOnce Demo/ClickOnce demo.vsto.

2. You should see the same dialog boxes in the previous steps.

3. Install the solution.

4. Open the Word 2007 template.

   The document should display the date. The insertion point should be two lines below that.

5. Exit Word 2007.

6. Uninstall ClickOnce Demo.

Installing from Network Shares

In this exercise, you publish the solution to a network share and install it from that location.

To publish a solution to a network share

1. Create a ClickOnce Demo folder on a computer on your network and share it. You can use your computer if there is no network available.

2. Return to Visual Studio.

3. In Solution Explorer, right-click the project name, and then click Publish.

4. Type \\computer_name\ClickOnce Demo as the publish location. Click Next.

5. Select From a UNC path or file share.

6. Type**\\**computer_name \ClickOnce Demo as the publishing location. Click Finish.

7. In Windows Explorer, navigate to the shared folder, ClickOnce Demo folder.

You should see contents similar to those you saw previously. By default, each time you publish a solution, Visual Studio increments the revision part of the solution’s version number. The solution you just published is therefore version 1.0.0.1.

To install a solution from a network share

1. Copy ClickOnce Demo.dotx from the publish location and overwrite the previous version. The new version of ClickOnce Demo.dotx downloads the latest deployment manifest file from the Web site location.

2. Install the solution by using one of the installation methods.

3. Open the template.

   The Microsoft Office Customization Installer dialog box appears, as shown in Figure 7. Notice that the installer now retrieves the deployment manifest file from the network share.

   Figure 7. Installer retrieving deployment manifest file from the network share

   

4. Install the customization as before. Confirm that the customization runs.

5. Exit Word 2007, and then uninstall ClickOnce Demo.

6. In Windows Explorer, navigate to the shared folder.

7. Type \\computer_name\ClickOnce Demo and then click OK. You should see the Microsoft Office Customization Installer.

8. Follow the prompts to install the customization.

9. Open the document and confirm the customization runs.

10. Exit Word 2007 and uninstall ClickOnce Demo.

11. In the ClickOnce Demo folder, double-click the setup.exe file. You should see the Microsoft Office Customization Installer.

12. Follow the prompts to install the customization.

13. Open the document and confirm that the customization runs.

In this exercise, you saw three ways you can install an Office solution:

• You can open the document.

• You can execute the deployment manifest file.

• You can run the Setup program.

In this example, all three of these methods download the deployment manifest file and install the customization. However, the Microsoft Office-based solution you built in Visual Studio will run only if the computer has the following software installed:

• Microsoft .NET Framework 3.5

• Visual Studio Tools for Office runtime

• Appropriate Microsoft Office application, including the primary interop assemblies

The Setup program installs the .NET Framework and the Visual Studio Tools for Office runtime if they are not present. These are downloaded from the Microsoft Download Center, or you can specify the location for these prerequisites. The next section demonstrates this.

Publishing Options

The Publish Wizard asks you for two pieces of information: the publish location and installation path. If you are publishing to a Web site, you must specify the installation path, which by default is the publish location. If you are publishing to a disk path or file share and you want the publish location and installation path to differ, you must specify the installation path. If you accept the default or leave the installation path blank, the publish location and install path remain the same. You can use the Publish Location page of the Project Designer to specify a broader range of options and settings for publishing. This section walks through using the Publish Location page to specify additional publishing options.

1. In Visual Studio, in the Project Designer, navigate to the Publish Location page, as shown in Figure 8.

   Figure 8. Publishing options to set on Publish Location page of the Project Designer

   

   On the Publish Location page, you can set or change the publishing and installation folders. You can also select the publish language for the solution. If you choose a language other than English, you must ensure your users installed the Visual Studio Tools for the Office system Language Package or that you add it to the solution’s prerequisites so the Setup program installs it. For more information, see Microsoft Visual Studio 2005 Tools for the Microsoft Office System (VSTO2005) Language Package.

   Automatically increment revision with each release is checked by default. With this option, the revision portion of the version increases each time you publish the solution. Figure 8 shows that the next version is 1.0.0.2.

   Note
   We recommend that you increment the version number each time you publish. If you add significant functionality or resolve a large number of issues, you may want to increment the minor portion rather than the revision portion.

2. Click Prerequisites to view the solution’s prerequisites, as shown in Figure 9.

   Microsoft Office solutions you build with Visual Studio 2008 require both the Microsoft .NET Framework 3.5 and the runtime for Visual Studio Tools for the Office system.

   Figure 9. Prerequisites to view and specify

   

By default, when you publish a solution, Visual Studio creates a Setup.exe file. Because this executable file uses Windows Installer technology to install prerequisites, Windows Installer 3.1 is another prerequisite.

You can specify additional prerequisites, such as SQL Server 2005 Express Edition, if your solution requires them. By default, ClickOnce downloads required components from the vendor’s Web site. You can instruct ClickOnce to install them from a different location. Locations can include the application installation path, a Web site, an intranet site, a network share, or a folder on the user’s computer.

Updating Solutions

As you see, a user can easily install a published solution. However, installing the solution is only part of the value of ClickOnce. Another benefit is automatic application updates. The solution periodically reads its deployment manifest file to see if updates to the customization are available. If updates are available, the Visual Studio Tools for the Office system runtime downloads the new version of the customization.

To control the updating behavior of an application, in the Project Designer, on the Publish Location page, click Updates. This displays the Customization Updates dialog box, as shown in Figure 10.

Figure 10. Setting how often the runtime checks for customization updates

By default, the runtime for Visual Studio Tools for the Office system checks for updates every seven days. This minimizes the performance penalty of checking for updates. If you have five Word 2007 add-ins installed, for example, and each add-in checks each time it loads, you must wait for each add-in to check for updates each time you start Word 2007.

The runtime checks for updates by downloading a new version of the deployment manifest file and checking if it refers to a new version of the application manifest file. You can change this behavior by changing the interval, by turning off automatic checking, or by choosing to check each time the customization runs.

When you install a customization, the installer records the updating behavior. If the behavior changes, the Visual Studio Tools for the Office system runtime records that change the next time it downloads an update.

Suppose you publish and install a customization that uses the default update interval of seven days. Two days later, you make a change to the customization. You also change the updating behavior to check every time. You then republish. Five days later, the runtime for Visual Studio Tools for the Office system checks for an update, discovers one exists, and downloads it. At that time, the runtime records the updating behavior change in the registry.

The next time the user runs the customization, the runtime checks for updates and downloads as necessary.

If you want to change the update behavior immediately, you can have your users reinstall the customization.

To update the published Word 2007 solution

1. On the Publish Location page of the Project Designer, click Updates.

2. Select Check every time the customization runs, and then click OK.

3. Navigate to the ClickOnce Demo folder and delete the existing contents.

4. In Visual Studio, change the Revision portion of the version number to 0.

   You are now republishing the initial version of the solution and, in effect, starting over.

5. Click Publish Now to publish the application again. Notice the Revision portion of the version number is now 1.

6. Uninstall the customization.

7. Navigate to the publishing folder in Windows Explorer.

8. Reinstall the customization by double-clicking Setup.exe or ClickOnce Demo.vsto.

   Note
   Reinstalling is necessary because the currently installed version uses the default update interval of seven days.

9. Recopy the document file, overwriting the current version.

10. Open the document and confirm that the customization runs.

11. Modify the ThisDocument_Startup method to display the date using a different format.

    Me.Content.InsertAfter(DateTime.Today.ToLongDateString())
    

12. Republish the solution by clicking Publish Now in the Publish page of the Project Designer.

13. Open the document and confirm that the date appears in the longer format.

14. In Windows Explorer, navigate to the Application Files folder in the publishing location. You should two folders, one for each version of the solution. These folders contain version specific copies of the files you saw before.

    Figure 11. Visual Studio adds a folder and files to the publish location for the solution

    

15. In Windows Explorer, navigate back to the publishing location folder.

16. In Notepad, open the file ClickOnce Demo.vsto.

    You should see the following XML, which identifies the application manifest file location.

    <dependency>
      <dependentAssembly dependencyType="install" 
       codebase=
       "Application Files\ClickOnce Demo_1_0_0_1\ClickOnce Demo.dll.manifest" 
       size="11628">
    

17. Open the Word 2007 template.

The Visual Studio Tools for the Office system runtime downloads the updated customization. The new customization runs and you should see the date in the longer format.

Automatic updating is a powerful feature of ClickOnce. You simply publish a new version of the customization. When users open the document, they automatically receive and install the update.

Rolling Back Updates

Each time you publish a solution, Visual Studio updates the publishing location and installation path. The top-level folder contains the current deployment manifest file and the deployment manifest files for each published version of the solution. There are folders corresponding to each version and these contain the document customization and application manifest file for that version of the solution.

Keeping these versions of the solutions makes it easy for you to roll back an update. When you open the document, the Visual Studio Tools for the Office system runtime downloads ClickOnce Demo.vsto. This is a copy of the most recent deployment manifest file and indicates which version of the customization to load.

In the previous exercise, you published version 1.0.0.1. The deployment manifest file indicates that version. To load a different version of the customization, you can replace the version in the publishing location or installation path with a previous version.

To roll back the published update

1. In Windows Explorer, navigate to the folder, Application Files\ClickOnce Demo_1_0_0_0.

2. ClickOnce Demo_1_0_0_0.vsto.

3. Make a copy of the file, ClickOnce Demo_1_0_0_0.vsto.

4. Overwrite the ClickOnce Demo.vsto file with the one you just copied.

5. Open the Word 2007 template.

You should see the dialog box shown in Figure 8. The Visual Studio Tools for the Office system runtime downloads the previous customization. You should see the date in the shorter format.

To return to the 1.0.0.1 version of the customization, repeat the previous steps but make a copy of the deployment manifest in the Application Files\ClickOnce Demo_1_0_0_1 folder.

ClickOnce and Visual Studio Tools for Office Runtime Security Checks

When a user installs or updates a Microsoft Office solution, the Visual Studio Tools for the Office system runtime performs the following series of security checks to determine if the solution is trusted:

1. Does the document reside on the user’s computer or in a trusted folder? If it does, the runtime proceeds to the next check. If it does not, the solution does not load.

2. Does the application manifest file identify whether the solution requests FullTrust permission? This is the default. If it does, the runtime proceeds to the next check. If it does not, the solution does not install or update.

3. Is the deployment manifest file in the Internet Explorer Restricted Sites zone? If it is not, the runtime proceeds to the next check. If it is, the solution does not install or update.

4. Is the deployment manifest file signed with an explicity untrusted certificate? If it is not, the runtime proceeds to the next check. If it is, the solution does not install or update.

5. Is the deployment manifest file signed with a trusted published certificate? If it is, the solution installs or updates with no further security checks. If it is not, the runtime proceeds to the next check.

6. Is user prompting (asking the user if he or she trusts the installation) disabled? If it is, the solution does not install or update. If it is not, the runtime proceeds to the next check.

7. Is the solution in the inclusion list? If it is, the solution installs or updates with no further security checks. If it is not, the runtime proceeds to the next check.

8. When prompted, did the user choose to install the solution? If the user did, the solution installs or updates. If the user did not, the solution does not install or update.

The following sections explore in more detail the ClickOnce trust prompt, trusted certificates, and the inclusion list.

Understanding the ClickOnce Trust Prompt

When you installed the Microsoft Office solution in the first exercise, you saw a dialog box that informed you that the publisher could not be verified. This dialog box is the ClickOnce trust prompt. The trust prompt asked you if you wanted to install the customization.

As a best practice, you should not prompt users if they trust the installation. The typical user may not have the knowledge required to make the correct decision. Does the user know if they should not trust it?

You can remove remove the users from the trust decision in two ways. You can sign the ClickOnce manifest file with a trusted publisher certificate or you can add the solution to the inclusion list ahead of time. Both of these techniques allow the installation to proceed without user prompting.

There is an option between providing users with no information and removing them from the decision. You can sign the deployment manifest file with a certificate that has a known identity. The ClickOnce trust prompt then changes to reflect the known identity of the publisher.

Using Digital Certificates

You trust software if you know who published it and you trust that publisher. A digital certificate provides proof of identity. It can also provide proof of trust.

To publish a solution by using ClickOnce, you must sign the application and deployment manifest files with a digital certificate. In the Project Designer, on the Signing tab, shown in Figure 12, notice that Sign the ClickOnce manifest is selected. Notice also that the solution contains the file ClickOnce Demo_TemporaryKey.pfx.

Figure 12. Certificate for signing ClickOnce manifest files

The .pfx file is a personal certificate file. Visual Studio creates this when you create the project.

Note
Visual Studio 2005 creates the .pfx file when you build the solution, unless you specify a certificate.

The certificate contains a public key and a private key. Visual Studio uses these to apply a digital signature to the manifest file. The digital signature provides you with proof no one has altered the manifest files after publishing.

ClickOnce uses the digital signature to verify the publisher and the permission level of the solution. The default certificate is for development purposes, not production, and is therefore not a trusted certificate. It provides no proof of identity or trust. That is why the runtime for Visual Studio Tools for the Office system prompted you for permission to install the solution.

A digital certificate provides proof of identity if it is installed in the Trusted Root Certification Authority certificate store and has not expired or been revoked. A digital certificate provides proof of trust if it provides proof of identity and is installed in the Trusted Publishers certificate store on the user’s computer.

Requiring Trusted Certificates

You can control user prompting and require trusted certificates. To do this, add the following registry key: \HKLM\Software\Microsoft\.NETFramework\Security\TrustManager\PromptingLevel.

Caution
Modify the registry at your own risk. If you corrupt the registry, you might have to reinstall the operating system to fix the problem. Microsoft cannot guarantee that registry problems can be solved.

Then add the following string values for each of the security zones:

• MyComputer

• LocalIntranet

• Internet

• TrustedSites

• UntrustedSites

Set the value of each security zone to one of the following:

• Enabled. The installation prompts the user if the solution is not signed with a trusted certificate. This is the default for the MyComputer, LocalIntranet, and TrustedSites zones.

• AuthenticodeRequired. The user cannot install the solution if it is not signed with a trusted root authority certificate. The installation prompts the user if the solution is not signed with a trusted publisher certificate. This is the default for the Internet zone.

• Disabled. The user cannot install the solution if it is not signed with a trusted publisher certificate. This is the default for the UntrustedSites zone.

If you want to prevent users from making any trust decisions, use Disabled as the value for each security zone.

Inclusion List

If you sign a Microsoft Office solution with a trusted certificate and you install that certificate on the user’s computer, the solution always installs and updates with no need for user prompting. As an alternative to using a trusted certificate, you can add the solution to the inclusion list. The inclusion list is a list of trusted solutions. Visual Studio Tools for the Office system uses the registry to maintain this list.

When a user chooses to trust a solution using the ClickOnce trust prompt, Visual Studio Tools for the Office system adds the solution to the inclusion list. Subsequent updates do not require user prompting, as the solution is in the list of trusted solutions.

You can manually add a solution to the inclusion list, or remove a solution, by using the UserInclusionList class. This class is in the Microsoft.VisualStudio.Tools.Applications.Runtime.Security namespace.

In this exercise, you add a solution to the inclusion list and then install it without prompting. To start, create a Microsoft Office solution.

To add a solution to the inclusion list and then install it

1. Create a Word 2007 Template solution named ClickOnce Demo 2.

2. Open the file ThisDocument.vb.

3. Add the following to the ThisDocument_Startup method.

   Try
       ' Insert the date into the document.
       Me.Content.InsertAfter(DateTime.Today.ToShortDateString())
       ' Go to the end of the line and add two paragraph returns.
       With Me.Application.Selection
           .EndKey(Word.WdUnits.wdLine)
           .TypeParagraph()
           .TypeParagraph()
       End With
   Catch
       MessageBox.Show( _
           "The date could not be added to the document.")
   End Try
   

4. Publish this solution.

5. Next, add the solution to the inclusion list.

6. Create a Windows Forms Application solution.

7. Add a reference to Microsoft.VisualStudio.Tools.Office.Runtime.

8. Add two text boxes to the form. The second text box should be multiline.

9. Add a button to the form.

10. Set the Text property to Add.

11. Add the following code to the Form1.vb code file.

    Imports Microsoft.VisualStudio.Tools.Office.Runtime.Security
    

12. Add the following declarations.

    Private solutionLocation As Uri
    Private entry As AddInSecurityEntry
    

13. Add the following code to the button’s Click event handler.

    solutionLocation = New Uri(TextBox1.Text)
    entry = New AddInSecurityEntry(solutionLocation, TextBox2.Text)
    UserInclusionList.Add(entry)
    

14. Run the application.

15. In the first text box, type the location of the deployment manifest. For example, type:

    http://computer_name/ClickOnce Demo 2/ClickOnce Demo 2.vsto

    or type:

    \\computer_name\ClickOnce Demo 2\ClickOnce Demo 2.vsto

16. Navigate to the publish location, and then open the deployment manifest file.

17. Locate the RSAKeyValue element.

18. Copy the contents of that element, including all child elements.

19. Paste the XML into the second text box on the form, as shown in the following example.

    <RSAKeyValue>
      <Modulus>xS7LuQGcYZYijaXJzuYRiqpHud3XYBsXZv8ELmbUzYA0Pc410pmUF0XAnGOkkEDH7GZHCfGKmdKdT4j7m56iQooL
      QuGoJSpaoqiTV0loVDPfByY+7yvtm424znaj2SkJ0ro4adeF9TOY30EON5pDo4E/bzTr1c+ToYofA0maVo8=</Modulus>
      <Exponent>AQAB</Exponent>
    </RSAKeyValue>
    

20. Click Add.

Finally, you install the solution without user prompting.

1. Return to the publishing location.

2. From the publish location, copy ClickOnce Demo 2.dotx to another location, for example to the desktop.

3. Open the Word template.

4. The runtime for Visual Studio Tools for the Office system should download and install the customization without prompting you for a trust decision.

Conclusion

An add-in or customization for Visual Studio Tools for the Office system needs permission to run. If you build Microsoft Office 2003 solutions with any version of Visual Studio Tools for the Office system or if you build 2007 Office system solutions by using Microsoft Visual Studio 2005 Tools for the 2007 Microsoft Office system (Second Edition), you have to grant full trust permission to the assembly.

By default, these solutions do not have permission to execute. This is a source of confusion and difficulty for developers working with Visual Studio Tools for the Office system. There are documented ways to make this easier. However, they require extra steps and not everyone is fully aware of them.

As you see in this article, Visual Studio 2008 Professional enables you to use ClickOnce to deploy solutions for the 2007 Office system. ClickOnce, by default, gives Microsoft Office solutions full trust permissions. The extra step that has caused issues in the past is now built-in. This is a welcome enhancement to the product.

ClickOnce is easy to use, but it also provides several layers of control. You can determine which of the techniques you have seen here to use for your solutions and customers.

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#, and Microsoft Windows Workflow Foundation. Before joining MCW, Robert worked at Microsoft as the Product Manager for Visual Studio Tools for the Office system.

Additional Resources

For more information, see the following resources:

• Visual Studio Developer Center

• Office Development with Visual Studio Developer Portal

• ClickOnce

• ClickOnce Deployment