http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnreal/html/realworld03232004.asp

Deploying Windows Forms Applications with ClickOnce

<!--NONSCROLLING BANNER END-->

Mauro Sant'Anna
Microsoft Regional Director

December 2004

Summary: Examines the ClickOnce technology, compares it to other deployment technologies, and shows how you can use it in your applications. (11 printed pages)

Introduction

ClickOnce is a new Windows Forms deployment technology that will ship with Visual Studio 2005. It enables easy application installation and upgrading of Web applications with smart clients. The deployment of Windows Forms applications through HTTP has been available since the first version of the .NET Framework and has been evolving ever since. This article discusses the advantages of Windows Forms applications and the evolution of this technology leading up to ClickOnce. I will also show a simple example using the public Beta 1 version of Visual Studio 2005.

Why Windows Forms?

Since the World Wide Web appeared, most users and developers alike are more interested in Web applications than they are in "regular" Windows applications. Besides the "coolness factor," a Web application has some interesting and special characteristics:

• A Web application can be accessed from anywhere in the world where an Internet connection is available; the client doesn't even need to be running Windows. A "pure Web" application is a very good technology when your application needs ubiquitous access.
• A Web application is easy to deploy and update: just copy the application files into a directory on a Web Server and all your clients can start using the new application instantly. No DLL hell, no registry entries to tangle with, no COM classes to register; it just works!

The focus of this article is on the second bullet above: deployment. The HTTP protocol used by Web applications has several advantages over traditional Windows application deployment.

On the other hand, as much as I love the Web, it's hard to say that the user experience on the Web is stellar. When compared with Windows applications, the Web has several disadvantages:

• Its user interface is quite poor. Things that we take for granted in a Windows application, such as drag and drop and right-clicking the mouse, are very hard or even impossible to do in a Web application.
• Even when we do manage to do rich interface tricks, it usually requires an insane amount of client script, a kind of code that is particularly hard to write and debug.
• A Web application uses a lot of server resources, bandwidth, and user patience because most things have to be done at the server with a round trip and some waiting involved.
• Printing is limited to "print screen technology," with little control over things like page breaks due to different fonts, margins, and paper size.
• Some of the problems above can be mitigated through the use of plug-ins or ActiveX controls, but those in turn tend to have the same deployment problems that the old non-Web applications used to have.

What if we could marry the easy distribution of Web applications with the rich client experience of Windows applications? Well, we can. The .NET Framework since its first version allows the distribution of Windows Forms applications through HTTP and without the usual problems.

This kind of application is especially interesting in intranet/extranet scenarios, where ubiquitous access is not required and we can suppose the end user's computer will have both Internet Explorer and the .NET Framework installed.

.NET Framework 1.x: HREFing .EXEs

Versions 1.0 and 1.1 of the .NET Framework came "out of the box" with the capability to deploy Windows Forms applications through HTTP. You basically use an "HREF" tag to point to a managed .EXE. Internet Explorer and the .NET Framework runtime can download and run not only the executable but also the DLLs it might require, on demand. This kind of deployment has been nicknamed "hrefing EXEs."

This is an example of such a tag:

<a href="MainProject.exe">Call MainProject</a>

This is quite easy to do and has been discussed in these recommended articles:

• Security and Versioning Models in the Windows Forms Engine Help You Create and Deploy Smart Clients by Chris Sells; also, see his smart client Wahoo! sample
• Death of the Browser? by Billy Hollis
• My article, Deploy Windows Forms on the Web
• Using Windows Forms Controls in Internet Explorer

Because the .NET assembly (.EXE or .DLL) is the basic deployment unit, you want to break your application into a main .EXE and several DLLs. This way, if you make simple changes in a single DLL, just this DLL need to be downloaded.

As easy as it sounds, there are still some tricks to get things working correctly:

