ClickOnce Configuration

The Publish Wizard is a lightweight UI wrapper that provides a quick-fire publishing option. However, the Publish Wizard hides the rich support provided by ClickOnce from VS05 that allows developers to tailor application deployment to fit a wide range of scenarios. The place you start is the Publish tab of a project's property pages, as shown in Figure 19.16.

Figure 19.16. Configuring ClickOnce Deployment for Your Application from the Publish Tab

Now let's look at the configurations available from the Publish tab.

Bootstrapping

Before an application can be installed, the client machine must meet certain installation requirements. For Windows Forms 2.0 applications, this means that the client must have installed at least Windows 98 and the .NET Framework 2.0 in order to run both the application and ClickOnce. If an application has other prerequisites, the client machine must be bootstrapped with them. Bootstrapping is the process of determining the minimum set of prerequisites for executing an application, checking the client for those prerequisites, and installing any that are missing.

VS05 allows you to specify your application's prerequisite installation needs in the Prerequisites dialog shown in Figure 19.17. The Prerequisites dialog is available by clicking Properties | Prerequisites.

Figure 19.17. Configuring ClickOnce Published Application Prerequisites

.NET Framework 2.0 is checked as a prerequisite by default, and you can select or deselect other prerequisites as dictated by your application's requirements and your expected client needs. Windows Installer 2.0 and 3.1 versions are included with the .NET Framework 2.0 redistributable, so you probably don't need to check those.

Additionally, VS05 does its best to anticipate your prerequisites; for example, if you include a SQL Server .mdf file in your application, the "SQL Server 2005 Express Edition" option listed in the Prerequisites dialog is automatically checked. If your prerequisites are not available from the list, you can click "Check Microsoft Update for more redistributable components" to find them. ^[11]

^[11] You have several more options for configuring this list and the bootstrapper in general, all of which are covered in a very good article by Seane Draine: http://msdn.microsoft.com/msdnmag/issues/04/10/Bootstrapper/ (http://tinysells.com/44).

After you specify your prerequisites, you can also specify where the bootstrapper will get thema component vendor's web site, your application's publish location, or some other location.

When an application is published, your prerequisite configurations are turned into the setup.exe that VS05 generates by default. When run on the client, setup.exe pulls down and executes the installer for each missing prerequisite. If you choose to have users download the installers from your application's publish location, VS05 ensures that the required installers are copied there, as shown in Figure 19.18.

Figure 19.18. Making Application Prerequisite Installers Available in Your Publish Location

You can see that the .NET Framework 2.0 installer (dotnetfx.exe) and Microsoft Data Access Components 2.0 (mdac_typ.exe) are copied to their own folders.

The ability to detect whether .NET Framework 2.0 is installed on the client machine is built into publish.htm with JavaScript. If .NET Framework 2.0 is the only selected prerequisite and is installed, then publish.htm tailors itself to display a link directly to the deployment manifest, as you saw earlier. However, if .NET Framework 2.0 is not found, or if further prerequisites are required, publish.htm renders differently, as shown in Figure 19.19.

Figure 19.19. Configuring ClickOnce Published Application Prerequisites

You can see that all the prerequisites are listed, and clicking the Install button will download and execute setup.exe instead of the deployment manifest. If users think they have the appropriate prerequisites already installed, they can bypass the setup and run the application immediately by clicking the "launch" link.

After the setup application has completed execution, the version-to-install deployment manifest is automatically downloaded and processed to continue the application launch.

Application Files

Just as you need to make sure that a client machine contains the appropriate prerequisites, you also need to make sure that VS05 publishes the application and data files your application requires to execute, which can often be more than a single assembly. Fortunately, VS05 does a great job of identifying these files. You can view its selection in the Application Files dialog, shown in Figure 19.20, by clicking the Application Files button on the Properties tab.

Figure 19.20. Configuring Mandatory ClickOnce Application Files

