ClickOnce

ClickOnce is a deployment technology that allows applications to be self updating. Applications are published to a file share, Web site, or media such as a CD. Once published, ClickOnce apps can be automatically updated with minimal user input.

ClickOnce also solves the security permission problem. Normally, to install an application the user would need Administrative rights. With ClickOnce a user can install and run an application with only the absolute minimum permissions required to run the application.

ClickOnce Operation

ClickOnce applications have two XML-based manifest files associated with them. One is the application manifest, and the other is the deployment manifest. These two files describe everything that is required to know to deploy an application.

The application manifest contains information about the application such as permissions required, assemblies to include, and other dependencies. The deployment manifest is about the deployment of the app. Items such as the location of application manifest is contained in the deployment manifest. The complete schemas for the manifests are in the .NET SDK documentation.

ClickOnce has some limitations. Assemblies cannot be added to the GAC, for example. The following table compares ClickOnce and Windows Installer.

Open table as spreadsheet

	ClickOnce	Windows Installer
Application installation location	ClickOnce application cache	Program Files folder
Install for multiple users	No	Yes
Install Shared files	No	Yes
Install drivers	No	Yes
Install to the GAC	No	Yes
Add application to Startup group	No	Yes
Add application to the favorites menu	No	Yes
Register file types	No	Yes
Access registry	No. The HKLM can be accessed with Full Trust permissions.	Yes
Binary patching of files	Yes	No
Install assemblies on demand	Yes	No

Some situations certainly exist where using Windows Installer is clearly a better choice; however, ClickOnce can be used for a large number of applications.

Publishing an Application

Everything that ClickOnce needs to know is contained in the two manifest files. The process of publishing an application for ClickOnce deployment is simply generating the manifests and placing the files in the proper location. The manifest files can be generated in Visual Studio 2005. There is also a command-line tool (mage.exe) and a version with a GUI (mageUI.exe).

You can create the manifest files in Visual Studio 2005 in two ways. At the bottom of the Publish tab on the Project Properties dialog are two buttons. One is the Publish Wizard and the other is Publish Now. The Publish Wizard asks several questions about the deployment of the application and then generates the manifest files and copies all of the needed files to the deployment location. The Publish Now button uses the values that have been set in the Publish tab to create the manifest files and copies the files to the deployment location.

In order to use the command-line tool, mage.exe, the values for the various ClickOnce properties must be passed in. Manifest files can be both created and updated using mage.exe. Typing mage.exe .help at the command prompt will give the syntax for passing in the values required.

The GUI version of mage.exe (mageUI.exe) is similar in appearance to the Publish tab in Visual Studio 2005. An application and deployment manifest file can be created and updated using the GUI tool.

ClickOnce applications appear in the Add/Remove Control Panel applet just like any other installed application. One big difference is that the user is presented with the choice of either uninstalling the application or rolling back to the previous version. ClickOnce keeps the previous version in the ClickOnce application cache.

ClickOnce Settings

Several properties are available for both manifest files. The most important property is where the application should be deployed from. The dependencies for the application must be specified. The Publish tab has an Application Files button that shows a dialog for entering all of the assemblies required by the application. The Prerequisite button displays a list of common prerequisites that can be installed along with application. You have the choice of installing the prerequisites from the same location that the application is being published to or optionally having the prerequisites installed from the vendor’s Web site.

The Update button displays a dialog that has the information about how the application should be updated. As new versions of an application are made available, ClickOnce can be used to update the application. Options include to check for updates every time the application starts or to check in the background. If the background option is selected, a specified period of time between checks can be entered. Options for allowing the user to be able to decline or accept the update are available. This can be used to force an update in the background so that the user is never aware that the update is occurring. The next time the application is run, the new version will be used instead of the older version. A separate location for the update files can be used as well. This way the original installation package can be located in one location and installed for new users, and all of the updates can be staged in another location.

The application can be set up so that it will run in either online or offline mode. In offline mode the application can be run from the Start Menu and acts as if it were installed using the Windows Installer. Online mode means that the application will run only if the installation folder is available.

Application Cache

Applications distributed with ClickOnce are not installed in the Program Files folder. Instead, they are placed in an application cache that resides in the Local Settings folder under the current user’s Documents and Settings folder. Controlling this aspect of the deployment means that multiple versions of an application can reside on the client PC at the same time. If the application is set to run online, every version that the user has accessed is retained. For applications that are set to run locally, the current and previous versions are retained.

Because of this, it is a very simple process to roll back a ClickOnce application to its previous version. If the user goes to the Add/Remove programs Control Panel applet, the dialog presented will contain the choice of removing the ClickOnce application or rolling back to the previous version. An Administrator can change the manifest file to point to the previous version. If the administrator does this, the next time the user runs that application, a check will be made for an update. Instead of finding new assemblies to deploy, the application will restore the previous version without any interaction from the user.

Security

