The CAB Project template is used to create a cabinet file. A cabinet file (.cab) can contain any number of files. It is often used to package a set of related components in an application.

Controls hosted within Internet Explorer are often packaged into a cabinet file, with a reference added to the file in the Web page that uses the control. When Internet Explorer encounters this reference, it confirms that the control isn't already installed on the user's computer, at which point it downloads the cabinet file, extracts the control, and installs it to a protected part of the user's computer.

You can compress cabinet files to reduce their size and consequently the amount of time it takes to download them.

The Merge Module Project template is used to create a merge module, which is similar to a cabinet file in that it can be used to package a group of files. The difference is that a merge module file (.msm) cannot be used by itself to install the files that it contains. The merge module file created by this project template can only be used within another setup project.

Merge modules were introduced as part of the Microsoft Windows Installer technology to enable a set of files to be packaged into an easy-to-use file that could be reused and shared between Windows-Installer-based setup programs. The idea is to package all the files and any other resources (e.g., registry entries, bitmaps, and so on) that are dependent on each other into the merge module.

This type of project can be very useful for packaging a component and all its dependencies. The resulting merge file can then be used in the setup program of each application that uses the component. This enables applications such as Crystal Reports to have a prepackaged deployment set that can be integrated into the deployment of other applications.

The Setup Project template is used to create a standard Windows Installer setup for an application, which is normally installed in the Program Files directory of a user's computer.

The Web Setup Project template is used to create a Windows Installer setup program that can be used to install a project into a virtual directory of a web server. It is intended to be used to create a setup program for a Web application, which may contain ASP.NET Web Forms or Web services.

The Smart Device CAB Project template is used to create a CAB file for an application that runs on a device containing the .NET Compact Framework, such as a Pocket PC device. Such applications are often referred to as mobile applications, and they have many capabilities and limitations that do not apply to other .NET-based applications. This book does not discuss mobile applications, so this template isn't covered here.

The Setup Wizard can be used to help guide you through the creation of any of the previous setup and deployment project templates except the Smart Device CAB template.

First create an application that will serve as the desktop application you want to deploy. Create a new project and choose Windows Application from the list of available Visual Basic project templates. Name the project SampleForDeployment and don't add any code to it yet.

Next, add a new project to the solution and choose Setup Project from the list of available Setup and Deployment Project templates. You now have a Visual Studio solution containing two projects.

When created, the deployment project does not contain any files. It has a folder called Detected Dependencies, which is discussed later. You will need to add the executable file from your Windows application SampleForDeployment to the deployment project.

You add files to a setup deployment project using the Add function, which is available in two places: You can select the deployment project in the Solution Explorer and use the Add option from the Project menu, or you can right-click the setup project file in the Solution Explorer and choose Add from the pop-up menu. Both methods enable you to choose from one of four options:

Add the output of the Windows application project to the setup project. Select the Project Output menu item to bring up the dialog box shown in Figure 24-3.

Figure 24.3. Figure 24-3

The Add Project Output Group dialog box is divided into several parts:

Click OK to return to the solution.

At this point, not only has the output from the Windows application been added to the Setup project, but the Detected Dependencies folder also contains an entry.

Whenever you add a .NET component to this deployment project, its dependencies are added to this folder. The dependencies of the dependencies are also added, and so on until all the required files have been added. The files listed in the Detected Dependencies folder are included in the resulting setup and, by default, are installed into the application's directory as application-private assemblies. This default behavior helps reduce the possible effects of DLL hell by making the application use its own copies of dependent files.

If you don't want a particular dependency file to be included in the resulting setup, you can exclude it by right-clicking the file entry under Detected Dependencies and selecting Exclude from the pop-up menu. For example, you may decide that you want to exclude a detected dependency from the setup of an application because you know that the dependency is already installed on the target computer. The dependency will then have a small "circle and slash" icon before its name to indicate that it has been excluded.

