Deploying Add-ins by Using ClickOnce

Visual Studio Tools for Applications provides the option for you to implement ClickOnce deployment features. ClickOnce gives add-in developers a more secure and maintainable way to publish, install, load, and discover add-ins than simply copying the add-ins to a folder on each user's computer. 

However, ClickOnce adds significant requirements to the add-in developer's deployment process. For example, add-in developers must generate and sign the application and deployment manifests with a certificate by using the Manifest Generation and Editing Tool (Mage.exe), which is available in the Windows Software Development Kit (SDK) and with Microsoft Visual Studio 2008 Professional. Also, Visual Studio Tools for Applications does not include tools to help the add-in developer's ClickOnce deployment experience, such as a publish wizard to package add-ins for distribution or generate required manifests. If you want to provide those tools, you must implement them.

There are several steps to deploying an add-in:

• Generating manifests.

• Publishing add-ins.

• Installing add-ins.

• Discovering and activating add-ins.

Generating Manifests

A ClickOnce installation requires application and deployment manifests, which must be signed. Visual Studio Tools for Applications does not include tools that automatically generate or sign manifests. If you would like to provide these tools, you must implement them.

The main options for the user experience you can provide to your add-in developers are the following two:

• Add-in developers manually create and sign the manifests after development is complete.

• You can add steps during the add-in build process to generate and sign manifests automatically.

Creating Add-in Deployment Manifests

The deployment manifests for Visual Studio Tools for Applications add-ins follow the general ClickOnce schema. You can create deployment manifests by using the Manifest Generation and Editing Tool (Mage.exe). To see how to create a deployment manifest by using Mage.exe, see Walkthrough: Integrating ClickOnce for a Managed Object Model.

Creating Add-in Application Manifests

The application manifests for Visual Studio Tools for Applications add-ins follow the general ClickOnce schema and describe the host application and its dependent assemblies. In addition, they contain a part that is specific to Visual Studio Tools for Applications. For information about the requirements for ClickOnce manifests, see Application Manifests for Office Solutions (2007 System).

The Visual Studio Tools for Applications part of the application manifest must contain an <entrypoints> element in the <vstav2> namespace. The <entrypoints> element contains one or more <entrypoint> elements, which contain the fully qualified name of a class that acts as an entry point. It is usually the host item class that provides a starting point for add-in developers to write their code. For more information about host items, see Creating Project Templates Using the Project Template Generation Tool (Projectgen.exe). 

The optional <update> element indicates whether an add-in checks for updates at regular intervals. The related <expiration> element describes the frequency with which the add-in checks for updates. For more information about the <entrypoints> element, see <entryPoints> Element (2007 System).

The following example demonstrates the Visual Studio Tools for Applications part of a ClickOnce application manifest. It is part of the sample add-in that is included in the ShapeAppBasicCSharp sample. This example uses the host item class as the <entrypoint> element and includes the name of the DLL and version number. For more information about how to create an application manifest for this sample add-in by using Mage.exe, see Walkthrough: Integrating ClickOnce for a Managed Object Model.

<vstav2:addIn xmlns:vstav2=""urn:schemas-microsoft-com:vsta.v2"">
    <vstav2:entryPoints>
        <vstav2:entryPoint class="ShapeAppCSharpAppAddIn.AppAddIn">
            <assemblyIdentity 
                name="ShapeAppCSharpAppAddIn" 
                version=" 1.0.2895.23322" 
                language="neutral" 
                processorArchitecture="msil" />
        </vstav2:entryPoint>
    </vstav2:entryPoints>
    <vstav2:update enabled="true">
        <vstav2:expiration maximumAge="7" unit="days" />
    </vstav2:update>
</vstav2:addIn>

Generating and Signing Manifests with Mage.exe

To manually create and sign the manifests, add-in developers can use the Manifest Generation and Editing Tool (Mage.exe). For an example of how it is used, see Walkthrough: Manually Deploying a ClickOnce Application.

To automate the Manifest Generation and Editing Tool in the host application or stand-alone application, use the command-line version of the tool. You can develop a manifest generation tool that calls Mage.exe with the manifest generation and signing steps. For more information, see and Manifest Generation and Editing Tool (Mage.exe).

Generating Manifests with Build Tasks

MSBuild is the build system for Visual Studio, and build tasks are used to automate different steps of the build. You can write build tasks to generate the application manifest and the add-in specific information for the application manifest. Use the Microsoft.Build.Tasks.Deployment.ManifestUtilities namespace and the PregenerateApplicationManifest build task to create a template for an application manifest for the add-in. The template is saved to the EmbeddedManifestFileNameWithPath property location. Pass this file to your own build task to complete the application manifest. You can model your application manifest generation build task after the GenerateOfficeAddInManifest and GenerateOfficeDocumentManifest build tasks.

