Modifying the Deployment Project

The previous walk-through created a default Windows Installer package for a particular project template. You didn’t customize the steps or actions that were performed when the package was run. What if you want to add a step to the installation process that displays a ReadMe file to the user? Or what if you need to create registry entries on the installation computer?

This section focuses on additional capabilities for deployment projects. Most of these capabilities are accessed by using a series of “editors” for changing parts of the deployment project. Six editors are available for customizing a Windows Installer−based deployment project:

• File System Editor

• Registry Editor

• File Types Editor

• User Interface Editor

• Custom Actions Editor

• Launch Conditions Editor

The editors are accessible through the View Editor menu option or by using the corresponding buttons at the top of Solution Explorer.

You can also modify the resulting Windows Installer package through the project’s Properties window. This section offers a brief look at each of the six editors and the project properties, and shows how they can be used to modify the resulting Windows Installer package. You will use the project created in the Windows application walk-through in this section.

Project Properties

The first step you take in customizing the Windows Installer package is to use the project properties. The project’s Property Pages dialog box is accessed by right-clicking the root of the setup project in Solution Explorer and selecting Properties from the pop-up menu. You can also select the Properties item from the Project menu when the setup project is the active project. Both of these methods bring up the project’s Property Pages dialog box, illustrated in Figure 22-6.

Figure 22-6

The Build Page

The only page on the properties dialog is the Build page. The options on that page can be used to affect the way that the resulting Windows Installer package is built.

As with most other projects in VS 2005, you can create different build configurations. You use the Configuration combo box to select the build configuration for which you want to alter properties. In Figure 22-6, the properties for the currently active build configuration, Debug, are being modified. The button labeled Configuration Manager allows you to add, remove, and edit the build configurations for this project.

The Output file name field can be used to modify where the resulting Windows Installer package (.msi) file will be created. You can modify the filename and path directly or you can browse for a location.

Package Files

The next setting, Package files, enables you to specify how the files that make up the installation are packaged. The following table describes the possible settings:

Open table as spreadsheet

Package	Description
As loose uncom-pressed files	When you build the project, the files that are to be included as part of the installation are copied to the same directory as the resulting Windows Installer package (.msi) file. As mentioned earlier, this directory can be set using the Output file name setting.
In setup file	When the project is built, the files that are to be included as part of the installation are packaged in the resulting Windows Installer package file. When you use this method, you only have one file to distribute. This is the default setting.
In cabinet file(s)	With this option, when the project is built, the files that are to be included as part of the installation are packaged into a number of cabinet files.

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 22-7, which is the dialog that is displayed when the Prerequisites button is pressed.

Figure 22-7

The .NET Framework is checked by default. You should only uncheck it if you are sure that all the machines upon which your application will be installed already have the Framework installed.

If the box for any of these prerequisites is checked, 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, 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.

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 will be located. Alternatively, you can select “Download prerequisites from the component vendor’s web site,” which uses the installation URL from the previous dialog (refer to Figure 22-6).

.NET 3.0 applications can only be installed on Windows XP or later. Windows Installer 2.0 is available on all those operating systems, so it is unnecessary to have the Windows Installer 2.0 prerequisite.

Compression

You also have the option to modify the compression used when packaging the files that are to be contained within the installation program. The three options (Optimized for speed, Optimized for size, and None) are self-explanatory and are not covered in this book. The default is Optimized for speed.

Setting the Cabinet File Size

If you want to package the files in cabinet files, then you have the option to specify the size of those resulting cabinet file(s):

• You can let the resulting cabinet file be of unlimited size. What this effectively means is that all the files will be packaged into one big cabinet file. The resulting size of the cabinet file will also be dependent on the compression method selected.

• If you are installing from floppy disks or CDs, creating one large cabinet file may not be appropriate. In this case, you can specify the maximum size of the resulting cabinet file(s). If you select this option, you need to fill in the maximum size that a cabinet file can be (in KB). If all the files that need to be contained within this installation exceed this size, then multiple cabinet files will be created.

The File System Editor

The File System Editor is automatically displayed for you in VS 2005’s document window when you first create the setup project. You can also access this editor and the other editors that are available via the View Editor menu option in the VS 2005 IDE. The File System Editor is used to manage all the file system aspects of the installation:

• Creating folders on the user’s machine

• Adding files to the folders defined

• Creating shortcuts

Basically, this is the editor that you use to define what files need to be installed and where they are installed on the user’s machine. The File System Editor is split into two panes in the document window, as shown in Figure 22-8.