Applications deployed over the Internet or intranet have a lower security or trust setting than applications that have been installed to the local drive have. For example, by default if an application is launched or deployed from the Internet it is in the Internet Security Zone. This means that it cannot access the file system, among other things. If the application is installed from a file share, it will run in the Intranet Zone.

If the application requires a higher level of trust than the default, the user will be prompted to grant the permissions required for the application to run. These permissions are set in the trustInfo element of the application manifest. Only the permissions asked for in this setting will be granted. So, if an application asks for file access permissions, Full Trust will not be granted, only the specific permissions asked for.

Another option is to use Trusted Application Deployment. Trusted Application Deployment is a way to grant permissions on an enterprise-wide basis without having to prompt the user. A trust license issuer is identified to each client machine. This is done with public key cryptography. Typically, an organization will have only one issuer. It is important to keep the private key for the issuer in a safe, secure location.

A trust license is requested from the issuer. The level of trust that is being requested is part of the trust license configuration. A public key used to sign the application must also be supplied to the license issuer. The license created contains the public key used to sign the application and the public key of the license issuer. This trust license is then embedded in the deployment manifest. The last step is to sign the deployment manifest with your own key pair. The application is now ready to deploy.

When the client opens the deployment manifest the Trust Manager will determine if the ClickOnce application has been given a higher trust. The issuer license is looked at first. If it is valid, the public key in the license is compared to the public key that was used to sign the application. If these match, the application is granted the requested permissions.

Advanced Options

The installation processes discussed so far are very powerful and can do quite a bit. But there is much more that you can control in the installation process. For example, you can use the various editors in Visual Studio 2005 to build conditional installations or add registry keys and custom dialog boxes. The SampleClientSetupSolution example has all of these advanced options enabled.

File System Editor

The File System Editor enables you to specify where in the target the various files and assemblies that make up the application will be deployed. By default, a standard set of deployment folders is displayed. You can add any number of custom and special folders with the editor. This is also where you would add desktop and Start Menu shortcuts to the application. Any file that must be part of the deployment must be referenced in the File System Editor.

Registry Editor

The Registry Editor allows you to add keys and data to the registry. When the editor is first displayed, a standard set of main keys is displayed:

• HKEY_CLASSES_ROOT

• HKEY_CURRENT_USER

• HKEY_LOCAL_MACHINE

• HKEY_USERS

HKEY_CURRENT_USER and HKEY_LOCAL_MACHINE contain additional entries in the Software/[Manufacturer] key where Manufacturer is the information you entered in the Manufacturer property of the deployment project.

To add additional keys and values, highlight one of the main keys on the left side of the editor. Select Action from the main menu, and then select New. Select the key or the value type that you want to add. Repeat this step until you have all of the registry settings that you want. If you select the Registry on target Machine item on the left pane and then select the Action menu, you will see an Import option, which enables you to import an already defined *.reg file.

To create a default value for a key you must first enter value for the key, then select the value name in the right or value pane. Select Rename from the File menu, and delete the name. Press Enter, and the value name is replaced with (Default).

You can also set some properties for the subkeys and values in the editor. The only one that hasn’t been discussed already is the DeleteAtUninstall property. A well-designed application should remove all keys that have been added by the application at uninstall time. The default setting is not to delete the keys.

One thing to keep in mind is that the preferred method for maintaining application settings is to use XML-based configuration files. These files offer a great deal more flexibility and are much easier to restore and back up than registry entries.

File Types Editor

The File Types editor is used to establish associations between files and applications. For example, when you double-click a file with the .doc extension, the file is opened in Word. You can create these same associations for your application.

To add an association, select File Types on Target Machine from the Action menu. Then select Add File Type. In the properties window, you can now set the name of the association. In the Extension property, add the file extension that should be associated with the application. Do not enter the periods; you can separate multiple extensions with a semicolon, like this: ex1;ex2. In the Command property, select the ellipse button. Now, select the file (typically an executable) that you want to associate with the specified file types. Keep in mind that any one extension should be associated with only one application.

By default, the editor shows &Open as the Document Action. You can add others. The order in which the actions appear in the editor is the order in which they will appear in the context menu when the user right-clicks the file type. Keep in mind that the first item is always the default action. You can set the Arguments property for the actions. This is the command-line argument used to start the application.

User Interface Editor

Sometimes you might want to ask the user for more information during the installation process. The User Interface editor is used to specify properties for a set of predefined dialog boxes. The editor is separated into two sections, Install and Admin. One is for the standard installation and the other is used for an administrator’s installation. Each section is broken up into three subsections: Start, Progress, and End. These subsections represent the three basic stages of the installation process (see Figure 15-4).

Figure 15-4

The following table lists the types of dialog boxes that you can add to the project.

Open table as spreadsheet

