Chapter 39. Deploying Applications Using ClickOnce

IN THIS CHAPTER

• Introduction to ClickOnce
• Publishing ClickOnce Applications
• Updating ClickOnce Applications
• Programming with the System.Deployment.Application Namespace

In the past, deploying Windows applications has often been a painful and arduous task. Previous versions of the .NET Framework made it easier to deploy Windows Forms applications because the .NET Framework’s inherent architecture removed DLL versioning problems and allowed side-by-side execution. However, it was still more difficult to bundle and deploy Windows Forms applications than it was to simply give a customer the URL to an ASP.NET web application.

The goal of this chapter is to show you that the old adage “Windows is harder to deploy” no longer exists. Using ClickOnce technology, you can have the best of both worlds: The rich, highly interactive, high-performance environment of Windows Forms with the quick and painless deployment that used to be the sole domain of ASP.NET applications.

This chapter will progressively build a fairly large sample to illustrate the various principles of ClickOnce technology. It is recommended that you follow along with this sample as the chapter progresses, as true mastery of ClickOnce only comes from the actual development and maintenance of a ClickOnce application.

Introduction to ClickOnce

Before learning about ClickOnce and how it works, it is beneficial to learn the problems that it solves. In traditional software installation packages, there are several issues that can be difficult for developers to get around that make the entire development process take more time (and therefore cost more money). When a user receives a Windows Installer package either from a CD or from a web download, that user must run that installation package to install the software. This often requires administrative privileges on the computer. After the software is installed, new versions, releases, updates, and patches often require that the previous version be completely removed before the new version can be installed. In addition, the new version is often a completely new package that contains the entire application rather than just the portions that have changed. Applications like many antivirus packages have built in their own custom update technology to allow the application to update itself once installed, but it still must be installed using a Windows Installer package that might require administrative privileges.

ClickOnce is a technology introduced with version 2.0 of the .NET Framework that provides a means by which developers can quickly and easily publish their applications. In addition to simplified deployment, ClickOnce allows applications to automatically receive updates from a central location that will only be downloaded as they are needed. Finally, ClickOnce also ensures that when a new version is placed in the publication location (which can be a network share or a location on the web), only the assemblies that are required are downloaded.

As you will see throughout the remainder of this chapter, security is taken care of by storing ClickOnce applications in an isolated per-user, per-application “sandbox” that prevents the application from interfering with other installed applications. ClickOnce applications don’t inherently require administrative privileges, they don’t require expensive and time-consuming uninstalls to make way for new releases, and they only download what they need. All of this functionality has been embedded directly into the .NET Framework and will dramatically increase your power to deploy and update your applications.

Although ClickOnce is an incredibly powerful new technology, it is also designed for applications that are running in a somewhat isolated environment. ClickOnce installations cannot make global changes for shared libraries. There are still a few scenarios in which you would want to use a Visual Studio Setup Project (Windows Installer) to deploy your application.

Table 39.1 shows a comparison of features between Windows Installer deployment and ClickOnce deployment to help you get an idea of when to use each technology. A more detailed version of this table is also available on MSDN.

Table 39.1 Feature Comparison: ClickOnce Versus Windows Installer

What it all boils down to is that using ClickOnce to deploy your applications is extremely fast and flexible, provided your application doesn’t need to make changes to global resources and settings. ClickOnce is ideal for deploying Smart Clients that typically have small footprints and provide a rich, interactive user interface that operates against a web service or relational database back end.

Publishing ClickOnce Applications

Writing complex code and dealing with enormous configuration files are not the hardest parts of using ClickOnce deployment. One of the most difficult tasks is in making the decisions that affect how your application is deployed and updated. This section takes you through the process of deciding how you want to publish your application including walking you through publishing a ClickOnce application.

You can publish your ClickOnce application in several ways. Each of these options is controlled through various options in the Publish Wizard that is used when you publish your application.

Deployment over the Web or Network Share

When you know that your customers will have network access to a single deployment location and the logistics burden of distributing a CD is too costly, deploying your application on the web or a network share is an excellent solution. Using this method, the user will navigate to a URL or to a network share and either click a link pointing to a deployment manifest (an XML file containing deployment data related to ClickOnce) or will double-click the deployment manifest file on the share. If the application requires additional security permissions, the user will be prompted to grant those permissions. A huge benefit to this model is that only the required permissions will be granted, unlike Windows Installer, which installs everything with full trust. After the application has been downloaded to the local user’s ClickOnce cache, a shortcut to that application will be created on the user’s Start menu and will appear in the Add/Remove Programs dialog in the Control Panel.