• The.NET Framework must have been previously installed on the client (although you can download a plug-in from http://msdn.microsoft.com/vstudio/downloads/tools/bootstrapper/ that can make it easier to install the Framework and your application).
• Your application will run on the client as partially trusted code. On the one hand, this is good because your application runs in a sandbox and has limitations on what it can do to the client computer. On the other hand, if you need functionality such as opening local files or calling a COM object you have to somehow set up a security policy in the client, not a trivial thing to do.
• By default, it's quite likely that your executable will try to load several DLLs with localization resources; due to some issues in the current implementation, performance will suffer, especially in a slow Internet link.
• The updates are made on a file-by-file basis; for instance there's no way to guarantee that all your 10 updated files are indeed downloaded; your client may be stuck with a "half updated" application.
• You application is available offline only if the user manually set up "Work Offline" in Internet Explorer; the application itself has no control over it.
• By default, the .config file associated with the program is not available (check here on how to do it).
• Your application won't have a shortcut in the desktop or the Start menu.

Updater Application Block

In order to address some of the issues pointed above, Microsoft created the Updater Application Block (UAB). The updater block is a library that you add to your application to manage the download of the application pieces through HTTP.

It has some advantages over the original Framework implementation:

• It runs as a local application and is available all the time with no performance penalties.
• Updates are transacted; that is, all the files of a new version must be successfully downloaded before the new version becomes available.
• All the application files are listed in a manifest.
• It runs as a full trust application; you needn't fiddle with client security policy.
• Your application can have shortcuts on the Start menu.

On the other hand, there are also some disadvantages:

• You must change your application substantially in order to use it.
• Since it uses BITS to download the application pieces, it does not run under Windows 98/ME; Windows 2000 or later is required.
• It runs as a fully trusted local application, so it pretty much ignores code access security.
• It's not supported by Microsoft.

To get more information on the UAB, see Jamie Cool's .NET Application Updater Component. You can also check out the home of the UAB at Gotdotnet. The UAB is not "officially" supported, though there's a forum at www.gotdotnet.com. In any case, the UAB comes with full source code, and you can change it to fix some of its restrictions such as the requirement of BITS and Windows 2000.

ClickOnce

The UAB is clearly an interim measure while Microsoft develops a definitive solution. This solution is ClickOnce. Basically, ClickOnce has all the advantages of the UAB with few of its problems, plus some added functionality. In my opinion one of the main advantage of ClickOnce is that it restores code access security.

When compared to HREF EXEs, a ClickOnce application has the following advantages:

• Updates are transacted (that is, are either done fully or not at all).
• The application not only can work offline but it has a degree of control over it; there are APIs so that the application can find out if it's online or offline; it can also control its own update process;
• It has good integration with Visual Studio .NET, including the ability to generate the appropriate extra files and tools that help to figure out which security privileges your application need in order to run.
• It comes with a Win32 "bootstraper" executable that can download necessary components, even the .NET Framework itself.
• Application files can be downloaded on demand or in batches;
• It can have Start menu shortcuts;

ClickOnce is a feature of Visual Studio 2005, formerly code-named "Whidbey," and the .NET Framework 2.0. Let's explore an example using the "Community Preview Beta 1" (Framework version 2.0.40607).

A ClickOnce Application

Let's create a simple ClickOnce application by following these steps.

1. Start Visual Studio 2005.
2. Select File, then click New Project.
3. Choose a language (C# or Visual Basic .NET) and select Windows Application.
4. Name the project MyClickOnceApp and click OK.
5. Add a button to the form and change its Text property to About.
6. Double-click the button. In the code Window enter the following code.

   Visual Basic .NET:

   MsgBox("My First ClickOnce Application")

   C#:

   MessageBox.Show("My First ClickOnce Application");

Press F5 to run and test the application.

All Windows applications under Visual Studio 2005 have a Publish page under Project | MyClickOnceApp Properties to control deployment details:

Figure 1. Configuring publish settings

Publishing Location indicates where the application will be deployed from. It can be a Web server (HTTP) location, as shown above, but can also be a regular network path.

Install Mode and Settings controls several deployment details, such as:

• Whether the application will be available online only or offline as well.
• Application Files: Where individual files will be installed.
• Prerequisites: Whether the setup program must install other components, such as Windows Installer 2.0, .NET Framework 2.0, J# Redistributable Package, SQL Server 2005 Express, Crystal Reports, and Microsoft Data Access Components 2.8.

  

  Figure 2. Configuring prerequisites

• Updates: Controls when the application should check for updates and how those updates are brought to the client.

  

  Figure 3. Configuring updates

• Options: Adjusts details such as application language, Start menu shortcut resource name, HTML page used for Web deployment, and the deployment policy ticket.

  

  Figure 4. Configuring publish options

Publish Version adjusts the application version number; the version number can be automatically increased at each deployment.

Publish Wizard allows you to set up various publishing options. This wizard is also called from the menu Build | Publish. All ClickOnce applications must be cryptographically signed; the wizard asks for an existing key (recommended) or it can generate a new one.

Figure 5. Signing your application

After you run the wizard once, you can click Publish Now to publish updates. In our example a Web page will be shown.

Figure 6. Published application

This Web page contains a script that checks which extra Prerequisite package must be installed before installing our application. If a prerequisite is not present, it will be installed the first time the application is run.

After the user clicks the Install link, several dialog boxes may require the user's intervention, at least the first time it runs:

• Windows XP SP2 warnings
• Agreement to software licenses
• Lack of verification of the publisher's signature

Deployment Details

Visual Studio .NET 2005 will create a new Web for our application with several files and folders.

Figure 7. Deployment folders

The dotnetfx folder contains the .NET Framework redistributable, currently a 25 MB executable.

By default, Visual Studio will increase the version number each time you deploy the application; each version will get a new folder with the corresponding increasing version number.

The .application file is the target for the link shown in the HTML page publish.htm. It is an XML file that contains information such as the folder corresponding to the current version of the application and digital signatures.

Publish.htm is a Web page containing not just the link to the .application file but also some client script that does some version checking and shows messages accordingly. For instance, if your computer does not have the .NET Framework, the message shown under Install MyClickOnceApp will be different.

Setup.exe is a Win32 executable capable of installing not only your application, but as well all the necessary components such as the .NET Framework itself and MDAC 2.8 in the correct order.

Each application folder contains the application's files and also a manifest file. The manifest is an XML file with basically the following information:

• Precise identity of all the application's files. This identity comprises the file name, version number, culture, and processor architecture ("msil" in our case).
• All the permissions the application requires.
• Digital signatures.

Running the Application

After the application is downloaded, you can run it without the need to download it again. In our example, the application can be started by clicking the link to the Web page or the shortcut in the Start menu. In both cases, the existence of a new version is checked according to the settings on the Application Updates project options. A new version is downloaded if needed.

To check this update capability, do the following:

1. Make a visible change to the application, such as changing the location of the button on the form.
2. Build and deploy it again.
3. Run the application and check the download process.

As a last note, it's important to notice that this information is based on the Beta 1 version of Visual Studio .NET; newer versions may have different features.

Comparison Chart

HREF .EXE UAB ClickOnce

No changes required to the application	X		X
Application isolation	X		X
Fully supported	X		X
Low system impact	X		X
Code access security preserved	X		X
On demand file download	X		X
Manifests to declaratively list the necessary files		X	X
Cryptographically signed manifests			X
Batch file download		X	X
Work offline	(*)	X	X
Transacted installs		X	X
Optimum performance		X	X
Windows 2000 or later required		X	(**)
Windows shell integration		X	X
Good control over the update process		X	X
API for working offline and control the download process			X
Automatic installation of optional packages			X

(*) Requires user intervention

(**) Too early to say for a beta product

Conclusion

ClickOnce is a very powerful technology for application deployment. It's a natural evolution of the deployment models available previously, bringing together robustness, security, performance, and flexibility to the rich client experience of Windows Forms applications.