Deploying Solutions for 2007 Office...

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 2007 Microsoft Office solutions. (20 printed pages)

Robert Green, MCW Technologies, LLC

October 2007

Applies to: Microsoft Visual Studio 2008, Microsoft Visual Studio Tools for the Microsoft Office System (3.0)

IMPORTANT This article pertains to Visual Studio 2008 Beta 2.

Contents

Publishing Solutions Using ClickOnce
Creating the Sample Application
Deploying Solutions with the Publish Wizard
Installing Microsoft Office Solutions
Publishing Options
Updating Solutions
ClickOnce 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 and Microsoft Visual Studio Tools for the 2007 Microsoft Office system (3.0) are client applications with the user interface (UI) provided by familiar applications, such as Microsoft Office Word 2007 or Microsoft Office Excel 2007.

One of the most important additions to the Microsoft .NET Framework 2.0 and Microsoft Visual Studio 2005 was ClickOnce. 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, you can now deploy solutions for the 2007 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.

You must publish the components of the solution in two places: the publishing location and the installation location.

The location where you publish an application is not necessarily the same as the location from which users install the application. You have several options, 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

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.
Create a Microsoft Office Word 2007 Template solution named ClickOnce Demo.
Open the file ThisDocument.vb.

Add the following code to the ThisDocument_Startup method:

Visual Basic

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

Run the solution and confirm the customization adds the date to the document and adds two lines below the date.
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.

To publish the solution, in Solution Explorer, right-click the project name and then click Publish. This displays the Publish Wizard dialog box.
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
Click Next.
Type the location from which users will install the solution. This can be a Web site or network share, as shown in Figure 2.

Figure 2. Specify the installation location
Click Finish. Visual Studio builds the solution before publishing it. Visual Studio displays the message "Publish succeeded" in the lower left after it finishes.
In Windows Explorer, navigate to the folder, 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 with the files ClickOnce Demo.vsto and ClickOnce Demo_1_0_0_0.vsto. These files are deployment manifest files for the solution (though Explorer lists them as application manifest files). The first file represents the current deployment manifest file. The second file represents the deployment manifest file for the 1.0.0.0 version of the solution. At this point, 1.0.0.0 is the current version.

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

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

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, you break ClickOnce installation and updating functionality for Microsoft Office solutions.

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

Xml

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

In Windows Explorer, navigate to the ClickOnce Demo_1_0_0_0 folder.

This folder, as shown in Figure 4, contains the template and the customization assembly. The customization assembly has a .deploy file name extension.

The file, ClickOnce Demo.dll.manifest, is the application manifest file. The application manifest file is an XML file that provides the runtime with the information it needs to load and update customization assemblies.

Figure 4. Files contained in ClickOnce Demo_1_0_0_0 folder

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.

Xml

<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 one of three ways:

By opening the document.
By executing the .vsto file.
By running the Setup program.

Installing from Web Sites

When you open a document, the runtime for Visual Studio Tools for the Office system downloads the deployment manifest file and the file 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

In Control Panel, click Administrative Tools.
Click Internet Information Services Manager, and then double-click MIME Types.
In the Actions list, click Add.
In the File Name Extension box, type .vsto.
In the MIME Type text box, type application/octet-stream, and then click OK.

To install the solution by opening the document

From the publish location, copy ClickOnce Demo.dotx to another location, for example the desktop.
Ensure the template is not currently open in Visual Studio.
Open the template.

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

Figure 5. Installer downloading the deployment manifest file

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

Figure 6. Installer prompting for a trust decision if it cannot verify the publisher
Click Install.

You should see the dialog box shown in Figure 7. The runtime for Visual Studio Tools for the Office system is downloading the customization.

Figure 7. Installer installing the customization
After the installation completes, click Close.

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

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

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

Uninstall ClickOnce Demo.

To install the solution from executing a .vsto file

Open the browser. In the address bar, type http://vistavpc/ClickOnce Demo/ClickOnce demo.vsto.
You should see the same dialog boxes in the previous steps.
Install the solution.
Open the Word 2007 template.

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

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