To enable web- or share-based deployment, simply type in a web URL or a file-share path when prompted for the publication location by the Publish Wizard.

Deployment on CD

If you need to get your application to users who cannot establish a network connection to the central deployment location or have low-bandwidth connections, you may decide to distribute the application on a CD. At other times you might want to distribute the application on a CD, such as when you don’t want the application’s original installation source to be available on the Internet.

Using the Publish Wizard, you can deploy the application to a CD or to a location that can then be used as an image with which to burn CDs. The end user then installs the application from the CD just like any other Windows application. A shortcut will be added to the user’s Start menu and an entry will appear in the Add/Remove Programs dialog in the Control Panel. To use the CD/DVD deployment model within the Publish Wizard, you simply select a location on a disk that will be used for CD imaging when prompted for the publication location by the Publish Wizard.

Application Launched Directly from Web or Share

This model is what many people refer to as the “zero footprint” deployment model. When a user clicks the application link on the web or a network share, the application is installed into the user’s ClickOnce cache just like the first (web) deployment model. However, when the application is done running, the application will be removed from the ClickOnce cache. This deployment model does not add an entry to the Add/Remove Programs dialog in the Control Panel, nor does it create a shortcut on the user’s Start menu. To use this deployment model, select the “No, this application is only available online” option from the Publish Wizard. This deployment model is ideal for applications that are run from the web but are run infrequently, such as tax software that might only be run once per year. Applications with frequent updates that are activated more often by the user should use the web deployment model instead of the “zero footprint” web launch model.

Deploying a ClickOnce Application

Now that you have seen the various options available to you for deployment methods using ClickOnce, you can walk through the process of deploying your own ClickOnce application.

The first thing you need before you can deploy your application is, of course, an application. This sample uses an application called ClickOnce1. To add to the realism, a Windows Forms Control Library called FormLibrary was created and an AboutBox form was added to that library. Then a reference from ClickOnce1 to FormLibrary was added.

Add a menu strip to the main form in the ClickOnce1 application and make one of the menu options launch the About box as follows:

FormLibrary.AboutBox1 aBox = new FormLibrary.AboutBox1();
aBox.ShowDialog();

This is to illustrate how dependencies work within a ClickOnce application and to prove that referenced assemblies will indeed be downloaded during the installation process.

Make sure that both of your assemblies (ClickOnce1 and FormLibrary) have the same version number, 1.0.0.0. Also make sure that you supply some additional information in the AssemblyInfo.cs file like the publisher name, assembly title, and so on.

Because you will eventually want to test how the update feature works, add a few random controls to the main form so that you will have a visual comparison between future versions.

Before publication, this application looked like the one in Figure 39.1.

Figure 39.1 A sample ClickOnce application.

Now you’re ready to publish the application. There are a couple of entry points that will launch the Publish Wizard, but this author recommends going into the Publish tab of the Project Properties editor. This gives you a quick overview of publication settings defaults before launching the wizard.

Before launching the wizard, click the Options button to see the various publication options that are available to you. Make sure you set the publisher name and the application name and the optional support URL. Also note the handy option, “For CD Installations, Automatically Start Setup When CD Is Inserted.”

When you’re done with the Options dialog, click the Prerequisites button. This dialog allows you to specify all of the prerequisites your application needs to run. The .NET Framework 2.0 Runtime is already selected. One very useful feature is that you can select “SQL Server 2005 Express Edition” and your application will never deploy without first installing SQL Express on the end user’s machine. This is unbelievably useful for data-driven ClickOnce applications.

One last thing you should do before you publish your application is to decide whether you want to sign the ClickOnce manifests. By using Authenticode technology to digitally sign these XML files, you can attach verifiable proof of the authenticity of the publisher. For testing purposes you can leave this step off. However, in a commercial publication you will want to sign the application manifests as well as the application itself using strong naming. For this sample, the author clicked the Create Test Certificate button just to have a verifiable source with which to test.

