A Day in the Life of ClickOnce Deployment

As a test of the ClickOnce deployment model for Windows Forms applications, I built the simple game shown in Figure 19.1^[3]

^[3] Any similarity to any other very popular game that you may already be familiar with is strictly intentional.

Figure 19.1. The Game of Wahoo! (See Plate 20)

Wahoo is a standard Windows Forms application that allows users to start, pause, and resume games, with game play controlled from the keyboard. Additionally, Wahoo uses a web service to track the top 10 scores. When Wahoo can't use the web service, the top 10 scores for the current player are saved to the local file system.

Wahoo functionality is split across two assemblies: One assembly (WahooControlLibrary.dll) encapsulates game play within a control and is hosted in the other assembly (Wahoo.exe), which provides the game UI.

Because Wahoo is fun for everyone, making it available over the Internet is ideal. The easiest way is to use ClickOnce, a technology that manages the delivery of a Windows Forms application from a development (or build) machine to a user's client machine over the Internet. As shown in Figure 19.2, delivery can be broadly categorized into two stages: publishing and launching.

Figure 19.2. Application Delivery with ClickOnce Involving Publishing and Launching

Publishing is a developer-driven process that creates an application installation and makes it available to users from a suitably accessible publish location, the place to which developers copy the application files. Launching is a user-driven process that relies on ClickOnce to download an application from the publish location before installing and executing it.

Publishing an Application

To publish an application from VS05 for ClickOnce deployment, you first identify all the files needed to ensure that the application will execute on a client machine, before bundling the files into a logical installation package that is promoted to a publish location. At minimum, developers need to elect a publish location.

Designating the Publish Location

The easiest way to designate a publish location is to exploit the integration between ClickOnce and VS05 and use the Publish Wizard. You open it by right-clicking your project in Solution Explorer and selecting Publish. On the first page of the Publish Wizard, shown in Figure 19.3, you specify a publish location.

Figure 19.3. ClickOnce Publish Wizard: Choosing a Publish Location

As you can see, VS05 supports publishing an application to four types of locations: local disk paths, file shares, FTP sites, and web sites. For Wahoo, which is hosted by an Internet service provider (ISP), we can publish only to an FTP server:

ftp://www.sellsbrothers.com/Wahoo2

However, we want Wahoo users to be able to launch the application from a web site, so we need to pick a web location to launch from.

Designating the Launch Location

Users get an application from a launch location, which, in most cases, is the same as the publish location. However, ClickOnce doesn't support launching from FTP servers. If you specify an FTP site as the publish location, the Publish Wizard asks for an alternative launch location, as shown in Figure 19.4.^[4]

^[4] You can also manually configure publish and install locations via Project Property Pages | Publish.

Figure 19.4. ClickOnce Publish Wizard: Choosing a Launch Location

You can see that the launch location options are web sites, Universal Naming Convention (UNC) paths or file shares, and CDs or DVDs. Wahoo will be launched from the Sellsbrothers web site:

http:www.sellsbrothers.com/Wahoo2

With a publish location and a launch location, click Finish to publish the application.

Preparing an Installation Package for Publishing

Before an application is published, VS05 creates an installation package that comprises all the files needed to execute an application. For web site publish locations, the package is structured as shown in Figure 19.5.

Figure 19.5. Wahoo Installation Package Published to a Web Site

As you can see, VS05 has copied the Wahoo game assembly (Wahoo.exe), the dependent Wahoo game control assembly (WahooControlLibrary.dll), and the application settings file (Wahoo.exe.config) to a folder under the Wahoo web site. This folder is automatically created by VS05. Its name is a concatenation of the application's assembly name and publish version and is formatted this way: ^[5]

^[5] ClickOnce publish version numbers and versioning in general are discussed later in this chapter.

AssemblyName_MajorVersion_MinorVersion_BuildNumber_RevisionNumber

Notice that the names of the assembly files and the application settings file have been appended with ".deploy." VS05 does this by default for files published to web servers as a security measure: It is common for web server configurations to preclude them from hosting application files (.exes and .dlls). ^[6]

^[6] Use of the .deploy extension is determined by the "Use .deploy file extension" check box of the Publish Options dialog, which you open from a project's property pages by selecting Publish | Options.

We know that the assembly and settings files comprise the files required to run this application, but our users don't know that and certainly should not be made to download them one at a time. Instead, ClickOnce takes on the burden in typical .NET fashion by using an application manifest to specify which files are required for an application to execute on a client machine. The manifest, as you can see in Figure 19.5, is created by VS05 during publishing using the following naming convention:

AssemblyName.exe.manifest

Because multiple versions of an application can be published, there could be one or more folders, delineated by a unique version number and application manifest. In the face of such a choice, there needs to be a way to advertise which is the latest downloadable version. And there is: the deployment manifest, as shown in Figure 19.6.

Figure 19.6. ClickOnce Deployment Manifest

The deployment manifest references the application manifest to obtain the current version of the application to download. VS05 creates two ways to launch an application by generating two deployment manifests in the publish location's root: one that's version-specific (AssemblyName_PublishVersion.application), and one for the version-to-install (AssemblyName.application). Users should navigate to the version-to-install deployment manifest, which, for Wahoo, is found in the following location:

