Setup Projects

You can add a setup project to a solution to create a Microsoft Installer application for your solution. Setup projects are highly configurable and allow you to create directories on the target computer, copy files, modify the registry, and execute custom actions during installation. When compiled, a setup project produces an .msi file, which incorporates a setup wizard for the application. The .msi file can be distributed by disk, download, or file share. When clicked, the .msi file will launch the application setup wizard and install the application.

► To add a setup project to your solution

1. From the File menu, choose Add and then New Project to open the Add New Project dialog box.

2. In the Project Types pane, expand Other Project Types and then click Setup And Deployment.

3. In the Templates pane, click Setup Project and then click OK.

Setup Project Editors

Each setup project includes six editors that allow you to configure the contents and the behavior of the setup project. These editors are:

■ File System Editor Allows you to configure the installation of your application to the file system of the target computer.

■ Registry Editor Allows you to write entries to the registry upon installation.

■ File Types Editor Allows you to set associations between applications and file types.

■ User Interface Editor Allows you to edit the user interface seen during installation for both regular installation and administrative installation.

■ Custom Actions Editor Allows you to define custom actions to be performed during installation.

■ Launch Conditions Editor Allows you to set conditions for launching the installation of your setup project.

Adding Files to a Setup Project with the File System Editor

The File System Editor represents the file system on the target computer. You can add output files to various directories, create new directories on the target computer, or create and add shortcuts to the target computer. Figure 15-4 shows the File System Editor.

Figure 15-4 The File System Editor

The File System Editor is split into two panes. The left pane represents the directory structure of the target computer. Each folder in the left pane represents a folder on the target computer that exists or will be created by the setup application. The right pane displays the contents of the directory that is selected in the left pane. Initially, the File System Editor consists of three folders: the Application Folder, the User's Desktop, and the User's Program Menu. You can change the folder for a particular file by selecting the file in the right pane and dragging it to the appropriate folder.

You can add additional folders to the File System Editor by right-clicking the left pane and choosing Add Special Folder. The shortcut menu pictured in Figure 15-5 appears. Using this menu, you can add a special folder to the File System Editor or create your own custom folder. If you choose a custom folder, this folder will be created in the target computer's file system upon installation.

Common Files Folder

Common Files (64-bit) Folder

Fonts Folder

Program Files Folder

Program Files (64-bit) Folder

System Folder

System (64-bit) Folder

User's Application Data Folder

User's Desktop

User's Favorites Folder

User's Personal Data Folder

User's Programs Menu

User's Send To Menu

User's Start Menu

User's Startup Folder

User's Template Folder

Windows Folder

Global Assembly Cache Folder

Custom Folder

Figure 15-5 The Add Special Folder shortcut menu

► To add output from a project to a deployment project

1. Right-click Application Folder in the left-hand pane of the File System Editor, choose Add, and then choose Project Output. The Add Project Output Group dialog box (pictured in Figure 15-6) opens.

Add Project Output Group


Add Project Output Group



Localized resources

Debug Symbols

Content Files

Source Files

Documentation Files

XML Serialization Assemblies


Configuration: | (Active)



Contains the DLL or EXE built by the project.

Figure 15-6 The Add Project Output Group dialog box

Figure 15-6 The Add Project Output Group dialog box

2. Choose the project outputs that you want to add to your setup project. All .exe and .dll files created by the project are contained in Primary Output. You can also add additional project files to your setup project, such as localized resources, content files, or documentation files, or, less frequently, debug symbols, source files, or XML serialization assemblies. Once you have selected the output to be added to the folder, click OK.

► To create a shortcut and add it to the target computer

1. In the right-hand pane of the File System Editor, right-click the file for which you want to create a shortcut and choose Create Shortcut. A shortcut to the file is created and added to the pane.

2. Drag the shortcut from the right-hand pane to the appropriate folder in the left-hand pane.

Configuring the Setup Project to Add an Icon During Setup

You can use the File System Editor to associate an icon with your application at install.

Shortcuts to your application will be displayed with the icon you specify.

► To associate an icon with an application at setup

1. In the File System Editor, right-click a folder and choose Add and then select File. The Add Files dialog box opens.

2. Browse to the .ico file you want to associate with a shortcut and click Add to add it to your setup project.

3. Create a shortcut to your application as previously described.

4. In the File System Editor, select the shortcut.

5. In the Properties window, select the Icon property and then choose (Browse...). Browse to the icon you want to associate with your application.

6. Select the icon and click OK.