You can select an item in the setup project in the Solution Explorer and that particular item's properties will be displayed in the Properties window. Because there are too many properties to discuss them all, we will take a look at the properties from the root setup node and each of the two different project items. First, however, make sure that the root setup node is selected, and take some time to browse the list of available properties.

The root setup node represents the output from this deployment project type: a Windows Installer package (.msi). Therefore, the Properties window contains properties that affect the resulting .msi that is produced.

Another commonly used deployment scenario is that of a Web application that has been created using the ASP.NET Web Application Project template. Typically, the Web application is developed on a development web server, and you need to create a deployment project to transfer the finished application to a production web server.

For this scenario, the template to use is the Web Setup Project template. There is one major difference between this template and the previously described Setup Project template: The Web Setup Project will, by default, deploy the application to a virtual directory of the web server on which the setup is run, whereas a Setup Project deploys the application to the Program Files folder on the target machine by default.

There are substantial similarities between producing a deployment project for this scenario and producing a Windows application deployment project as shown in the walk-through. They both produce a Windows Installer package and have the same set of project properties discussed earlier.

As in the previous walk-through, you need to add the output of the Web application to the deployment project. This is accomplished in much the same way as earlier, by right-clicking on a Web Setup project and selecting Add — Project Output. There is one key difference: When you add the project representing the website, the only option you have for the type of files to add is Content Files, which encompasses the files that make up the website.

As before, if you build such a project, then the result in an .msi file, which can be used in this case to deploy a website.

The only page available from the Property Pages dialog is the Build page. The options on this page can be used to affect the way that the resulting Windows Installer package is built.

As with most other projects in VS 2008, you can create different build configurations. Use the Configuration combo box to select the build configuration for which you want to alter properties. In Figure 24-4, notice that you are modifying the properties for the currently active build configuration: Debug. The button labeled Configuration Manager enables you to add, remove, and edit the build configurations for this project.

The Output File Name setting can be used to modify where the resulting Windows Installer package (.msi) file is created. You can modify the filename and path directly or you can click the Browse button.

Prerequisites

Prerequisites are standard components that may be needed to install or run the application but are not a part of the application. There are several of these, as shown in Figure 24-5, which shows the dialog that is displayed when the Prerequisites button is clicked.

The .NET Framework is checked by default, and so is the Windows Installer. You should only uncheck these if you are sure that all the machines upon which your application will be installed already have the correct versions of these prerequisites installed. As mentioned earlier in this chapter, Visual Studio 2008 allows targeting of the .NET Framework version you would like to use (2.0, 3.0, or 3.5), so the targeted version of the framework needs to be coordinated with the prerequisites.

If the box for any of these prerequisites is checked, then the resulting installation package will automatically check for the presence of that prerequisite and install it if required. If you are installing from a CD or network share, then it is common for the packages that install these prerequisites to be placed in the same location as your installation package. The default settings assume that this is true and install the prerequisites from that location.

Figure 24.5. Figure 24-5

However, you can specify a different location for packages that install prerequisites. You can select the "Download prerequisites from the following location:" option at the bottom of the dialog and then specify the URL at which the packages are located. Alternately, you can select "Download prerequisites from the component vendor's web site," and then the Installation URL on the previous dialog will be used (refer to Figure 24-5).

To add an item that needs to be installed to a folder, you can either right-click the folder in the left pane and choose Add from the pop-up menu or you can select the required folder, right-click in the right pane, and again choose Add from the pop-up menu. You will be presented with four options, three of which were discussed earlier in the walk-through:

The fourth option (Folder) enables you to add a subfolder to the currently selected folder. This subfolder then becomes a standard folder that can be used to add files. If you add any .NET components or executables, the dependencies of these components are also added to the installation automatically.

When you create a new deployment project, a set of standard folders is created for you (listed in the desktop application section). If the folders created do not match your requirements, you can also use the File System editor to add special folders. To add a special folder, right-click anywhere in the left pane (other than on a folder), and you will be presented with a pop-up menu containing one item: Add Special Folder. This menu item expands to show you a list of folders that you can add to the installation (folders already added to the project are grayed out).

