ClickOnce Installation

Article
10/14/2010

ClickOnce Installation

Introduction

ClickOnce, a Web-based deployment technology, requires creating manifests that specify install and update policies, moving files to appropriate locations, and setting up correct privileges. ClickOnce also requires a .NET Framework 2.0 or later. Although not required, many developers commonly use Visual Studio® 2005 to create ClickOnce applications.

Implementing Deployment and Update Strategies

Deployment and update strategies are set in the deployment manifest. The following table lists the manifest configurations for different deployment policies.

Deployment policy	Manifest configuration
Installing from Web or network share	In Visual Studio, select the project in Solution Explorer. On the Build menu, click Build project name. On the Publish Wizard, click "From a Web site" or "From a UNC path" or "file share" on the How will users install the application? Page. Mage.exe and MageUI.exe produce manifests with this strategy by default.
Installing from media	To enable this deployment strategy in Visual Studio, click "From a CD-ROM or DVD-ROM" on the How will users install the application? page of the Publish Wizard. This setting cannot be configured automatically by Mage.exe or MageUI.exe. To enable the deployment strategy without using Visual Studio, create a default deployment manifest using Mage.exe and manually edit the forwardingUrl tag.
Launching from Web or network share	To enable this deployment strategy in Visual Studio, click "Do not install the application" on the Install or Run From Web page of the Publish Wizard. This setting cannot be automatically configured by Mage.exe or MageUI.exe. To enable the deployment strategy without Visual Studio, create a default deployment manifest using Mage.exe and manually edit the shellVisible tag.

The following table describes how to set update polices.

Note

The Update policy is not applied to your application if it is configured to use the Launching from Web or network share deployment policy.

Update policy	Action
Checking for updates on a background thread.	To enable this update strategy using the Visual Studio Publish Wizard, select the project in Solution Explorer. On the Project menu, click project name Properties. Click the Publish tab. Click the Updates button to open the Application Updates dialog box. In the Choose when the application should check for updates section of the Application Updates dialog box, click After the application starts. This setting cannot be configured automatically by Mage.exe or MageUI.exe. To enable the deployment strategy without using Visual Studio, create a default deployment manifest using Mage.exe and manually change the Update element in the deployment manifest to Periodic. To specify the update interval using the Visual Studio Publish Wizard, in the Application Updates dialog box set the Specify how frequently the application should check for updates properties. To specify the update interval without using Visual Studio, edit the minElapsedTimeAllowed and unit attributes of the Update element in the deployment manifest.
Checking for updates at application start	To enable this update strategy using the Visual Studio Publish Wizard, in the Application Updates dialog box, select the Choose when the application should check for updates section, then click Before the application starts. This setting cannot be configured automatically by Mage.exe or MageUI.exe. To enable the deployment strategy without using Visual Studio, create a default deployment manifest using Mage.exe and manually change the Mode attribute of the Update element in the deployment manifest to BeforeApplicationStartup.
Enabling user-initiated updates	Provide a user interface, such as a Check for Updates Now menu item or an Update Settings dialog box, using standard .NET Framework 3.0 forms and the ClickOnce deployment APIs found in the System.Deployment namespace. To do this using the Visual Studio Publish Wizard, in the Application Updates dialog box, clear The application should check for updates check box. Automatic update checking cannot be turned off by Mage.exe or MageUI.exe. To turn off automatic update checking without using Visual Studio, create a default deployment manifest using Mage.exe and manually remove the Subscription tag from the deployment manifest.
Blocking automatic updating	To block automatic update checking using the Visual Studio Publish Wizard, in the Application Updates dialog box, clear The application should check for updates check box. This setting cannot automatically be configured by Mage.exe or MageUI.exe. To block automatic update checking without using Visual Studio, create a default deployment manifest using Mage.exe and manually remove the Subscription tag from the deployment manifest.

Customizing Deployment and Update Strategies

It is possible to customize an installation policy in the following ways:

Using On-Demand Installation