Configuring Conditional Installation Based on the Operating System Version

You can use the system property VersionNT to determine the operating system at install time. This allows you to create install conditions that allow the installation to proceed or abort based on the operating system.

The VersionNT property is an integer that is calculated by the following formula: MajorVersion * 100 + MinorVersion. Thus, Microsoft Windows 2000 would report a VersionNT value of 500 or greater, based on the minor version.

► To configure conditional installation based on the operating system version

1. In the File System Editor, select the file that contains the primary output for the application.

2. In the Properties window, select the Condition property and type a condition that evaluates the operating system based on the formula previously described. For example, if you want to restrict installation to Windows 2000 or later, you would type a condition that read VersionNT>=500.

Setting Setup Project Properties

The setup project properties provide information about your project and set actions relating to versions of your project. The setup project properties are set in the Properties window. Many setup project properties can provide descriptive information about your application. These properties include:

■ AddRemoveProgramsIcon Specifies an icon for the Add/Remove Programs dialog box on the client computer.

■ Author Contains information about the author of the program.

■ Description Contains a description of the application.

■ Keywords Contains keywords to be associated with the application.

■ Localization Provides the locale information for the application.

■ Manufacturer Contains information about the manufacturer of the application. Is commonly used to define the default install folder within the Program Files folder.

■ ManufacturerURL Contains the URL of the manufacturer's Web site.

■ ProductName Contains the name of the product.

■ Subject Contains information about the subject of the application.

■ SupportPhone Provides a phone number for support for the application.

■ SupportURL Contains a URL for support for the application.

■ TargetPlatform Specifies the target platform of the installer: x86, x64, or Itanium.

■ Title Contains the title of the application.

Other properties of the setup project are used to determine the behavior of the setup project at install time. These properties include:

■ DetectNewerInstalledVersion Looks for a more recent version of the application on the target computer and aborts the installation if one is found.

■ InstallAllUsers Specifies whether the package is installed for all users or for only the installing user.

■ PostBuildEvent Specifies a command line that is executed after the build ends.

■ PreBuildEvent Specifies a command line that is executed before the build begins.

■ RemovePreviousVersion Looks for earlier versions of the application and unin-stalls them in favor of the new version if one is found.

■ RunPostBuildEvent Specifies the condition under which the post-build event runs. The value is either On Successful Build or Always.

■ SearchPath Specifies the path that is used to search for assemblies, files, or merge modules on the development computer.

■ Version Holds the information used by the previous two properties to determine versioning.

There are two additional properties: ProductCode and UpgradeCode. These are used by the setup program and should never be altered manually.

You can change these properties at design time by selecting the project in Solution Explorer and altering the appropriate property in the Properties window.

Configuring a Deployment Project to Deploy the .NET Framework

All applications created with Visual Studio 2005 require.NET Framework 2.0 to run. If you are uncertain of the deployment environment for your applications, you can configure your setup project to install prerequisites such as the .NET Framework as part of the installation. The .NET Framework is configured to be installed by default, but the following procedure allows you to verify that this configuration is still valid.

► To configure a deployment project to deploy the .NET Framework

1. In Solution Explorer, select the deployment project.

2. From the Project menu, click Properties. The Property Pages dialog box opens.

3. In the Properties dialog box, click Prerequisites to open the Prerequisites dialog box.

4. If it is not already selected, select the check box labeled Create Setup Program To Install Prerequisite Components.

5. In the Choose Which Prerequisites To Install list, select the check box labeled .NET Framework 2.0.

6. In the group labeled Specify The Install Location For Prerequisites, select the radio button labeled Download Prerequisites From The Component Vendor's Web Site.

7. Click OK, and then click OK again in the Property Pages dialog box. Custom Actions

Custom actions are an advanced installation technology. With the Custom Actions Editor, you can configure code to be executed during installation. Custom action code must be contained in an Installer class. You can use custom actions to execute code upon four Installer events: Install, Commit, Rollback, or Uninstall. Install actions occur after the files have been installed but before the installation has been committed. Commit actions occur when an installation is committed on the target machine. Rollback actions are executed when an installation fails and is rolled back, and Uninstall actions are executed when an application is being uninstalled. You can use the Custom Actions Editor, shown in Figure 15-7, to associate code with these Windows Installer events.

Figure 15-7 The Custom Actions Editor