Create a ClickOnce Demo folder on your computer and share it.
Return to Visual Studio.
In Solution Explorer, right-click the project name, and then click Publish.
Type \\vistavpc\ClickOnce Demo as the publish location. Click Next.
Select From a UNC path or file share.
Type \\vistavpc\ClickOnce Demo as the publish location. Click Finish.

In Windows Explorer, navigate to the ClickOnce Demo folder.

You should see contents similar to those you saw earlier. However, this time you see a ClickOnce Demo_1_0_0_1.vsto file and a ClickOnce Demo_1_0_0_1 folder.

Each time you publish a solution, Visual Studio increments the revision part of the solution’s version number. You see how to control this later in the article.

To install a solution from a network share

Copy ClickOnce Demo.dotx from the publish location and overwrite the previous version.

The first version of the document downloads the deployment manifest file from the Web site location. The new version of the document downloads it from the network share.
Install the solution by using each of the three installation methods.
Open the template.

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

Figure 9. Installer retrieving deployment manifest file from the network share
Install the customization as before. Confirm that the customization runs.
Exit Word 2007, and then uninstall ClickOnce Demo.
On the desktop, click Start and then click Run.
Type \\vistavpc\ClickOnce Demo and then click OK.
In the ClickOnce Demo folder, double-click the ClickOnce Demo.vsto file.

You should see the Microsoft Office Customization Installer.
Follow the prompts to install the customization.
Open the document and confirm the customization runs.
Exit Word 2007 and uninstall ClickOnce Demo.
In the ClickOnce Demo folder, double-click the setup.exe file.

You should see the Microsoft Office Customization Installer.
Follow the prompts to install the customization.
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.

All three of these methods download the deployment manifest file and install the customization.

Publishing Options

The Publish Wizard asks you for two pieces of information: the publishing location and installation location. When you click Finish, Visual Studio publishes the solution. You can use the Publish tab of the Project Designer to specify a broader range of options and settings for publishing. This section walks through using the Publish tab to specify additional publishing options.

In Visual Studio, in the Project Designer, navigate to the Publish tab, as shown in Figure 10.

Figure 10. Publishing options to set on Publish tab of the Project Designer

On the Publish tab, 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. 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 10 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.

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

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 11. 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 location, 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. The other value 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 runtime for Visual Studio Tools for the Office system downloads the new version of the customization.

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

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

Controlling how often to check for 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's 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 in the registry. If the behavior changes, the runtime for Visual Studio Tools for the Office system 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

On the Publish tab, click Updates.
Select Check every time the customization runs, and then click OK.
Navigate to the ClickOnce Demo folder and delete the existing contents.
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.
Click Publish Now to publish the application again. Notice the Revision portion of the version number is now 1.
Navigate to the publishing folder in Windows Explorer.
Uninstall the customization.
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.
Recopy the document file, overwriting the current version.
Open the document and confirm that the customization runs.
Modify the ThisDocument_Startup method to display the date using a different format.
Me.Content.InsertAfter(DateTime.Today.ToLongDateString())
Republish the solution and reopen the document.
Navigate to the publishing location in Windows Explorer. You should see contents similar to those shown in Figure 13.

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

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

In Notepad, open the file ClickOnce Demo.vsto.

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

Xml

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

In Windows Explorer, navigate to the ClickOnce Demo_1_0_0_1 folder.

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

You should see the following XML, which tells the runtime to retrieve the 1.0.0.1 version of the customization assembly from the ClickOnce cache.

Xml

<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" />

Open the Word 2007 template.

You should see the dialog box shown in Figure 14. The runtime for Visual Studio Tools for the Office system downloads the updated customization. The new customization runs and you should see the date in the longer format.

Figure 14. Installing the updated version of the customization

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 location. 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 runtime for Visual Studio Tools for the Office system downloads ClickOnce Demo.vsto. This is the current 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 modify the contents of the manifest file, or you can replace it with a previous version.