Figure 22-8

The left pane shows a list of the folders that have been created automatically for the project. When you select a folder in the left pane, two things happen: First, the right pane of the editor displays a list of the files that are to be installed into the selected folder; and second, the Properties window changes to show you the properties of the currently selected folder.

Adding Items to a Folder

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 select the required folder and 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:

• Project output

• File

• Assembly

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.

Adding Special Folders

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, then 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). You will be presented with a pop-up menu that has 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, summarized in the following table:

Open table as spreadsheet

Name	Description	Windows Installer Property
Common Files folder	Files (nonsystem) shared by multiple applications are usually installed to this folder.	[CommonFilesFolder]
Common Files folder (64-bit)	Same as Common Files folder, but for 64-bit systems	[CommonFiles64Folder]
Fonts folder	This folder is used to contain all the fonts that are installed on the computer. If your application used a specific font, then you want to install it into this folder.	[FontsFolder]
Program Files folder	Most applications are installed in a directory below the Program Files folder. This acts as root directory for installed applications.	[ProgramFilesFolder]
Program Files folder (64-bit)	Same as Program Files folder, but for 64-bit systems	[ProgramFiles64Folder]
System folder	This folder is used to store shared system files. The folder typically holds files that are part of the OS.	[SystemFolder]
System folder (64-bit)	Same as System folder, but for 64-bit systems.	[System64Folder]
User’s Application Data folder	This folder is used to store data, on a per-application basis, that is specific to a user.	[CommonAppDataFolder]
User’s Desktop folder	This folder represents the user’s desktop. It can be used to create and display an application shortcut, which users can click to start your application.	[DesktopFolder]
User’s Favorites folder	This folder is used as a central place to store links to the user’s favorite websites, documents, folders, and so on.	[FavoritesFolder]
User’s Personal Data folder	This is where a user stores important files. It is normally referred to as My Documents.	[PersonalFolder]
User’s Programs Menu	This is where shortcuts are created to applications that appear on the user’s Program menu. This is an ideal place to create a shortcut to your application.	[ProgramMenuFolder]
User’s Send To Menu	This folder stores all the user’s “Send To” shortcuts. A Send To shortcut is displayed when you right-click a file in the Windows Explorer and choose Send To. The Send To shortcut usually invokes an application by passing in the pathname of the files from which it was invoked.	[SendToFolder]
User’s Start Menu	This folder can be used to add items to the user’s Start menu. This is not often used.	[StartMenuFolder]
User’s Startup folder	This folder is used to start applications whenever the user logs in to the computer. If you want your application to start every time the user logs in, then you can add a shortcut to your application in this folder.	[StartupFolder]
User’s Template folder	This folder contains templates specific to the logged-in user. Templates are usually used by applications such as Microsoft Office 2000.	[TemplateFolder]
Windows folder	The Windows root folder. This is where the OS is installed.	[WindowsFolder]
Global Assembly Cache folder	This folder is used to store all the shared assemblies on the user’s computer.

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 name of the folder is in edit mode, so type in the name and press Enter. The folder will now be selected, and the Properties window will have changed to show the properties of the new folder. The properties of a folder are summarized in the following table:

Open table as spreadsheet

Property	Description
(Name)	This is the name of the selected folder. The Name property is used within the setup project as the means by which you select a folder.
AlwaysCreate	This property is used to indicate whether this folder should be created on installation even if it’s empty (True). If the value is False and there are no files to be installed into the folder, then the folder will not be created. The default is False.
Condition	This enables you to enter a condition that will be evaluated when the installation is run. If the condition evaluates to True, then the folder will be created; if the condition evaluates to False, then the folder won’t be created.
DefaultLocation	This is where you define where the folder is going to be created on the target machine. You can enter a literal folder name (such as C:\Temp), use a Windows Installer property, or use a combination of the two. A Windows Installer property contains information that is filled in when the installer is run. In the last table of special folders is a column called Windows Installer property. The property defined in this table is filled in with the actual location of the special folder at runtime. Therefore, if you enter [WindowsFolder] as the text for this property, the folder created represents the Windows special folder.
Property	This property is used to define a Windows Installer property that can be used to override the DefaultLocation property of the folder when the installation is run.
Transitive	This property indicates whether the condition specified in the Condition property is reevaluated on subsequent (re)installs. If the value is True, then the condition is checked on each additional run of the installation. A value of False causes the condition to be run only the first time the installation is run on the computer. The default value is False.