A particular feature in a developer's application may be used by only a small set of the users. Therefore, it may be desirable to offer the feature's assemblies as a download only when a user tries to access the functionality.

It is possible to mark certain assemblies as "optional". A ClickOnce application can be written to use the functionality of the Microsoft® .NET Framework version 3.0 System.Deployment namespace to dynamically download these assemblies when needed.

By default, all the assemblies included in a ClickOnce application are downloaded when the application is first run.

Specifying Deployment Prerequisites

ClickOnce applications typically require that the correct versions of the Common Language Runtime (CRL) and the .NET Framework, the managed programming model, be installed before an application can be installed. Typically, the Microsoft .NET Framework version 2.0 and Microsoft Data Access Components 2.7 must be installed first.

It is possible to install these components as a part of an application's installation, a practice known as bootstrapping. By default, Microsoft tools that can be used to create installations, such as Visual Studio, will provide bootstrapping for Microsoft® Windows® Installer and ClickOnce deployments. Bootstrapping can be disabled for a component, but do that only if the correct version of the component is already installed.

Note

By default .Net Framework version 2.0 is selected.

Using Trusted Application Deployment

Trusted Application Deployment makes it possible to grant additional permissions to a managed application in a safer, more secure manner without user prompting.

It is possible to configure a client with a list of trusted publishers that are identified using Authenticode® certificates. A ClickOnce application signed by one of these trusted publishers receives a higher level of trust.

Requiring Updates

It is possible to indicate that an update is required. Typically, users can decline to upgrade when prompted by a ClickOnce application that a new version is available. However, under certain circumstances—for example, when a change to an external resource (such as a Web service) prevents existing versions of an application from running—it is necessary to require an update.

A required update is indicated in the deployment manifest of an update site and can be specified under any of the update policies. If an application is set to Checks for updates on application start, an older version of an application will not be run without a required update.

Using Alternate Update Locations

A ClickOnce application can be installed from a CD or a file share and still require that the application check for periodic updates on the Web. Do this by specifying an alternate location for updates in the application's deployment manifest.

Using Elevated Permissions

An application's permissions are determined by the settings in the trustInfo element of the application manifest. Visual Studio 2005 automatically generates this information based on the settings on the project's Security Properties window. A ClickOnce application is only granted the specific permissions that it requests (for example, where file access requires full trust permissions). If the application requests file access permissions, it will only be granted file access permissions, not full trust permissions. When developing a ClickOnce application, request only the specific permissions necessary.

Deployment Issues

There are several important issues to consider when designing an application to be deployed using ClickOnce.

Manifest Signing

All the deployment manifests should be signed using Authenticode signing. Publisher information based on the Authenticode signature will be displayed to the user in the Permissions dialog box during installation. This indicates that the application originated from a trusted source.

ClickOnce displays Publisher Information only if the Certificate has a trusted root. If there is no trusted root, the ClickOnce Trust Manager dialog displays an "unknown publisher" message, and the name of the publisher is displayed from the Certificate instead of the manifest. This prevents the insertion of any other name as publisher.

The .NET Framework Software Development Kit (SDK) includes a file-signing tool (Signcode.exe) that enables publishers to sign the manifest. Manifests also can be signed using Mage.exe or Mageui.exe:

Manifest Generation and Editing, Mage—Sign WindowsFormsApp1.manifest -CertFile mycert.pfx.
The file mycert.pfx is a valid digital signature (a Personal Information Exchange file).

For more information about code signing, see "Introduction to Code Signing" and "Designing Applications for Windows Vista"Designing UAC Applications for Windows Vista in the MSDN Library.

ClickOnce Cache Management

All ClickOnce applications work out of a single location, or cache, in a family of hidden directories under the current user's Documents folder. This cache holds all the application's files: its assemblies, configuration files, application and user settings, and data directory. The cache also helps guarantee application isolation by keeping the assemblies and data files separate from one another for all applications and their distinct versions.

ClickOnce assumes the burden of managing the physical installation of an application, taking away the burden from users.

