ClickOnce Deployment: An Overview
by Peter A. Bromberg, Ph.D.

Peter Bromberg

A "ClickOnce Application" is any Windows Forms or console application that is published using Visual Studio .NET 2005 ClickOnce technologies. Applications can be published from a Web page, a network file share, or media such as a CD-ROM. An application can be installed on an end users computer and run locally even when the computer is offline, or it can be run in an online-only mode without permanently installing anything on the end users computer.

In addition, ClickOnce applications can be made to be self-updating; checking for newer versions as they become available and automatically replacing any outdated files. The developer can specify the update behavior, and a network administrator can control update strategies (for example, by making an update mandatory). Updates can also be rolled back to a previous version by either the end user or an administrator. For many software developers, the question will be, "What is different between ClickOnce and a standard MSI Windows Installer deployment?" By exploring the differences, you will be better able to determine which technology is right for you.

ClickOnce Deployment vs. Conventional MSI Installer

To appreciate ClickOnce technology, developers must first understand that it is a complement to, not a replacement for existing MSI Intaller technology. In fact, Microsoft recently released version 3.0 of its Windows Installer API.

There is no single rule to determine whether you should use a ClickOnce deployment or conventional MSI Installer. The following list highlights some guidelines you can use to help make the best decision for your specific needs:

  •    Does your application require user input at installation?
  •    Does your application require configuration of Active Directory or COM+?
  •    After your application is installed, does it create files, write to the registry, or affect the target system in a      way that leaves resources behind when your application is removed?
  •    Does your application install COM components?
  •    Does your application require registering any components for COM Interop?
  •    Does your application install any services?
  •    Must your application install to a specific location or install assemblies to the Global Assembly Cache?
  •    Does your application have any components that are conditionally installed based on the operating system      or runtime environment?

If the answer is yes to any of these questions, then a properly designed and configured MSI Installer is probably still the best choice for your needs. If you don't need to address these issues, ClickOnce technology is a good candidate for your deployment solution. It is important for developers to have a full understanding of the capabilities and limitations of both ClickOnce and MSI installer technologies early in the development process. This helps to avoid costly upgrade-path refactoring down the road. As with any new technology, it's "RTFM"!

ClickOnce - Background

The ability to remotely load .NET Framework assemblies via HTTP has been built into the .NET Framework since the earliest BETA versions. Applications could be loaded either via a direct HTTP request to the executable (.EXE) assembly or via an OBJECT tag pointing to a DLL assembly as a UserControl from within Internet Explorer (IE). In addition, applications would automatically run in a protected security sandbox called Partial Trust. This arrangement offered some significant benefits to developers and administrators in that it provided the means to deploy some types of .NET Framework applications across the enterprise without the necessity to touch any of the client machines. Users could simply click a link in an email from the Administrator or request a particular Web page on the intranet, and, provided the page was listed as a Trusted Site in IE, install an application. Users could then run the application from the desktop or by simply returning to the Web page and having the application run inside the IE container.

This arrangement has both benefits and drawbacks. Developers complained that Partial Trust meant much of the functionality they wanted to have in their applications, such as being able to make database calls, would not work. Microsoft had determined that from a security standpoint, it would no longer allow remotely invoked applications to go down the slippery path that allowed ActiveX to be exploited -- at least not ClickOnce .NET applications. The main issue with ActiveX was that a script from any source could reuse anyone's ActiveX component on the machine. ClickOnce applications, even if they are fully trusted, are completely isolated from one another -- a key security improvement.

After the release of .NET 1.1, Microsoft made available several versions of the Updater Application Block, a deployment technology that takes advantage of remote downloading via BITS or HTTP. By using an application Manifest (a simple Xml file describing required assemblies and resources, their locations, and what versions to deploy), applications are provided the ability to update themselves by automatically checking to see if there are newer versions each time they are loaded.

This is how ClickOnce technology came about, and with Visual Studio .NET 2005, it is now built-in to the Integrated Development Environment.

The Object Model