Suppose you name your folder “Wrox Press” and set the DefaultLocation property for your folder to [FavoritesFolder]\Wrox Press. You could now 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 favorite folder called Wrox Press, and those shortcuts will be placed in it.

Creating Shortcuts

The first step in creating a shortcut is to locate the file that is to be 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 will be 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 will probably want to rename the shortcut, which can be easily done via the Rename option of the pop-up menu.

You have only taken a brief look at the File System Editor. There are many additional capabilities you can explore.

The Registry Editor

The next editor that you are going to look at is the Registry Editor, which can be used for the following:

• Create registry keys

• Create values for registry keys

• Import a registry file

Like the File System Editor, the Registry Editor is split into two panes, as illustrated in Figure 22-9.

Figure 22-9

The left pane of the editor represents the registry keys on the target computer. When you select a registry key, two things happen: the right pane of the editor is updated to show the values that are to be created under the selected registry key, and if the registry key selected is not a root key in the left pane, the Properties window will be updated with a set of properties for this registry key.

When you create a new deployment project, a set of registry keys will be created for you that correspond to the standard base registry keys of Windows. Notice in Figure 22-9 that there is a key defined with a name of [Manufacturer]. When the installation is run, this is replaced with the value of the Manufacturer property described earlier in the chapter. [Manufacturer] is a property of the installation and can be used elsewhere within the installation. Several of these properties are defined that can be used in much the same way (consult the “Property Reference” topic in the MSDN documentation for a full list).

Adding a Value to a Registry Key

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

• Right-click the registry key and use the resulting pop-up menu.

• Right-click in the right-hand pane and use the resulting pop-up menu.

• Use the Action menu.

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

• Key

• String value

• Environment string value

• Binary value

• DWORD value

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 the 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_USER\Software [Manufacturer].

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

Create a value that is applicable to only this application and not all applications created by you. To do so, create a new registry key below the HKEY>\_CURRENT>\_USER\ Software\[Manufacturer] key that is specific to this product (select the Action New@ Key menu item).

When the key is created, the key name will be 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 New menu and give the new value a name of Debug.

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, the Windows Installer package will overwrite the existing value with that defined in the Registry Editor.

You can move most keys and values in the Registry Editor around 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, note 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.

Importing Registry Files

If you already have a registry file that contains the registry settings that you would like to be created, then you can import the file into the Registry Editor. To import a registry file, you need to make sure 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.

Tip 

Registry manipulation should be used with extreme caution. Windows relies heavily on the registry, and you can cause yourself a great number of problems if you delete, overwrite, or change registry values and keys without knowing the full consequences of the action.

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

The File Types Editor

The File Types Editor can be used to create the required registry entries to establish a file association for the application being installed. A file association is simply a link between a particular file extension and a particular application. For example, the file extension .doc is normally associated with Microsoft WordPad or Microsoft Word.

When you create a file association, not only do you create a link between the file extension and the application, but you also define a set of actions that can be performed from the context menu of the file with the associated extension. For example, if you right-click a document with an extension of .doc, you get a context menu that can contain any number of actions - for example, Open and Print. The action in bold (Open, by default) is the default action to be called when you double-click the file, so in the example, double-clicking a Word document will start Microsoft Word and load the selected document.

Let’s walk through the creation of a file extension for the application. Suppose that the application uses a file extension of .set and the file is to be opened in the application when it is double-clicked. Start the File Types editor, which contains a single pane. In a new deployment project, this pane will only contain a root node called “File Types on Target Machine.”

To add a new file type, you need to make sure the root element is selected in the editor. You can then choose Add File Type from the Action menu, or right-click on the root node and select Add File Type. Give the new file type the name “Example File Type.”

Next, you must set the extension and application for this file type. Use the Properties window (shown in Figure 22-10). Enter .set as the value for the Extensions property.

Figure 22-10

To associate an application with this file type, you need to use the Command property. The ellipsis button for this property presents you with a dialog box in which you can select an executable file contained within any of the folders defined in the File System Editor. In this case, you select Primary Output from WindowsApplication (active) from the Application Folder as the value for Command.

When this new file type was first created, a default action was added for you called &Open - select it. Now take a look at the Properties window again. Notice the Arguments property: You can use this to add command-line arguments to the application defined in the last step. In the case of the default action that has been added for you, the arguments are “%1”, where the value “%1” will be replaced by the filename that invoked the action. You can add your own hard-coded arguments (such as /d). An action is set to be the default by right-clicking it and selecting Set as Default from the pop-up menu.