To roll back the published update

Navigate to the publishing folder in Windows Explorer.
Delete the file ClickOnce Demo.vsto.
Make a copy of the file, ClickOnce Demo_1_0_0_0.vsto.
Rename the copy ClickOnce Demo.vsto.
Open the Word 2007 template.

You should see the dialog box shown in Figure 8. The runtime for Visual Studio Tools for the Office system 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 ClickOnce Demo_1_0_0_1.vsto.

Note:
Visual Studio overwrites the Setup.exe file each time you publish. The setup program installs prerequisites, if necessary, and then downloads the deployment manifest file. Unless the prerequisites change there is no need to maintain multiple versions of this file.

ClickOnce Security Checks

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

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.
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.
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.
Is the deployment manifest file signed with an untrusted certificate? If it is not, the runtime proceeds to the next check. If it is, the solution does not install or update.
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.
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.
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.
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 15, notice that Sign the ClickOnce manifest is selected. Notice also that the solution contains the file ClickOnce Demo_TemporaryKey.pfx.

Figure 15. 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 publish the solution, not when you create the project.

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.

Working with Trusted Root Certificates

In this exercise, you sign the ClickOnce manifest with a trusted root certificate. You then install the solution with user prompting.

To sign the ClickOnce manifest

In Project Designer, click the Signing tab.
To view more information about the existing certificate, click More Details.

This displays the Certificate dialog box, as shown in Figure 16. You can see that the certificate is not trusted. There is no proof of identity.

Figure 16. Default certificate is not trusted
Click OK to close the dialog box.

Trusted certificates should be password protected. The existing certificate in the solution is not password protected, so you should create a new certificate.
Delete the file ClickOnce Demo_TemporaryKey.pfx.
Click Create Test Certificate.
Type and confirm a password, and then click OK.
Rename the certificate file to ClickOnce Demo.pfx.

Note:

Though not required, renaming the certificate file in this way identifies the certificate file as a trusted certificate.
Click More Details.

The Certificate dialog box now has an Install Certificate button.
Click Install Certificate to display the Certificate Import Wizard, and then click Next.
On the Certificate Store page, click Place all certificates in the following store.
Click Browse to display the Select Certificate Store dialog box.
Click Trusted Root Certification Authorities (Figure 17), and then click OK.

Figure 17. Certificate installed in certificate store identifies the publisher
Click Next, and then click Finish.

A security warning is displayed informing you that Windows cannot validate that the certificate is from you. Click Yes to install the certificate.
Click Install Certificate.
Close the Certificate dialog box, and then reopen it.

The Certificate dialog box reflects that the certificate has a proof of identity, as shown in Figure 18.

Figure 18. Certificate provides proof of identity
Click OK to close the Certificate window.
In the Project Designer, switch to the Publish tab.
Click Publish Now.

When you see the dialog box that informs you the updated version of the application is signed with a key that is different from the published version, click Yes to overwrite the published application.
Uninstall the ClickOnce Demo solution.
Open the Word document. You could also double-click Setup.exe or double-click the .vsto file.

Note:
Though not required, renaming the certificate file in this way identifies the certificate file as a trusted certificate.

The runtime for Visual Studio Tools for the Office system should download the customization and prompt you for a trust decision, as shown in Figure 19. Notice that the publisher is verified and is displayed in the dialog box. Notice also that the icon in the lower left is yellow now, rather than red.

Figure 19. ClickOnce trust prompt verifies and displays the publisher

Note:
Do not install the customization. You install it in the next exercise.

The user now knows who published this customization and is better equipped to make a trust decision.

Working with Trusted Publisher Certificates

In this exercise, you sign the ClickOnce manifest file with a trusted publisher certificate. You then install the solution without user prompting.

To sign the manifest files with a trusted publisher certificate