Click the Publish Wizard button to launch the ClickOnce Publish Wizard. If you’re satisfied with all of the options you have specified, you can simply click the Publish Now button to deploy immediately. The wizard will prompt you for the location (URL/file path) of the publication and the installation footprint options (online only or both online and offline).

Assuming everything worked well and the publishing was a success, you should be presented with a web page that looks like the one shown in Figure 39.2.

Figure 39.2 Application deployment page created by ClickOnce publication.

If you hold the mouse pointer over the Install button, you’ll see that the link to the installation is actually a link to the application manifest file, ClickOnce1.application. The web deployment location looks like the one shown in Figure 39.3. As you can see, there is a central application manifest file that provides information about the application (as well as an Authenticode signature if the manifest was signed) and an application manifest for each individual version of the application.

Figure 39.3 Initial publication of a ClickOnce application to the web.

To finish out the deployment of this application, click the Install button. You will see a progress dialog indicating that the application requirements are being validated. Then, if you used a test certificate or no certificate at all, you will see a warning indicating that the publisher cannot be verified. This is just a test, so click Install because you are the publisher. The installation process should be very quick for this application. When it’s done, the application runs and you’ll see the main form with all of the controls that you added to it.

If your sample has the same data as the one this sample has been developing, you will see that the Start menu now has a “SAMS Publishing” group that contains the following two shortcuts: “ClickOnce Application” and “ClickOnce Application Online Support.” Note that the icon for the application in the Start menu is the same as the icon you defined in the application settings editor. The online support shortcut appears if you specify a Support URL in the Publish settings tab.

The last thing to do before moving on to the section on updating a ClickOnce application is to verify that the application shows up in the Add or Remove Programs dialog in the Control Panel.

When you launch the application a second time from the Start menu, the application requirements validation dialog will appear as the application checks the publication location for updates. As you’ll see later in the chapter, you can programmatically override this behavior for a smoother and richer experience during this stage.

To satisfy your curiosity, shut down the IIS website that hosts the publication location and run the application again. The application will run just fine even though the deployment location is offline. If the deployment location is offline, the application behaves as though there are no new updates.

Updating ClickOnce Applications

After your application has been published and customers have downloaded it and are using it, new releases will always be necessary. Bug fixes need to make it out to clients as well as new releases that contain new functionality.

With previous versions of the .NET Framework, the basic model was to issue a new Windows Installer image. Customers would then have to obtain the new installer image and run that, which would completely remove the previous version of the application and then create a fresh installation containing the new version. Any dynamic update support within a .NET Framework application in previous versions was developed entirely by hand by developers or using the Automatic Update Application Building Block from Microsoft.

When you publish an application, you have the option of automatically incrementing the publish version with every publication. This can be a handy feature, but it can occasionally cause problems. The publish version is a completely arbitrary number that is not directly related to any assembly version. This means that you can publish version 2.0 of your application and you may still be using several version 1.0 assemblies. This is deliberate because a lot of companies follow this model and do not increase version numbers of assemblies unless the assembly changes. The separation of publish version and assembly version provides maximum flexibility for the developer.

To see the options available for ClickOnce updates, go to the Publish tab of the Project Settings editor and click the Updates button. The dialog box shown in Figure 39.4 shows the options available for automatic updates. If your application does automatically check for updates, it can check either before the application starts or it can check after. Delaying the update check until after startup allows for a faster start time for the application, but new updates will not be applied until the application is shut down and started again.

Figure 39.4 ClickOnce automatic update configuration.

To see how updates work with ClickOnce, make some changes to the main form that are easy to catch, such as changing the background color, removing controls, adding new ones, and so on. Then, increase the assembly version on both the ClickOnce1 and FormLibrary assemblies to version 2.0.0.0.

Then, without running the publication wizard, change the publish version to 2.0.0.0 and click the Publish Now button. After the publication takes place and the publication is verified, the destination directory hosted by IIS should look like the one shown in Figure 39.5.

Before downloading the new version of the application, the end user receives a confirmation prompt asking if she wants to download the new version, as shown in Figure 39.6.

After you have downloaded the new update, your application should show up with the appropriate version number (2.0.0.0) and any GUI changes that you made to the application will appear. Any change that you made, code or otherwise, is associated with that specific publish version of the application.

Figure 39.5 Multiple versions exposed for ClickOnce.