You can choose from several system folders, which are summarized in the following table:

If none of the built-in folders match your requirements, you can create your own custom folder. Right-click in the left pane of the File Editor and choose Custom Folder from the pop-up menu.

The new folder is created in the left pane of the editor. The folder name appears in edit mode, so enter the name of the folder and press Enter. The folder will now be selected, and the Properties window will change to show the properties of the new folder. The properties of a folder are summarized in the following table:

Suppose you name your folder "Wrox Press" and you set the DefaultLocation property for your folder to [FavoritesFolder]Wrox Press. You could add some shortcuts to this folder using the technique described in the following section. When the installation is run, a new folder is added to the user's Favorites folder called Wrox Press, and those shortcuts are placed in it.

The first step in creating a shortcut is to locate the file that is the target of the shortcut. Select the target file and right-click it. The pop-up menu that appears includes an option to create a shortcut to the selected file, which is created in the same folder. Select this option.

To add the shortcut to the user's desktop, you need to move this shortcut to the folder that represents the user's desktop. Likewise, you could move this shortcut to the folder that represents the user's Programs menu. Cut and paste the new shortcut to the User's Desktop folder in the left pane of the editor. The shortcut will be added to the user's desktop when the installation is run. You should probably rename the shortcut, which is easily accomplished via the Rename option of the pop-up menu.

This has been only a brief tour of the File System Editor. There are many additional capabilities that you can explore.

Before adding a value, you must select (or create) the registry key that will hold the value. There are several ways to add the registry value:

For illustrational purposes here, select one of the Software registry keys. The Action menu contains one item, New, which contains a number of submenu items:

Using this menu, you can create a new registry key below the currently selected key (via Key), or you can create a value for the currently selected registry key using one of the four Value types: String, Environment String, Binary, and DWORD.

For example, suppose you need to create a registry entry that informs the application whether or not to run in Debug mode. The registry value must be applicable to a particular user, must be called Debug, and must contain the text True or False.

The first step is to select the following registry key in the left pane of the editor:

HKEY_CURRENT_USERSoftware [Manufacturer].

The registry key HKEY>_CURRENT>_USER is used to store registry settings that apply to the currently logged-in user.

Now you want to create a value that it is applicable to only this application, not all applications created by you. You need to create a new registry key below the HKEY>_CURRENT>_USER Software Manufacturer] key that is specific to this product, so select the Action

When the key is created, the key name is editable, so give it a name of [ProductName] and press Enter. This creates a key that is given the name of the product contained within this Windows Installer package. The ProductName property of the setup was discussed earlier in this chapter.

Now that you have created the correct registry key, the next step is to create the actual registry value. Make sure that your new registry key is selected, and choose String Value from the Action

Once the value has been created, you can set a default value for it in its Properties window; in this case False. When the Windows Installer package is run in the Debug registry, the value will be created. If a value already exists in the registry, then the Windows Installer package will overwrite the existing value with what is defined in the Registry Editor.

You can move around most keys and values in the Registry Editor by using cut and paste or simply by dragging and dropping the required item.

The alternative to creating registry entries during installation is to have your application create registry entries the first time they are needed. However, this has one significant difference from registry keys created with a Windows Installer package. The uninstall corresponding to a Windows Installer installation automatically removes any registry keys created during the install. If the registry entries are created by the application instead, then the uninstall has no way of knowing that these registry entries should be removed.

If you already have a registry file containing the registry settings that you would like to be created, you can import the file into the Registry Editor. To import a registry file, you need to ensure that the root node (Registry on Target Machine) is selected in the left pane of the editor. You can then use the Import item of the Action menu to select the registry file to import.

If you want to create the registry entries that are required to create file associations, then use the editor covered next.

The installation can run in two modes, which correspond to the two root nodes of the editor: Install and Administrative Install. These distinguish between an end user installing the application and a system administrator performing a network setup.

The Install mode is most frequently used and is what you will use in this exercise. As mentioned earlier, the installation steps are divided into three stages, represented as subnodes of the parent installation mode.