For Wahoo, VS05 has already identified both Wahoo.exe and Wahoo.exe.config and has marked them as mandatory (colored gray): They cannot be removed from this list. WahooControlLibrary.dll is also there and is required, although it can be excluded just as debug (.pdb) files are by default. You can change the publish status of the listed files from the drop-down in the Publish Status column, which supports the options shown in Figure 19.21.

Figure 19.21. Changing the Default Publish Status

The default Publish Status of (Auto) specifies that VS05 decides based on file type.^[12] Include and Exclude are self-explanatory. Data File specifies that files like Access .mdb files are stored in the data folder of the deployed application.^[13] You can add files to this list by adding them to your project and setting their Build Action to Content, after which you can change their publish status as required.

^[12] By default, .pdb files are excluded, and .mdf, .ldf, .mdb, and .xml files are set to a Data File publish status. Files marked with a Build Action of Content are marked with a publish status of Include.

^[13] This location is the Data folder, which is found under %userprofile%\local settings\apps\data\hashed_path\data.

The Application Files dialog also provides a context menu for each file in the list. In this menu, you can create download groups, reset the configuration of each file to its original value, and delete files removed from the project.^[14] Whatever choices you make apply equally to all project configurations, including Debug and Release.

^[14] Download groups are named sets of files that can be downloaded on demand, using the ClickOnce deployment framework, rather than with the initial application installation. The SDK is the place to start for more information.

Publisher Details

Irrespective of the publish location from which users launch an application, they will probably want to know something about the publisher and product before they install it. ClickOnce allows you to configure publisher and product names as well as specify a web page users can visit for detailed product and support details. These options can be set from the Publish Options dialog, shown in Figure 19.22. It is accessible by clicking the Options button on the Publish tab.

Figure 19.22. Configuring Publisher and Product Names

Applying these configurations changes publish.htm, as shown in Figure 19.23.

Figure 19.23. Product Name, Publisher Name, and Support URL on publish.htm

As you can see, the product name, publisher name, and support URL are all included on the publish.htm page. Additionally, the product name finds its way onto the Security Warning dialog, as shown in Figure 19.24.^[15]

^[15] Note that the publisher in this case is not the publisher you configure via the Publish Options dialog. Instead, this refers to the publisher that digitally signed the application, which is discussed later in this chapter.

Figure 19.24. Product Name on the Security Warning Dialog

Publisher name, product name, and support URL are also used for Start menu integration, as shown in Figure 19.25.

Figure 19.25. Product Name, Publisher Name, and Support URL in the Start Menu

Finally, all these details are available in the Add or Remove Programs control panel entry for the application, as shown in Figure 19.26.

Figure 19.26. Product Name, Publisher Name, and Support URL in the Control Panel

Figures 19.25 and 19.26 illustrate the desire for ClickOnce to provide an informative user experience, including right in the Windows shell. Sometimes, however, ClickOnce-deployed applications may not require this level of integration with the shell; how much is determined by the install mode of a ClickOnce-deployed application.

Install Mode

ClickOnce weds Windows Forms development with web-style deployment, allowing clients to automatically stay keep their applications up-to-date. Additionally, ClickOnce offers a variety of version management features, all of which are dependent on a ClickOnce-deployed application's install mode.

The install mode specifies whether an application can be executed without a network connection. Consequently, there are two install modes: online/offline and online. Online/Offline install mode, the default, specifies that a ClickOnce-deployed application can execute without a network connection, which is a great option for standalone and smart client (semiconnected) applications.^[16] For example, Wahoo makes a great candidate for online/offline mode, because game play does not depend on a network connection, although high scores can be sent to and retrieved from a scores web service when connected to a network.

^[16] The term smart client means many things to many people, although one might consider a key characteristic of smart client applications to be the ability to operate in a semiconnected fashion. Further information regarding smart clients can be found at http://msdn.microsoft.com/smartclient (http://tinysells.com/45).

For applications that require a network connection to execute, however, developers can prevent them from starting without one by choosing online install mode. Online applications typically need to be online because resources they depend on, such as web services and databases, are available only online.