To save the application manifest template, set the fully qualified folder in the OutputPath property and the name of the application manifest template in the EmbeddedManifestFileName property. The add-in specific application manifest is set as an XML string in the InputManifest property.

If you want to implement automatic updates for deployed add-ins, assign values to UpdateInterval and UpdateIntervalUnits.

After the application and deployment manifests are created, sign the manifests with a certificate. You can automate manifest signing by calling the Manifest Generation and Editing Tool (Mage.exe) in the Execute method of your build tasks.

To run MSBuild tasks, set the properties and then call the Execute method of the task. Add your build tasks to the .targets file, which defines the standard build process. For more information, see MSBuild .Targets Files.

The following table explains how to use each member of PregenerateApplicationManifest to generate the application manifest. Use this build task to generate the add-in specific part of an application manifest.

Publishing Add-Ins

Publishing involves packaging the add-in build output (assemblies, manifests, and prerequisites such as the .NET Framework) in a Setup program so it can be copied to the location from which end users can download and install it. Installation locations include network file shares, Web sites, SharePoint portals, and CDs.

You can use many different technologies for creating a Setup program, including Windows Installer or the .NET Framework:

• The .NET Framework provides a number of basic features that make it easier to deploy a variety of applications. For more information, see Deploying .NET Framework Applications.

• Windows Installer deployment enables you to create installer packages to be distributed to users. For more information, see Windows Installer Deployment.

Installing Add-Ins

To install the add-in on end user computers with the ClickOnce infrastructure, you call the InstallAddIn method. If you want to provide a graphical user interface (GUI) that provides trust prompting and notification of installation progress, you must implement the IClickOnceAddInInstaller interface.

This interface provides a sequence of methods to enable Visual Studio Tools for Applications host applications to perform actions during the add-in installation. These methods provide a way for you to show the status of downloading the manifests, downloading the add-in, installing the add-in, or uninstalling the add-in.

When add-ins are installed, the files that are stored on the client computer go into a ClickOnce application cache. The ClickOnce cache is a family of hidden directories that hold all of the solution's files, including the assemblies, the configuration files, the application and user settings, and the data directory. For more information, see ClickOnce Cache Overview.

The following table shows the sequence for installing add-ins when you use ClickOnceAddInDeploymentManager and IClickOnceAddInInstaller.

The following table shows other methods to use during add-in installation for tracking download status, catching exceptions, and determining when to go offline.

Discovering and Activating Add-Ins

You must create a deployment manager to discover and load add-ins that are deployed by using ClickOnce. To discover add-ins, you can use static methods in the AddInStoreExtensions class. The methods provided by the AddInStoreExtensions class automatically fill in the values for the Visual Studio Tools for Applications pipeline path and the host application add-in view, which simplifies your work compared to using the methods defined in the AddInStore class.

To load add-ins, you can use the Activate extension methods that Visual Studio Tools for Applications adds to the AddInToken class in the .NET Framework. For more information about extension methods, see Extension Methods (C# Programming Guide) and Extension Methods (Visual Basic) in the MSDN Library for Visual Studio 2008.

For more information about the Visual Studio Tools for Applications architecture, see Understanding the Add-in Pipeline in Visual Studio Tools for Applications.

Implementing a Deployment Manager

Implement a deployment manager by following these basic steps:

1. Pass an instance of the IClickOnceAddInInstaller object into the ClickOnceAddInDeploymentManager constructor.

2. Call the InstallAddIn method, and then pass the resulting AddInInformation object to one of the FindAddIn or FindAddIns methods in the AddInStoreExtensions class. This returns an AddInToken object that you can use to activate the add-in.

3. Call one of the Activate extension methods provided by the AddInToken class. If you are using an IEntryPoint, call the Activate, which automatically calls the Activate extension method to retrieve the name of the add-in and create a new application domain for the add-in. The Activate method then calls the IEntryPoint initialization methods.

You can use your own view type in the Activate extension method, but you must call the initialization methods for the view type separately.

The ShapeAppClickOnceCSharp sample demonstrates how to discover and load a ClickOnce add-in with a host deployment manager. For a complete example, see Walkthrough: Integrating ClickOnce for a Managed Object Model.

See Also

Tasks

How to: Configure the ClickOnce Trust Prompt

Concepts

Securing and Deploying Add-Ins

Securing Add-ins by Using ClickOnce

How to: Sign Application and Deployment Manifests with Mage.exe

Walkthrough: Integrating ClickOnce for a Managed Object Model

Other Resources

Visual Studio Tools for Applications 2.0