The order in which the dialog boxes appear within the tree view determines the order in which they are presented to the user during an installation. Dialog boxes cannot be moved between different stages.

The order of the dialog boxes can be changed by dragging the respective dialog boxes to the position in which you want them to appear. You can also move a particular dialog box up or down in the order by right-clicking the dialog box and selecting either Move Up or Move Down.

A set of predefined dialog boxes has been added to the project for you, enabling actions such as prompting a user for a registration code. If these do not match your requirements, you can add or remove dialog boxes in any of the stages.

When adding a dialog box, you have the choice of using a built-in dialog box or importing one. To illustrate how to add a dialog box, consider an example of adding a dialog box to display a ReadMe file to the user of a Windows Installer package. The ReadMe file needs to be displayed before the actual installation of the files occurs.

The first step is to choose the mode in which the dialog box is to be shown: Install or Administrative Install. In this example, you will use the Install mode. Next, you need to determine the stage at which the dialog box is to be shown. In the example, you want to display the ReadMe file to the user before the actual installation of the files occurs, which means you have to show the ReadMe file in the Start stage. Make sure the Start node is selected below the Install parent node.

You are now ready to add the dialog box. Using the Action menu again, select the Add Dialog menu item, which will display a dialog box (see Figure 24-10) from which you can choose the desired dialog box.

As you can see, several built-in dialog boxes are available. Each dialog box includes a short description that appears at the bottom of the window to inform you of its intended function. In this case, you want to use the Read Me dialog box, so select it and click OK.

New dialog boxes are always added as the last dialog box in the stage that they are added to, so now you need to move it into the correct position. In this case, you want the Read Me dialog box to be shown immediately after the Welcome dialog box, so drag and drop it into position.

Figure 24.10. Figure 24-10

Like most other project items in Visual Studio, dialog boxes have a set of properties that you can change to suit your needs using the Properties window. If you make sure a dialog box is selected, you will notice that the Properties window changes to show the properties of the selected dialog box. The properties that appear vary according to the dialog box selected. Details of all the properties of the built-in dialog boxes can be found by looking at the "Properties of the User Interface Editor" topic in the MSDN documentation.

To add a custom action you must select the node of the event into which you want to install the action. You can then use the Action menu to select the executable, DLL, or script that implements the custom action. The four actions defined in the editor are described in the following table:

Suppose that you want to start your application as soon as the installation is completed successfully. Use the following process to accomplish this.

First, decide when the action must occur. Using the preceding table, you can see that the Commit event will be run when the installation has been successful. Ensure that this node is selected in the editor. You are now ready to add the actual action you want to occur when the Commit event is called. Using the Action menu again, select the Add Custom Action menu item, which will display a dialog box that you can use to navigate to and select a file (.exe, .dll, or Windows script) from any that are included in the File System Editor. For this example, select Primary output from WindowsApplication (Active), which is contained within the Application Folder.

As with most items in the editors, the new custom action has a number of properties. Here are some of the properties you are most likely to need:

Set the InstallClass property to equal False because your application does not contain an Installer class.

That's it. When you run the Windows Installer package and the installation is successful, the application will automatically start. The custom action that you implemented earlier is very simple, but custom actions can be used to accomplish any customized installation actions that you could want. Take some time to play around with what can be accomplished using custom actions. For instance, try creating a custom action that writes a short file into the application directory.

To add a file search, you begin by searching for the Microsoft Word 2007 executable. Making sure the Search Target Machine node is currently selected in the editor, add a new file search by selecting the Add File Search item from the Action menu. The new item should be given a meaningful name, so enter Word2007Search. The end result is shown in Figure 24-12.

Like most items contained within the editors mentioned in this chapter, the new file search item has a set of properties that you can modify using the Properties window. The properties of the file search item determine the criteria that will be used when searching for the file. Most of the properties are self-explanatory and have been covered in previous sections, so they are not covered in this chapter.

In this example, you need to search for the Microsoft Word 2007 executable, which means that a number of these properties need to be modified to match your own search criteria.