The User Interface Editor

The User Interface Editor, shown in Figure 22-11, is used to manage the interface that is shown during the installation of the application. The editor enables you to define the dialog boxes that are displayed to the user and in what order they are shown.

Figure 22-11

The editor uses a tree view with two root nodes: Install and Administrative Install. Below each of these nodes are three nodes that represent the stages of installation: Start, Progress, and End. Each of the three stages can contain a number of dialog boxes that are displayed to the user when the resulting Windows Installer package is run. A default set of dialog boxes is predefined when you create the deployment project. The default dialog boxes that are present depend on the type of deployment project: Setup Project or Web Setup Project. Figure 22-11 shows the dialog boxes that were added by default to a Setup Project. However, if you are creating a Web Setup Project, the Installation Folder dialog box will be replaced by an Installation Address dialog box.

Using Figure 22-11, the following section discusses the two modes in which the installer can be run, and the three stages of the installation.

Installation Modes

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.

Tip 

To use the Administrative Install mode of the resulting Windows Installer package, you can use msiexec.exe with a command-line parameter, e.g.,

 msiexec.exe /a <PACKAGE>.msi

Install mode is most frequently used and is what you will use in this example. As mentioned earlier, the steps the installation goes through can be split into three stages and are represented as subnodes of the parent installation mode.

The Start Stage

The Start stage is the first stage of the installation. It contains the dialog boxes that are displayed to the user before the actual installation of the files begins. The Start stage should be used to gather any information from the user that may affect what is installed and where it is installed.

This stage is commonly used to ask the user to select the base installation folder for the application and to indicate what parts of the system should be installed. Another common task at this stage is to ask users their name and organization. At the end of this stage, the Windows Installer service determines how much disk space is required on the target machine and confirms that this amount of space is available. If the space is not available, then the user receives an error and the installation ends.

The Progress Stage

The Progress stage is the second stage of the installer and is where the actual installation of the files occurs. There isn’t usually any user interaction in this stage of installation. Typically, one dialog box indicates the current progress of the installation, which is calculated automatically.

The End Stage

Once the actual installation of the files has finished, the installer moves into the End stage. The most common use of this stage is to inform the user that the installation has been completed successfully. It is often used to provide the option of running the application immediately or to view any release notes.

Customizing the Order of Dialog Boxes

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.

Adding Dialog Boxes

A set of predefined dialog boxes has been added to the project for you, allowing for 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 option to use a built-in dialog box or import one. To illustrate how to add a dialog box, consider an example that adds a dialog box to display a ReadMe file to the user of 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. This example uses 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 that 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 displays the Add Dialog dialog box (see Figure 22-12), where you can choose from the built-in dialog boxes.

Figure 22-12

As shown in Figure 22-12, there are a number of built-in dialog boxes to choose from. Each dialog box has 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 to which they are added, so 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.

Properties of the Dialog Boxes

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. When a dialog box is selected, you will notice that the Properties window varies according to the properties of the selected dialog box. The properties that appear depend on 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.

The Custom Actions Editor

The Custom Actions Editor (see Figure 22-13) is used for fairly advanced installations. It enables you to define actions that are to be performed due to one of the following installation events: Install, Commit, Rollback, and Uninstall. For example, you can use this editor to define an action that creates a new database when the installation is committed.

Figure 22-13

The custom actions that are added using this editor can be Windows script-based, compiled executables, or DLLs.

Load this editor by right-clicking on the Setup1 project and selecting View Custom Actions. The editor uses a tree view to represent the information. The four nodes in the tree view represent each of the four installation events to which you can add custom actions, as shown in Figure 22-13.

As with the User Interface Editor, the order in which the actions appear determines the order in which they are run, and this can be modified simply by dragging and dropping the actions or by using the context menus of the actions to move them up or down.

Adding a Custom Action

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 that are defined in the editor are described in the following table:

Open table as spreadsheet

Event	Description
Install	The actions defined for this event are run when the installation of the files has finished, but before the installation has been committed.
Commit	The actions defined for this event are run when the installation has been committed and has therefore been successful.
Rollback	The actions defined for this event are run when the installation fails and rolls back the machine to the state it was in before the install was started.
Uninstall	The actions defined for this event are run when the application is being uninstalled from the machine.