From a developer's perspective, the primary ClickOnce-related namespace in .NET Framework 2.0 is System.Deployment.Application, which offers CheckForDetailedUpdate, CheckForUpdate, DownloadFileGroup, and Update methods, along with asynchronous versions of the same. Properties such as CurrentDeployment, CurrentVersion, IsFirstRun, IsNetworkDeployed, TimeOfLastUpdateCheck, UpdatedApplicationFullName, and UpdateLocation enable you to track the various properties of a deployment programmatically. Finally, events such as UpdateProgressChanged and CheckForUpdateCompleted round out a rich programming model for the .Net developer who wants to create customized ClickOnce deployments and to control these and their behavior programmatically at runtime.

A Deployment Scenario

As the following publishing example highlights, the typical ClickOnce deployment scenario involves no programming. For this example, I loaded a Quoteminder tray application I wrote in Visual Studio.NET 2003, and converted the application to Visual Studio.NET 2005. This application needs to write to the registry, make HTTP calls to the Web to get stock quotes, and uses some native Windows code calls to pop up a notification window from the task bar. The first step in ClickOnce publishing is to select the Publish option from the Build menu, which brings up the initial dialog box with publish options (see Figure 1).

Figure 1: The Publish Wizard options window.

As Figure 1 shows, you can publish the application to a disk path, file share, FTP server, or a Web site. Make a selection and click Next to then set the applications online/offline availability. You can choose to make an application available online only, or both online and offline. In this example, the application can only function when the PC is online, so I selected the available only online radio button choice. At this point, you can continue with the default options by clicking Finish, and the application will be completely published. After the application is published, any users HTTP request to the published URL will be presented with a security dialog box (if you use the default options during setup), which Figure 2 shows.

Figure 2: ClickOnce security dialog box.

The user simply clicks Run, and the application is immediately installed locally in the ClickOnce cache and begins running, with no further action required either by the user or the Administrator. Obviously, this simple process holds significant advantages in the enterprise both for ease of deployment and for updating applications. Once published, the process of updating the application is as simple as republishing an updated application to the same target deployment endpoint, and users applications will automatically be updated. The user can also click the More Information link at the bottom right of the security dialog box for more advisory information.

In the example security dialog box, the user receives a red X warning. This warning can be avoided by signing the application with a trusted root certificate and configuring the security as required. Alternatively, you can push a policy configuration on the network to approve the application. If you do so, there will be no prompt for an online-only application. The end user doesnt need to make any trust decision, IT has made it for them.

Requirements and Features

Using ClickOnce requires that the target client already have the .NET Framework 2.0 installed. Visual Studio has made packaging and deploying the .NET Framework simpler. Select the prerequisites your application may have and Visual Studio will generate a bootstrapper file that will automatically install the specified prerequisites when run. On the server side, ClickOnce needs only an HTTP 1.1 server or a file server.

The bootstrapper is a setup packager that can be used to install application prerequisites, and it downloads and runs the prerequisites when invoked. When the bootstrapper completes installing prerequisites, it invokes the ClickOnce deployment manifest, which installs the main application. This method can be used to install third-party and custom prerequisites. However, almost all such redistributions that the bootstrapper will be used to install require Administrator rights.

ClickOnce also supports HTTP 1.1 compression. If compression is enabled on your Web server, the files ClickOnce downloads will be compressed. AS of this writing, the ClickOnce application cache is 100MB, but that might change by release shipment. This cache size only applies to online-only applications, not installed applications. Microsoft says there will be a way to configure this size.

Programmatic and Security Issues

At any given time, ClickOnce will have stored two versions of an application (the previous version and the current version). You cannot configure how many versions ClickOnce keeps, and the install location of a ClickOnce application cannot be managed by the application. This is to help make ClickOnce applications safe, reversible, and easy to administer. The administrator can specify where the ClickOnce store should reside.

You can indicate which files are required and which are optional. Only required files are downloaded on initial deployments and updates. An application can use the System.Deployment.Application APIs to have the optional parts of the application downloaded when appropriate. You can also put optional sets of files into groups that can be downloaded at the same time, and you can use ClickOnce to deploy .NET Framework-based applications built with any language. (C++ application deployment via ClickOnce within the IDE has been cut as of Beta 2. The MAGE tool can be used to ClickOnce deploy VC applications, but the top-level executable must still be a .NET assembly.)