Dialog Box	Description
Checkboxes	Contains up to four check boxes. Each check box has a Label, Value, and Visible property.
Confirm Installation	Gives the user the ability to confirm the various settings before installation takes place.
Customer Information	Has edit fields for the collection name, organization name, and serial number. Organization name and serial number are optional.
Finished	Displayed at the end of the setup process.
Installation Address	For Web applications, displays a dialog box so that users can choose an alternate installation URL.
Installation Folder	For client applications, displays a dialog box so that users can select an alternate installation folder.
License Agreement	Displays the license agreement that is located in a file specified by the LicenseFile property.
Progress	Displays a progress indicator during the installation process that shows the current installation status.
RadioButtons	Contains up to four radio buttons. Each radio button has a Label and Value property.
Read Me	Shows the readme information contained in the file specified by the ReadMe property.
Register User	Executes an application that will guide the user through the registration process. This application must be supplied in the setup project.
Splash	Displays a bitmap image.
TextBoxes	Contains up to four text box fields. Each text box has a Label, Value, and Visible property.
Welcome	Contains two properties: the WelcomeText property and the CopyrightWarning. Both are string properties.

Each of these dialog boxes also contains a property for setting the banner bitmap, and most have a property for banner text. You can also change the order in which the dialog boxes appear by dragging them up or down in the editor window.

Now that you can capture some of this information, the question is, how do you make use of it? This is where the Condition property that appears on most of the objects in the project comes in. The Condition property must evaluate to true for the installation step to proceed. For example, say the installation comes with three optional installation components. In this case, you would add a dialog box with three check boxes. The dialog should be somewhere after the Welcome and before the Confirm Installation dialog box. Change the Label property of each check box to describe the action. The first action could be “Install Component A,” the second could be “Install Component B,” and so on. In the File System editor select the file that represents Component A. Assuming that the name of the check box on the dialog box is CHECKBOXA1, the Condition property of the file would be CHECKBOXA1=Checked - that is, if CHECKBOXA1 is checked, install the file; otherwise, don’t install it.

Custom Actions Editor

The Custom Actions editor allows you to define custom steps that will take place during certain phases of the installation. Custom actions are created beforehand and consist of a DLL, EXE, script, or Installer class. The action would contain special steps to perform that can’t be defined in the standard deployment project. The actions will be performed at four specific points in the deployment. When the editor is first started, you will see the four points in the project (see Figure 15-5):

• Install - Actions will be executed at the end of the installation phase.

• Commit - Actions will be executed after the installation has finished and no errors have been recorded.

• Rollback - Actions occur after the rollback phase has completed.

• Uninstall - Actions occur after uninstall has completed.

Figure 15-5

To add an action, you first select the phase of the installation in which you want the action to occur. Select the Add Custom Action menu option from the Action menu to open the file system dialog box. This means that the component that contains the action must be part of the deployment project. Because it will be executing on the target machine it has to be deployed; therefore, it should be listed in the File System editor.

After you have added the action, you can select one or more of the properties listed in the following table.

Open table as spreadsheet

Arguments	Command-Line Arguments
Condition	A Windows Installer condition that must be evaluated and result in true for the action to execute.
CustomDataAction	Custom data that will be available to the action.
EntryPoint	The entry point for the custom DLL that contains the action. If the Action is contained in an executable, this property does not apply.
InstallerClass	A Boolean value that, if true, specifies that the action is a .NET ProjectInstaller class.
Name	Name of the action. Defaults to the file name of the action.
SourcePath	The path to action on the development machine.

Because the action is code that you develop outside of the deployment project, you have the freedom to add just about anything that adds a professional touch to your application. The thing to remember is that these actions happen after the phase it is associated with is complete. If you select the Install phase, the action will not execute until after the install phase has completed. If you want to make determinations before the process, you will want to create a launch condition.

Launch Conditions Editor

The Launch Conditions editor allows you to specify that certain conditions must be met before installation can continue. Launch conditions are organized into types of conditions. The basic launch conditions are File Search, Registry Search, and Windows Installer Search. When the editor is first started you see two groups (see Figure 15-6): Search Target Machine and Launch Conditions. Typically, a search is conducted, and, based on the success or failure of that search, a condition is executed. This happens by setting the Property property of the search. The Property property can be accessed by the installation process. It can be checked in the Condition property of other actions, for example. You can also add a launch condition in the editor. In this condition, you set the Condition property to the value of the Property property in the search. In the condition, you can specify a URL that will download the file, registry key, or installer component that was being searched for. Notice in Figure 15-6 that a .NET Framework condition is added by default.

Figure 15-6

File Search will search for a file or type of file. You can set many different file-related properties that determine how files are searched, including file name, folder location, various date values, version information, and size. You can also set the number of subfolders that are searched.

Registry Search allows you to search for keys and values. It also allows you to set the root key for searching.

Windows Installer Search looks for the specified Installer component. The search is conducted by GUID.

The Launch Conditions editor provides two prepackaged launch conditions: the .NET Framework Launch Condition, which allows you to search for a specific version of the runtime, and a search for a specific version of MDAC, which uses the registry search to find the relevant MDAC registry entries.