Navigate to the project folder.
Double-click the ClickOnce Demo.pfx file to start the Certificate Import Wizard.
Click Next twice.
Type the certificate’s password, and then click Next.
On the Certificate Store page, click Place all certificates in the following store.
Click Browse to display the Select Certificate Store dialog box.
Select Trusted Publishers, as shown in Figure 20.

Figure 20. Certificates installed in this certificate store are fully trusted
Click OK.
Click Next, and then click Finish.
In the Project Designer, click the Publish tab.
Click Publish Now.
Open the Word document. You could also double-click Setup.exe or double-click the .vsto file.

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

Installing Certificates on User Computers

You can decide what level of trust is required and whether to involve users in a trust decision for an individual solution or for an enterprise as a whole.

To avoid prompting users when they install the customization, the certificate must be in the appropriate certificate store on their computers. To automate the installation, you can export the certificate to a certificate file. You can then copy the file and run the certificate management console (certmgr.exe) on each user’s computer to install the certificate, as follows:

certmgr –add ClickOnce Demo.cer –s Root
certmgr –add ClickOnce Demo.cer –s TrustedPublisher

To export the certificate, use the Microsoft Management Console.

To export the certificate

From the desktop, click Start, click Run, and then type MMC.
On the File menu, click Add/Remove Snap-in.
Click Add.
In the list of available snap-ins, click Certificates, and then click Add.
When prompted, choose My user account, click Finish, and then click OK.
Expand the Certificates node, and then expand the Trusted Publishers node.
Click the Certificates sub node. You should see the certificate in the right-hand pane.

On the Actions menu, point to All Tasks, and then click Export. Use the Certificate Export Wizard to save the certificate to a file with a .cer extension.

Note:
If you installed Visual Studio 2005, you can find the certmgr.exe file in the path local_drive:`\\Program Files\Microsoft Visual Studio 8\SDK\v2.0\Bin`. Visual Studio 2008 does not currently install this file.

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.

Warning:
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 publisher 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 publisher 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

Create a Word 2007 Template solution named ClickOnce Demo 2.
Open the file ThisDocument.vb.

Add the following to the ThisDocument_Startup method.

Visual Basic

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

Publish this solution.

Next, add the solution to the inclusion list.
Create a Windows Forms Application solution.
Add a reference to Microsoft.VisualStudio.Tools.Office.Runtime.
Add two text boxes to the form. The second text box should be multiline.
Add a button to the form.
Set the Text property to Add.

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

Visual Basic

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

Add the following declarations.

Visual Basic

Private solutionLocation As Uri
Private entry As AddInSecurityEntry

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

Visual Basic

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

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

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

or type:

\\vistavpc\ClickOnce Demo 2\ClickOnce Demo 2.vsto
Navigate to the publish location, and then open the deployment manifest file.
Locate the RSAKeyValue element.
Copy the contents of that element, including all child elements.

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

Xml

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

Click Add.

Finally, you install the solution without user prompting.

Return to the publishing location.
From the publish location, copy ClickOnce Demo 2.dotx to another location, for example to the desktop.
Open the Word template.
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 Tools for the Office system now uses 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:

Product Families

Resources

About Microsoft

Popular Places

Popular Searches

Popular Downloads

Publishing Solutions Using ClickOnce

Creating the Sample Application

To create a Microsoft Office Solution

Deploying Solutions with the Publish Wizard

Installing Microsoft Office Solutions

Installing from Web Sites

To add a MIME type to the Web server

To install the solution by opening the document

To install the solution from executing a .vsto file

Installing from Network Shares

To publish a solution to a network share

To install a solution from a network share

Publishing Options

Updating Solutions

To update the published Word 2007 solution

Rolling Back Updates

To roll back the published update

ClickOnce Security Checks

Understanding the ClickOnce Trust Prompt

Using Digital Certificates

Working with Trusted Root Certificates

To sign the ClickOnce manifest

Working with Trusted Publisher Certificates

To sign the manifest files with a trusted publisher certificate

Installing Certificates on User Computers

To export the certificate

Requiring Trusted Certificates

Inclusion List

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

Conclusion

About the Author

Additional Resources