Figure 39.6 Download ClickOnce update dialog.

Although we developers don’t like to admit it, patches sometimes have their own bugs. In fact, developers often encounter situations in which a patch causes problems worse than the ones for which the patch was intended. This isn’t always the developer’s fault—environmental factors such as the client system, configuration, and OS can often cause patches and updates to fail. If this happens, the user is far from helpless. If the user had installed using a Windows Installer package, he would have to uninstall the application and try to find a copy of the previous version. With ClickOnce, all the user has to do is click the Change/Remove button next to the ClickOnce application. The user will then be prompted if he wants to restore the application to its previous state or uninstall it. Restoring the application to its previous state can undo any damage caused by the last update, restoring the user to a known working condition until she can get help from support.

Programming with the System.Deployment.Application Namespace

In addition to all of the things that ClickOnce automates for you, there are also a lot of things that you can do manually. For instance, you can write code that will manually check for updates, code that initiates the download of an update, or even code that manually downloads an optional file like an image or an unreferenced assembly. You also have control over the updating GUI and can replace the standard update dialog procedure with your own code. All of this is made possible through the System.Deployment.Application namespace and the System.Deployment.Application.ApplicationDeployment class. This class provides the essential functionality that you need to exert maximum control over your application’s ClickOnce update environment.

The ApplicationDeployment class contains several events that you can handle within your application. Some of them are

• CheckForUpdateCompleted—This event is fired when an asynchronous check for update availability is complete. Don’t confuse this with the completion of an actual download.
• CheckForUpdateProgressChanged—To report progress information back to the user, this event is fired every time the progress of checking for an update changes. It uses the DeploymentProgressChangedEventArgs class to report progress. This class contains a property indicating the percentage completed, but also provides more detail in the form of the BytesCompleted and BytesTotal properties.
• UpdateCompleted—When an asynchronous download and installation of an update is finished, this event is fired to notify the user interface.
• UpdateProgressChanged—This event is fired whenever the progress changes on the download of an update.

To see how you can modify your application to replace the default update behavior with your own, it will take two steps. First, you will have to modify the code to support your new update mechanism and publish that revision out to the publication location. Then, you’ll need to make another change so that you can watch your application download the new update.

The first step is to add an Update Now menu item to the form’s main menu strip. Also add a progress bar to the status strip on the bottom of the form. If you didn’t already have a status strip on your form, now would be a good time to add one. Next, modify your Form1.cs code to look like the code in Listing 39.1.

Listing 39.1 Manually Performing Updates and Reporting Progress

Build and then publish this application as version 2.1.0.1, making sure to change the automatic update checking from “Before” to “After.” Run the application and make sure that the application updates to the right version. Then, make some minor change to your application and label that version 2.1.0.2. Publish this application and then run the application again. Instead of the default behavior and GUI for updating applications, you should be able to click the Update Now menu item. When checking for updates, you should see the new progress bar at the bottom in the status trip. When an optional update is available, a prompt like the one shown in Figure 39.7 appears. If you choose to download the update, the progress bar again reports progress, but this time it is reporting the download progress of the new update.

At this point you have created a new application, deployed that application with the click of a button, and created an automatic update framework that takes care of all of the details of downloading new versions, installing those versions, and even rolling them back when failures occur. In addition to that, you have just replaced the default behavior and UI of ClickOnce updating with your own interface and code.

Figure 39.7 Custom ClickOnce GUI.

Summary

Ease of deployment has almost always been a unique feature of web applications. In the past, when it came to deciding on what platform the next application would run, ASP.NET applications always won when the decision came down to ease of deployment.

This chapter illustrates that this is no longer the case. Using ClickOnce deployment, applications can be interactive and easy to deploy with a rich user interface and all the power of the .NET Framework underneath.

In this chapter you saw how to deploy a ClickOnce application and the various deployment options that are available to you as the developer of a ClickOnce application. After you have deployed that application, you need to be able to provide updates, patches, new releases, and so on. This chapter covered the mechanism for updating a ClickOnce application and the various methods by which ClickOnce applications can receive updates.

At this point you should be able to start working with ClickOnce applications and hopefully begin recommending Windows Forms 2.0 as a viable quick-deployment platform and putting an end to the vicious rumor that Windows Forms applications are cumbersome to deploy and maintain.