The first property that requires modification is FileName. In this case, you are searching for the Microsoft Word 2007 executable, so enter winword.exe as the value for this property. Previous versions of Microsoft Word used the same filename.

There is no need to search for the file from the root of the hard drive. The Folder property can be used to define the starting folder for the search. By default, the value is [SystemFolder], which indicates that the search will start from the Windows system folder. There are several of these built-in values; if you are interested, you can look up what these folders correspond to in the section "Adding Special Folders."

In this example, you do not want to search the Windows system folder because Microsoft Word is usually installed in the Program Files folder. Set the value of the Folder property to [ProgramFilesFolder] to indicate that this should be your starting folder.

When the search starts, it will only search the folder specified in the Folder property, as indicated by the default value (0) of the Depth property. The Depth property is used to specify how many levels of subfolders the search will look in for the file in question, beginning from the starting folder specified. Note that there are performance issues associated with the Depth property. If a search is performed for a file that is very deep in the file system hierarchy, then it can take a long time to find the file. Therefore, wherever possible, use a combination of the Folder and Depth properties to decrease the possible search range. The file that you are searching for in your example will probably be at a depth of greater than 1, so change the value to 3.

There may be different versions of the file that you are searching for on a user's machine. You can use the remaining properties to specify a set of requirements for the file that must be met in order for it to be found, such as minimum version number or minimum file size.

You are searching for the existence of Microsoft Word 2007, which means you need to define the minimum version of the file that you want to find. To search for the correct version of winword.exe, you need to enter 12.0.0.0 as the value for the MinVersion property. This ensures that the user has Microsoft Word 2007 or later installed and not an earlier version.

To use the results of the file search, there must be a name for the results. This name is assigned to a Windows Installer property and is normally used to create a launch condition later. The Property property is where this name is specified.

For our example, enter WORDEXISTS as the value for the Property property. If the file search is successful, then the full path to the found file will be assigned to this Windows Installer property; otherwise, it will be left blank. At this point, the Properties window should look like the window shown in Figure 24-13.

A file search alone is pretty useless. The second step of the process of ensuring that the user has Microsoft Word 2007 installed is creating a launch condition that uses the results of the file search.

Make sure that the Launch Conditions node is selected in the editor, and add a new launch condition to the project by selecting Add Launch Condition from the Action menu. You need to give this new item a meaningful name; in this case, give it a name of Word2007Exists (see Figure 24-14).

This new item has a number of properties that you will need to modify. The first property you will change is called Message, and it is used to set the text of the message box that appears if this condition is not met. Enter any meaningful description that explains why the installation cannot continue.

Figure 24.13. Figure 24-13

Figure 24.14. Figure 24-14

The next property that you need to change is called Condition. It is used to define a valid deployment condition that is evaluated when the installation runs. The deployment condition entered must evaluate to True or False. When the installer is run, the condition is evaluated; if the result of the condition is False, then the message defined is displayed to the user and the installation stops.

For this example, you need to enter a condition that takes into account whether the winword.exe file was found. You can use the Windows Installer property defined earlier (WORDEXISTS) as part of the condition. Because the property is empty if the file was not found, and non-empty if the file was found, you can perform a simple test to determine whether the property is empty to create the condition. Enter WORDEXISTS <> "" as the value for the Condition property.

It is hoped that based on the preceding discussion of this search, you will be able to understand how to use the other searches and create your own launch conditions. That completes our brief tour of the editors that you can use to modify the resulting Windows Installer package to suit your needs. Although you have looked only briefly at the functionality of the editors, you have seen that they are extremely powerful, and worth investment of your time for further investigation.

Whenever an assembly in the application download cache is needed, the .NET Framework automatically checks for a new version in the appropriate directory on the web server. Thus, the application can be updated for all client machines by simply placing an assembly on the web server.