You can configure the install mode from either the Publish tab (see Figure 19.15) or the Publish Wizard, shown in Figure 19.27.

Figure 19.27. Configuring Install Mode via the Publish Wizard

For users, the difference between the two install modes is one of appearance: Online/ Offline applications integrate with the shell to provide Start menu access to the application, and online applications don't. With the latter, users are forced to rerun the application from its original deployment location. In reality, though, ClickOnce-deployed applications are always downloaded to, installed on, and executed from the client machine.

Versioning

Whether an application's install mode is online or online/offline, users receive the latest version of the application when it is launched from the publish location. However, because the Start menu icons for online/offline applications load locally installed versions, we need to deploy a versioning policy with an application to instruct ClickOnce to check for and download a new application version when a network connection is available.

ClickOnce offers a variety of application update options that specify when and how updates are retrieved.

Publish Version

You can tell ClickOnce when and how to pick up new application versions, although they first need to be generated. This relies on managing an application's publish version, which is a ClickOnce-specific version number that can be configured from the Publish tab of a project's property pages, shown in Figure 19.28.

Figure 19.28. Configuring the Publish Version

The publish version comprises major, minor, build, and revision numbers; the same shape as the assembly and file version numbers you can specify via the AssemblyVersion and FileVersion attributes. However, assembly and file version numbers are independent of the publish number.^[17] This means that you can publish one version of an application after one or more build versions have been produced.

^[17] See Chapter 15: Settings for more information on the AssemblyVersion and FileVersion attributes.

You can increment the version number manually (for custom version-numbering policies), or you can let VS05 do it automatically for you by selecting the "Automatically increment revision with each publish" option. If you choose to autoincrement, the version number is updated after an application is published. Consequently, your application's first publish version will be 1.0.0.0. When the application is next published, a new version is uploaded to the publish location, as shown in Figure 19.29.^[18]

^[18] If you try to republish an application with a publish version that has already been used, VS05 provides an appropriate warning.

Figure 19.29. New Published Version of the Application

When and how this update is picked up on the client machine are determined by a variety of options available in the Application Updates dialog, shown in Figure 19.30. You open this dialog by clicking the Updates button on the Publish tab of your project's property pages.

Figure 19.30. Configuring When and How a ClickOnce-Deployed Application Is Updated

You have a variety of options that include setting whether a ClickOnce-deployed application should even check for updates using the "The application should check for updates" check box. When checked, the update controls are enabled, allowing you to specify when and how often to check for updates.

Downloading a New Application Version

When an online/offline application is next launched in the presence of a network connection, ClickOnce compares the publish version number of the version installed on the client with the publish version number of the application referenced by the version-to-install deployment manifest. If the two values are different, it proceeds with an upgrade and displays the Update Available dialog, shown in Figure 19.31.

Figure 19.31. Informing the User of a New Application Version

Before users decide whether to download the new version, they can find more information about the update from the application's support web page, which they open by clicking the Name link. ^[19] If users are satisfied, they can get the new version by clicking OK, or they can click Skip to load their currently installed version.

^[19] This information is available only if you provide a support web page, something that is certainly recommended.

If users click the Skip button, ClickOnce is instructed to wait seven days before again asking to update. However, if the dialog's Close button is clicked (X in the upper-right corner), users are asked to update the next time the application is launched.

Rollback

No matter how much testing you do, you may publish new application versions that contain bugs or whose behavior breaks existing functionality. For these situations, online/offline applications come with additional shell integration in the form of the Maintenance dialog. It's available from the Add or Remove Programs control panel, shown in Figure 19.32.

Figure 19.32. Restoring or Removing the Application

The Maintenance dialog is a safety net that supports rolling back a defective ClickOnce-deployed application to the previous version, if installed. To reinstall earlier versions, users should be able to access the version-specific deployment manifests, as discussed earlier. If that doesn't do the trick, users can completely remove the application from their computer.