http://www.sellsbrothers.com/wahoo2/wahoo.application

As each version of an application is published, VS05 generates the version-specific folder and both the application and the deployment manifests, copying them to the appropriate locations. Additionally, VS05 updates the version-to-install deployment manifest, making it a copy of the latest published version-specific deployment manifest.

Because VS05 incorporates a layer of indirection between a single version-to-install deployment manifest and one or more version-specific manifests, application publishers can easily roll back a potentially bad new application version by manually replacing the version-to-install deployment manifest with one that refers to a previous, working version of the application.

Figure 19.7 illustrates the relationship between deployment and application manifests after several versions of an application have been published.

Figure 19.7. ClickOnce Deployment Manifest and Application Manifest Relationships

VS05 generates two additional files and adds them to the root: setup.exe and publish.htm. The setup.exe file is a standard installation application that downloads and executes the necessary prerequisites that a ClickOnce-deployed application needs in order to execute on the client machine, including.NET Framework 2.0. The publish.htm file, shown in Figure 19.8, is an HTML page that users can browse to launch an application. ^[7]

^[7] publish.htm is intended as an exemplar for application publishers to use as a model for their own installation web pages. If you prefer, you can prevent VS05 from generating publish.htm by unchecking "Automatically generated deployment web page after every publish" in the Publish Options dialog (project properties | Publish | Options).

Figure 19.8. The publish.htm Page

The Install button is a link to the version-to-install deployment manifest, and clicking it initiates application launch.

Launching an Application

Whether a user launches an application indirectly from publish.htm or by navigating directly to a deployment manifest, the ClickOnce launch process is initiated and begins a process comprising several steps: downloading the manifests, verifying their signatures and file hashes, and using them to determine whether the application is already cached on the client machine. This process is reported visually to the user via the dialog shown in Figure 19.9. ^[8]

^[8] An application can be launched only from a client machine on which .NET Framework 2.0 is installed. Ensuring that this is the case is discussed later in this chapter.

Figure 19.9. Verifying Application Requirements

If the result of checking application requirements is that ClickOnce can download the application, it performs a further analysis of the manifests, checking the application's publisher, security requirements, install files, and publish location. If some combination of these raises ClickOnce's hackles, the Security Warning dialog in Figure 19.10 is shown.

Figure 19.10. Security Warning

Users can open a more verbose description of the security concerns from the Security Warning dialog by clicking the More Information link label (Figure 19.10), which opens the dialog shown in Figure 19.11.

Figure 19.11. Security Warning: More Information

In this example, ClickOnce has determined that the application's publisher is unknown to the client, and the application requires more access to the client than the client allows for applications launched from the Internet. Both requirements are considered critical, and they are marked as such with the appropriate icons. Less critical is the footprint the application will leave on the client machine and the location from which it's being launched.

If all factors are soothing, the Security Warning dialog is not shown at all. However, typically some factors are troubling, so users need to consider these warnings before deciding whether to continue downloading the application. If they are comfortable with the security concerns, they can click Install to download the actual application. ^[9]Obligingly, ClickOnce begins downloading the required application files, keeping the user updated of its progress by displaying the progress dialog shown in Figure 19.12.

^[9] No application code is downloaded until the user chooses to, a practice that provides an added degree of security.

Figure 19.12. Download and Installation Progress

At the end of the download, ClickOnce begins installing the application.

Application Installation

By default, a ClickOnce-deployed application's files are placed in a folder on the local disk in a nonroaming, per-user location (%UserProfile%\Local Setting\Apps on Windows XP). Additionally, the default behavior for ClickOnce-deployed applications is to provide a modest level of integration with the shell, beginning with the addition of an entry in the Add or Remove Programs control panel, as shown in Figure 19.13.

Figure 19.13. Integration with Add or Remove Programs Control Panel

Additionally, a Start menu item is created for your application, as shown in Figure 19.14, which the user can select to activate the application even if no longer connected to the network.

Figure 19.14. ClickOnce-Deployed Application Start Menu Shortcut

If the publish location can't be reached, ClickOnce instead executes the currently installed application. ^[10]

^[10] The Start menu shortcut plays a pivotal role in application updates and versioning, as covered later in this chapter.

After installation or after users click the Start menu shortcut item, the ClickOnce launch process comes to an end and the application itself finally executes on the client, as shown in Figure 19.15. This is cause enough to shout Wahoo!

Figure 19.15. Wahoo in ClickOnce-Deployed Action

Because Wahoo is deployed from the Internet, information pertaining to security issues is displayed for users every time the application is run.

As the sun sets on a day in the life of a ClickOnce-deployed application, you'll fondly remember that even the simplest possible deployment configurationchoosing a publish locationcauses the ClickOnce juggernaut to roll into action. It creates and publishes an installation package to a publish location and, when the application is launched, manages the secure download, installation, and execution of the application to a client machine.

All this relies on VS05 to make a lot of decisions about the deployment process on your behalf, including creating a custom setup.exe to install application prerequisites, assembling the application files, deciding whether to integrate with the shell, and allowing users to stay current with new application versions if the publish location can be reached. If these defaults are unsuitable, don't worry. You can easily configure virtually any aspect of a ClickOnce deployment from VS05, including those you've seen and a whole lot more.