Any executable code can be executed as a custom action as long as it is contained in an Installer class. (Although, technically, it is possible to configure a custom action in code other than an Installer class, this text will limit discussion of custom actions to Installer classes.) You can add a new custom action in the Custom Action Editor by right-clicking the event in which you want your custom action to run and choosing Add Custom Action from the context menu. This opens the Select Item In Project dialog box, which allows you to select an item in your project to set as a custom action. A new custom action representing the item you selected is added to your setup project.

For the item you select to function as a custom action, it must contain an Installer class. Installer classes expose methods such as Install, Rollback, Uninstall, and Commit that are used by the setup project to execute custom actions. These methods are present in the base Installer class and must be overridden in the Installer class you create to contain a custom action. For example, the following code example demonstrates how to override the Install method of an Installer class:

Public Overrides Sub Install(ByVal stateSaver As System.Collections.IDictionary) MyBase.Instal l(stateSaver)

' Insert code for the custom action here End Sub

public override void Install(System.Collections.IDictionary stateSaver) {

base.Install (stateSaver);

// Insert code for your custom action here

You can write code for any or all of these methods, but code written in an Installer class will not be executed unless the project that contains it has been designated as a Custom Action. Note that the Installer class must be added to the project you want to deploy, not to the setup project itself.

► To add an Installer class to your project

1. In Solution Explorer, select the project that you want to add the Installer class to. Note that this should be the project you want to deploy, not the setup project itself.

2. From the Project menu, select Add New Item and then choose Installer Class in the Add New Item dialog box and click OK.

You can configure the custom action by setting the properties in the Properties window. Custom action properties are shown in Table 15-1.

Table 15-1 Properties of Custom Actions




This is the name of the selected custom action.


Supplies any required command-line arguments to the application represented by the custom action. This property is applicable only when the custom action is implemented as an executable (.exe).


Enters a Boolean statement that will be evaluated before the custom action is executed. If the statement is true, the custom action will execute. If the statement is false, the action will not execute. You can use the Condition property to evaluate properties chosen in custom dialog boxes.

Cus tomActionDa ta

Passes any additional required data to the custom action.


Specifies the name of the method to execute for the custom action. If left blank, the custom action will attempt to execute a method with the same name as the event with which the custom action is associated (for example, Install). This property applies only to custom actions implemented in DLLs and is ignored when the Installer-Class property is set to True.

Lesson 2: Creating Setup Projects for Deployment 681

Table 15-1 Properties of Custom Actions




A Boolean value that represents whether your custom action is implemented in an Installer class. This property must be true if the custom action is implemented in an Installer and false if it is not.


Contains the actual path on the developer's computer to the file that implements the custom action. This property is read-only.

► To create a custom action

1. Write, test, and debug the code for the custom action you want to add to your setup project.

2. Add an Installer class to the solution you want to deploy.

3. Add the code written in step 1 to the appropriate overridden method (e.g., Install, Rollback, Commit, or Uninstall) of the Installer class.

4. From the View menu, choose Editors, Custom Actions Editor.

5. Right-click the installation event that you want to associate with your custom action and choose Add Custom Action. The Select Item In Project window opens.

6. Browse to the file that implements your custom action and select it.

7. In the Properties window, configure the properties of the custom action.

Handling Errors in Custom Actions

Although most errors in deployment are handled by Windows Installer, you must write error-handling code to trap errors in custom actions. Because custom actions are executed code, errors that occur and are not handled can cause unexpected results on installation. Use Try...Catch blocks to catch and correct any errors that can be corrected. If an error occurs that cannot be corrected, such as a missing file, throw a new InstallException. Throwing an InstallException will cause the installation to be rolled back without leaving any lasting effect on the system. The following example demonstrates how to test for the existence of a file and throw a new InstallException if the file is not found.

Dim myInfo As New System.IO.FileInfo("aFile.txt") If Not myInfo.Exists Then

Throw New System.Configuration.Install.InstallExceptionC'File not found") End If

System.IO.Filelnfo mylnfo = new System.IO.FileInfoCaFile.txt'); if(!(myInfo.Exists))

throw new System.Configuration.Insta11.Insta11Exception("Fi1e not found");

Quick Check

1. How can you associate an icon with an application?

2. How can you roll back installation of a setup project in a custom action?

Quick Check Answers

A. You can associate an icon with your application by creating a shortcut in the File System Editor and then setting the shortcut's Icon property to the icon you want to associate with your application. The icon will be automatically added as the shortcut.

B. By throwing an InstallException. Custom actions that encounter unrecoverable errors should throw InstallException to roll back the installation and prevent harm to the system.

Was this article helpful?

0 0

Post a comment