One drawback of this technique for deploying the application is that it can be launched only from a Web page or some other means of accessing a URL (such as a shortcut or the Start

To get around this limitation, you can get a similar deployment capability by using a small launching application that uses dynamic loading to start the main application. Dynamic loading was discussed in the previous chapter. In this case, the location for the assembly used in dynamic loading will be the URL of the assembly on the web server. An application that uses this technique still gets all the trickle feeding and auto-update features of an application launched straight from a URL.

No-touch deployment is useful for simple applications, but it has some serious drawbacks for more complex applications:

Given the limitations of no-touch deployment, in the 2.0 version of the .NET Framework Microsoft added an alternative called ClickOnce. It is essentially a complete replacement for no-touch deployment. Thus, while no-touch deployment is still supported in .NET Framework 2.0 and higher, it is no longer recommended for use and is not covered here.

For a simple case, no special work is needed to prepare a typical Windows application to be deployed via ClickOnce. Unlike the deployment options discussed earlier, it is not necessary to add additional projects to the solution. If you use standard options in ClickOnce, then it is also unnecessary to add any custom logic to your application. All of the work to enable ClickOnce deployment for an application can be performed by selecting options in the IDE.

It is possible to control the ClickOnce deployment by writing your own custom logic controlling the ClickOnce deployment processes, but that capability is beyond the scope of this book and is not covered here. Instead, this chapter explains the basic configuration of ClickOnce and common options that don't require you to write any code.

Applications installed via ClickOnce are one of two types:

Online applications must be launched with a URL (Uniform Resource Locator), a standard filename, or a UNC (Universal Naming Convention) filename. This may be done in various ways, such as clicking a link in a Web page, typing a URL into the Address text box of a browser, typing a filename into the Address text box of Windows Explorer, or selecting a shortcut on the local machine that contains the URL or filename. However, ClickOnce does not automatically add any such mechanisms to a user's machine to access the application. That is up to you.

Offline applications can also be launched with a URL or UNC, and are always launched that way the first time. The differences are as follows:

A deployment walk-through for a simple Windows application will demonstrate the basics of ClickOnce. This first walk-through deploys an online application to a web server, which is one of the simpler user scenarios for ClickOnce.

First, create a simple Windows Application in Visual Studio, and name it SimpleApp. On the blank Form1 that is created as part of the application, place a single button.

To enable ClickOnce deployment, access the Build menu and select the Publish SimpleApp option. The ClickOnce Publish Wizard will appear. The first screen of the wizard is shown in Figure 24-15.

Figure 24.15. Figure 24-15

The location defaults to a local web server if you have one, but as discussed earlier, deployment can be done on a remote website, a network share, or even a local directory. You should change the location if the default is not appropriate for your circumstances. Once you've verified the location to publish to, click Next.

Select one of the two types of ClickOnce applications discussed earlier. Because this example is for an online application, click the second option to make the application available online only, as shown in Figure 24-16.

Figure 24.16. Figure 24-16

Click Next to see a summary of your selections, and then click Finish. The ClickOnce deployment process will begin. A new item will be added to your project called "SimpleApp_TemporaryKey.pfx," a complete build will be done, a new virtual directory will be created for the application on the web server, and the files needed to deploy the application will be copied to that virtual directory. (The new item is discussed later in the chapter, in the section "Signing the Manifest.")

When the process is complete, a Web page will be generated that contains the link needed to deploy the application. The Web page has a Run button that activates the link. If you click this button, the application will be deployed by ClickOnce. (You may wish to view the source for this Web page to obtain the HTML needed to launch the application from your own Web pages.)

First, the prerequisites for the application are verified. In this case, that just means the .NET Framework. If the website is remote, then you will see a Security Warning dialog much like you would get if you attempted to download a file, and you'll need to select the Run option.

Next, an Application Run - Security Warning dialog is displayed, asking if it is acceptable to run the application, as shown in Figure 24-17. You can run the application by selecting the Run button, or select Don't Run, which aborts the process. For now, select Run, and after a short delay you will see the application's form appear.

If you now make any changes to the SimpleApp application, you must publish the application again to make the changes available via ClickOnce. You can do that by stepping through the Publish Wizard once again. More details about automatic updating of ClickOnce applications are provided later in this chapter in the section "The Update Process."

Figure 24.17. Figure 24-17

In the second screen of the Publish Wizard, if you select the first option, then the installation process has some differences:

The virtual directory used by ClickOnce to deploy your application contains a number of files for different aspects of the deployment. Figure 24-18 shows what the directory for SimpleApp looks like after ClickOnce has finished copying all needed files.

Figure 24.18. Figure 24-18

The virtual directory contains a folder for the first version of SimpleApp, which by default is version 1.0.0.0. It also contains the Web page that was displayed after ClickOnce finished, which is named publish.htm.

The next file is Setup.exe. This is an executable that does not need the .NET Framework to run. It is used during the ClickOnce process for all the activities that must take place before the application is launched. This includes activities such as checking for the presence of the .NET Framework. It is discussed further later in the chapter in the section "The Bootstrapper."

The next file is SimpleApp.application. The ".application" extension is specific to ClickOnce, and indicates the special file called a manifest, introduced in the last chapter. This is an XML-based file that contains all the information needed to deploy the application, such as what files are needed and what options have been chosen. There is also a file named SimpleApp_1_0_0_0.application, which is the manifest specifically associated with version 1.0.0.0.

Each version of the application has its own manifest, and the one named SimpleApp.application (with no embedded version number) is typically the currently active one. (Thus, the link to the application does not need to change when the version number changes.)

Other files associated with a version are in the folder for that version.

Because the manifest controls the update process, it is essential that ClickOnce be assured that the manifest is valid. This is done by signing the manifest, using a public-private key pair. As long as a third party does not have the key pair, that party cannot "spoof" a manifest, preventing any malicious interference in the ClickOnce deployment process.

A key pair is automatically generated when you publish with ClickOnce. However, you can supply your own key pair if you like. Options for signing the application are discussed later in the section "ClickOnce Configuration Options."

Note that your application assemblies do not need to be signed in order for them to be used in a ClickOnce deployment. Only the manifest must be signed. The manifest contains hash codes of all the assemblies involved, and those hash codes are checked before assemblies are used. This prevents malicious third parties from inserting their own versions of your assemblies.

By default, all ClickOnce applications check for updates each time the application is launched. This is done by getting the current version of the manifest and checking whether any changes were made since the last time the application was launched. This process is automatic, so there's nothing you need to do to make it happen, but it's helpful for you to understand the steps that are taken.

For an online application, if a change is detected, then it is immediately applied by downloading any changed files. Then the application is launched. This is conceptually similar to a browser-based application because the user has no option to use an older version.

For an application available offline, if changes are detected, then the user is asked whether the update should be made. The user can choose to decline the update. A configuration option enables you to specify a minimum version number, and that can force a user to accept an update. You will look at ClickOnce configuration options later.

If an update is made for an offline application, then the previous version is kept. The user can then roll back to that version using the Add/Remove Programs option in the control panel. A user can also uninstall the ClickOnce-deployed application from that same location.

Only one previous version is kept. Older versions are removed when a new version is installed, so the only versions available at any point in time are the current version and the one immediately before it. A rollback can be made to the immediately preceding version, but not to any earlier versions.

You can control the update process by including code in your application that detects when changes have been made and applies the changes as necessary. As previously mentioned, this chapter does not cover writing such logic. You can find samples in the MSDN documentation for this capability.

In Visual Studio 2008, the properties for a Windows Application project include several pages that affect ClickOnce. (You can get to the properties for a project by right-clicking on it in the Solution Explorer and selecting Properties.)

The Signing tab page includes options for signing the ClickOnce manifest. There are buttons to select a particular certificate from a store or a file, or to generate a new test certification for signing. This page also contains an option to sign the assembly that is compiled from the project, but as mentioned previously, this is not necessary for ClickOnce to operate.

The Security tab page provides settings related to the code access security permissions needed by the application to run. Because the application is being deployed from a source other than the local machine, if you use ClickOnce, code access security limitations are in effect, as described in Chapter 12. A typical example of the Security tab page is shown in Figure 24-19.

Figure 24.19. Figure 24-19

Using the options on the Security tab page, you can calculate the permissions needed by the application, using the Calculate Permissions button. You can also arrange to test your application against a particular set of permissions. To do that, change from the default option "This is a full trust application" to the option immediately below it, labeled "This is a partial trust application." Then select the zone from which the application will be installed. When the application is run by Visual Studio, permission for that zone will be enforced.

All of the other ClickOnce configuration options are on the Publish tab, shown in Figure 24-20.

Figure 24.20. Figure 24-20

You can set many options with the Publish page, but here are some of the most important:

Because applications deployed by ClickOnce are a part of the .NET Framework, the .NET Framework must be available on the user's machine before your application can be installed and run. In addition, your application may require other items, such as a database or COM component, to be installed.

To provide for such needs, ClickOnce includes a bootstrapper that runs as the first step in the ClickOnce process. The bootstrapper is not a .NET program, so it can run on systems that do not yet have the .NET Framework installed. The bootstrapper is contained in a program called Setup.exe, which is included by ClickOnce as part of the publishing process.

When setup.exe runs, it checks for the prerequisites needed by the application, as specified in the Prerequisites options discussed previously. If needed, these options are then downloaded and installed. Only if the user's system contains installed prerequisites does ClickOnce attempt to install and run your Windows application.

The MSDN documentation includes more details on configuring and using the ClickOnce bootstrapper.

Sometimes an application manifest created by ClickOnce needs to be manually changed. For example, if the application contains dynamically loaded .NET DLLs (as discussed in the previous chapter), then such DLLs are not automatically included in a ClickOnce manifest.

In creating a manifest for an installation, ClickOnce relies on the compile-time references for the application being deployed. It will place any application assemblies that have compile-time references into the manifest.

However, dynamically loaded assemblies do not have a compile time reference, which means ClickOnce can't put them in the manifest automatically. If you have dynamically loaded assemblies in your Windows Forms application, then you must add them to the manifest manually.

ClickOnce includes a tool for manually editing the manifest. Named MAGE.exe, it can be started from the Visual Studio 2008 command prompt. It offers a UI to open a manifest and perform various manual operations on it. MAGE.exe can also be used from the command line, so you can create batch files or PowerShell scripts to automate insertion of files in a ClickOnce manifest.

How to use MAGE.exe is beyond the scope of this chapter, but the help files for MAGE.exe are extensive, and you can find MSDN samples on using it.

In addition to deploying an application for use, ClickOnce also provides the capability to uninstall or roll back applications that are deployed with the offline option. Such applications will have an entry in the Add/Remove Programs section of the control panel. That entry will offer an uninstall option; and if a rollback version is present, an option to roll back the last update.

Only one level of rollback is available. If multiple updates have occurred, then the user can only roll back to the most recent one. Once a rollback is done, no further rollback is possible until another update has been deployed.

ClickOnce is a complete replacement for no-touch deployment. However, there are other deployment scenarios for which ClickOnce may not be the ideal solution. For example, ClickOnce can deploy only a per-user installation. It cannot install an application once to be used by all users on the system.

ClickOnce may be used in combination with technologies such as the Windows Installer. If you create .msi files, as discussed earlier in the chapter, you may include them as part of ClickOnce's bootstrapper process. This is an advanced technique not discussed in this book, but you can learn more about this capability in the MSDN documentation.

For cases in which ClickOnce is not appropriate, you may wish to use more customized deployment technologies, which are discussed next.

Rather than start from scratch on such a deployment/installation technology, you can look at starting points such as the Updater Application Block. Created by Microsoft's Patterns and Practices Group, the Updater Application Block can be downloaded from Microsoft's website. It includes manifest-based checking of modules for updating, and background transfer of new modules using the same transfer technology as Windows Update.

You can use the Updater Application Block as is, or customize it for your own needs. For example, you could create a version that enables different classes of users to have different update strategies, so that new updates are sent to a select group of users first.