You can build in any customization mechanism that you would normally provide into your application. The step that changes with ClickOnce is the requirement to author manifests. Once a customized version of your application has been created, the original ClickOnce application and deployment manifests can be updated to include the new files, and re-signed with a valid key by using the MAGE tool.

There is no default security level for ClickOnce-deployed applications; they will run with whatever trust is defined in the application manifest. A default application has the ability to perform safe operations, such as displaying its UI and same-site network IO, but it cannot do unsafe things such as calling into unmanaged code or directly accessing the file system. This is similar to what applications deployed from IE in an HTML page can do.

Advanced Security and Deployment Issues

There are two options available to applications that need higher trust. The first is the trust prompt, which Figure 2 shows. An application can specify the permissions it needs, and if it needs more trust than is allowed in the zone, the user will be prompted at application installation. If the user accepts the prompt, the application will get the permissions it requested. Prior to Beta 2, an alternative was to use trust licenses. However, as of Beta 2 of Visual Studio.NET, there is somewhat equivalent functionality we get from the standard Windows platform support for X509 certificates. Developers can fine-tune security for their application on a per-zone basis using the Visual Studio.NET security page (see Figure 3), and can easily F5/debug within the Partial Trust defined on this page. Applaunch.exe is used to host applications running in the CLR. Applications running with full trust do not need to be hosted in a secure host and will not run under the AppLaunch.exe. Applaunch.exe is similar to the IEExec.exe hook presented in prior versions of the .NET Framework.

Figure 3: The Visual Studio.Net security page.

Combining ClickOnce and MSI Installer Technology

It is possible to use the bootstrapper to bridge the gap between ClickOnce and MSI. This can be done by factoring the heavy-duty parts of your application into an MSI, which can then be integrated into the setup.exe process alongside any FX and MDAC prerequisites.

Windows Installer technology provides advanced capabilities for interacting with the user during an installation. The ability of an installation to interrogate the target system to ensure that it meets the minimum requirements and has the correct prerequisites is important. Many applications need to have some interaction with the operating environment -- writing log files, storing data in the registry, and so on. A professional-level application must be able to clean up this application-specific data when it is removed from the system, and ClickOnce cannot provide these features.

To combine both MSI Installer and ClickOnce technologies, use an MSI installer to inspect and interrogate the target system first. It will interact with the user, store configuration information, install shared assemblies to the GAC, and other necessary functions. At uninstall time, it can clean up resources that should not be left behind. As ClickOnce applications can be installed via an Internet or intranet URL, you simply need to create a shortcut on the target system that points to the ClickOnce application manifest. You can enhance the Installer MSI to create a .URL file during installation. .URL files are just shortcuts that conform to the INI file specification:



This is all accomplished by adding a new line to the IniFile table of the MSI installer database, containing the following columns:

            IniFile A shortcut

            FileName The .URL file

            DirProperty The location for shortcut creation

            Section The ini file section in the ini file

            Key The key portion of the URL key-value combination

            URL The value portion, or

This type of editing can be done using the Orca tool that loads the table structure from an MSI file.


ClickOnce is a new deployment technology that provides valuable benefits and an auto-updating modality that was previously available only with a lot of custom programming or Application Blocks. For applications with more sophisticated requirements, Windows Installer MSI technology is still the deployment technology of choice. Each technology has the same goal of installing and updating applications, but they serve somewhat different purposes and have different capabilities. Fortunately, in some instances, these capabilities can be combined for the best of both worlds. It's not enough just to describe ClickOnce technology - you really have to publish, download and install your first ClickOnce app to see how cool it really is!

Peter Bromberg is a C# MVP, MCP, and .NET consultant who has worked in the banking and financial industry for 20 years. He has architected and developed web - based corporate distributed application solutions since 1995, and focuses exclusively on the .NET Platform.