ClickOnce applications launched from the Web or a network share are restricted in the amount of space they can occupy by a quota that constrains the size of the ClickOnce cache. When the quota limit is reached, the oldest applications are removed.

The cache size applies to all of the user's online applications. There is no per-application cache limit. Installed applications are not limited by the cache size and do not count against the cache limit. In addition, installation of new applications is not blocked by quota.

For online-only applications, the ClickOnce cache retains every version of the application that the user has accessed from his or her computer. For installed applications, the cache retains only the current version and the previously installed version.

By default, client computers have 100 MB of storage for online ClickOnce applications. A system administrator can change this quota by altering the registry key:

HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Deployment\OnlineAppQuotaInKB.

For more information on the ClickOnce cache, see "Architecture of the ClickOnce Cache" in the Windows SDK.

Data Access for ClickOnce Deployed Applications

ClickOnce provides the following ways of reading and writing data, both locally and remotely.

ClickOnce Data Directory—any file included in a ClickOnce application and marked as a "data" file in the manifest is copied to the ClickOnce cache directory under the user's Documents folder upon application install. For more information about including data files for ClickOnce installation, see "How To: Include a Data File in a ClickOnce Application" in the Windows SDK.

Data files can be of any file type and are intended for data that the application explicitly stores and maintains.

All static, non-dependency files not marked as "data" in the application manifest reside in the directory where the application's executable files and assemblies reside.

When a ClickOnce application is uninstalled, its Data Directory is also removed. Never use the Data Directory to store user–managed data, such as documents. During updates, for example updating from Notepad 1.0 to 1.1, ClickOnce merges the Notepad 1.0 local data directory with Notepad 1.1 (server), based on timestamp. When ClickOnce needs to replace files in the data directory, it copies older content files into a .pre sub-directory. This allows the application to copy older content if needed.
Isolated Storage—should be used if an application needs to run in partial trust but needs to maintain application or version-specific data.

An Isolated Storage API (found in the System.IO.IsolatedStorage namespace) is provided for creating and accessing files via a simple API that hides actual file locations from different versions of the application, as well as from the developer and the user.

For more information about developing ClickOnce–compatible applications with isolated storage, including the isolated storage API, see "Introduction to Isolated Storage" and "Isolated Storage Reference" in the Windows SDK.
Other Local Files—ClickOnce applications frequently need to manipulate or save user data (such as reports, images, and music). These applications can use the System.Security.Permissions.FileIOPermission class to determine if the application has proper rights before attempting to access a folder.

For more information about working with data access for ClickOnce–installable applications, see "Accessing Local and Remote Data in ClickOnce Applications" in the Windows SDK.

Resources

The following table lists supporting resources for ClickOnce under .NET Framework 3.0 and Windows Vista®.

Tool

Description

Manifest Generation and Editing Tool (Mage.exe )

A command-line tool for creating and editing application and deployment manifests.

As a command-line tool, Mage.exe can be run from batch scripts and other Windows–based applications, including ASP.NET applications.

For more information, see the Manifest Generation and Editing Tool (Mage.exe) section of the Windows SDK documentation.

Manifest Generation and Editing Tool Graphical Client (MageUI.exe)

A Windows Forms–based user interface to the same manifest-creating and editing functionality available in the command-line tool, Mage.exe.

For more information, see the Manifest Generation and Editing Tool–Graphical Client (MageUI.exe) section of the Windows SDK documentation.

Wizard	Description
Publish Wizard (Visual Studio)	A Visual Studio wizard that automates the creation of ClickOnce manifests and the copying of files to appropriate installation and update locations.

Namespace	Description
System.Deployment	Supports updates of a current deployment, as well as on-demand downloads of files.

Required files	Description
Application Manifest	A specification as to how an application is to be installed. It includes the application's assemblies, dependencies, files, required permissions, and the update location.
Deployment Manifest	A specification as to how an application is deployed. It includes the location of the application manifest and files, and the version of the application that clients should run, and updates the phone home URL.

Share via

ClickOnce Installation