Suppose you wanted 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 is run when the installation has been successful. Make sure that this node is selected in the editor. You are now ready to add the actual action you would like to happen when the Commit event is called. Using the Action menu again, select the Add Custom Action menu item, which displays 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. In 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. The following table describes some of the ones you are most likely to need:

Open table as spreadsheet

Property	Description
(Name)	This is the name given to the selected custom action.
Arguments	This property enables you to pass command-line arguments into the executable that makes up the custom action. This only applies to custom actions that are implemented in executable files (.exe). By default, the first argument passed in indicates what event caused the action to run. It can have the following values: /Install /Commit /Rollback /Uninstall
Condition	This enables you to enter a condition that will be evaluated before the custom action is run. If the condition evaluates to True, then the custom action will run; if the condition evaluates to False, then the custom action will not run.
CustomActionData	This property enables you to pass additional information to the custom action.
InstallerClass	If the custom action is implemented by an Installer class in the selected component, then this property must be set to True. If not, then it must be set to False. (consult the MSDN documentation for more information on the Installer class, which is used to create special installers for such .NET applications as Windows Services. The Installer class is located in the System.Configuration.Install namespace)

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 automatically starts. 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.

The Launch Conditions Editor

The Launch Conditions Editor can be used to define a number of conditions for the target machine that must be met before the installation will run. For example, if your application relies on the fact that the user has Microsoft Word 2000 installed on his or her machine in order to run your application, you can define a launch condition that checks this.

You can define a number of searches that can be performed to help create launch conditions:

• File search

• Registry search

• Windows Installer search

As with the Custom Actions Editor, the Launch Conditions Editor (shown in Figure 22-14) uses a tree view to display the information contained within it. The example shows a Custom Actions Editor that has had an item added. The steps for adding that item are covered later.

Figure 22-14

There are two root nodes. The first (Search Target Machine) is used to display the searches that have been defined. The second (Launch Conditions) contains a list of the conditions that will be evaluated when the Windows Installer package is run on the target machine.

As with many of the other editors, the order in which the items appear below these two nodes determines the order in which the searches are run and the order in which the conditions are evaluated. If you wish, you can modify the order of the items in the same manner as previous editors.

Tip 

The searches are run and then the conditions are evaluated as soon as the Windows Installer package is run, before any dialog boxes are shown to the user.

Let’s look at an example of adding a file search and launch condition to a setup project. For argument’s sake, let’s say that you want to ensure that your users have Microsoft Word 2003 installed on their machine before they are allowed to run the installation for your application.

Adding a File Search

To add a file search, you begin by searching for the Microsoft Word 2003 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 Word2003Search. The result is shown in Figure 22-14.

Modifying the File Search Properties

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 are 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 2003 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 need to search for the Microsoft Word 2003 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 a number of these built-in values; if you are interested, you can see what these folders correspond to in the “Adding Special Folders” section.

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 only searches 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 sub-folders the search will look in from the starting folder specified for the file in question.

Note some performance issues relating to the Depth property. If a search is performed for a file that is very deep in the file system hierarchy, 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 for it to be found - for example, minimum version number or minimum file size.

You are searching for the existence of Microsoft Word 2003; this 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, enter 11.0.0.0 as the value for the MinVersion property. This ensures that the user has Microsoft Word 2003 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 this example, enter WORDEXISTS as the value for the Property property. If the file search is successful, 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 as shown in Figure 22-15.

Figure 22-15

Creating a Launch Condition

A file search alone is pretty useless. The second step of the process of ensuring that the user has Microsoft Word 2003 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 (see Figure 22-16), give it the name Word2003Exists.

Figure 22-16

This new item has a number of properties 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.

The next property that you need to change is called Condition, and it is used to define a valid deployment condition that is to be 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 nonempty 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 the preceding discussion of this search enables you to use the other searches and create your own launch conditions. That completes our brief look at the editors you can use to modify the resulting Windows Installer package to suit your needs. Although this has been only a brief overview of the functionality of the editors, they are extremely powerful, and worth investment of your time for further investigation.

Building

The final step is to build the deployment or setup project you have created. There is no difference between how you build a Visual Basic .NET application and a deployment/setup project. If the project is the only project contained within the solution, then you can just use the Build item from the Build menu, which causes the project to be built. As with the other projects, you are informed of what is happening during the build through the Output window.

The deployment/setup project can also be built as part of a multiproject solution. If the Build Solution item is chosen from the Build menu, then all the projects in the solution are built. Any deployment or setup projects are built last. This ensures that if they contain the output from another project in the solution, they get the latest build of that project.