Lesson 2: Creating Setup Projects for Deployment 675 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 sym- bols, 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 cre- ated 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. 676 Chapter 15 Deployment 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 Proper- ties 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. Lesson 2: Creating Setup Projects for Deployment 677 ■ 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: ■ DetectNewerInstalledVer sion 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 deter- mine 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. 678 Chapter 15 Deployment 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 Edi- tor, 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. Roll- back 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 Cus- tom Actions Editor, shown in Figure 15-7, to associate code with these Windows Installer events. Lesson 2: Creating Setup Projects for Deployment 679 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-click- ing 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 cre- ate to contain a custom action. For example, the following code example demon- strates how to override the Install method of an Installer class: ' VB Public Overrides Sub Install(ByVal stateSaver As System.Collections.IDictionary) MyBase.Install(stateSaver) ' Insert code for the custom action here End Sub // C# public override void Install(System.Collections.IDictionary stateSaver) { base.Install(stateSaver); // Insert code for your custom action here } 680 Chapter 15 Deployment 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 win- dow. Custom action properties are shown in Table 15-1. Table 15-1 Properties of Custom Actions Property Description (Name) This is the name of the selected custom action. Arguments Supplies any required command-line arguments to the application represented by the custom action. This prop- erty is applicable only when the custom action is imple- mented as an executable (.exe). Condition 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 prop- erty to evaluate properties chosen in custom dialog boxes. CustomActionData Passes any additional required data to the custom action. EntryPoint Specifies the name of the method to execute for the cus- tom 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 Property Description InstallerClass 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. SourcePath 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 cor- rected. 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 demon- strates how to test for the existence of a file and throw a new InstallException if the file is not found. ' VB Dim myInfo As New System.IO.FileInfo("aFile.txt") If Not myInfo.Exists Then 682 Chapter 15 Deployment Throw New System.Configuration.Install.InstallException("File not found") End If // C# System.IO.FileInfo myInfo = new System.IO.FileInfo("aFile.txt"); if(!(myInfo.Exists)) throw new System.Configuration.Install.InstallException("File 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 automat- ically added as the shortcut. B. By throwing an InstallException. Custom actions that encounter unrecover- able errors should throw InstallException to roll back the installation and prevent harm to the system. Lab: Create a Setup Project In this lab, you will create a setup project for the same application that you installed in Lesson 1, “Deploying Applications with ClickOnce.” You will use the File System Editor to install files to different directories and create a custom action that displays a message box at install time. � Exercise 1: Use the File System Editor and Create a Custom Action 1. From the Code folder on the companion CD, open the partial solution for Chap- ter 15. 2. From the File menu, choose Add and then choose New Project. The Add New Project dialog box opens. 3. Expand Other Project Types, select Setup and Deployment, and then select Setup Project. Click OK. The Setup Project opens to the File System Editor. 4. In the File System Editor, right-click Application Folder, choose Add, and then choose Project Output. Lesson 2: Creating Setup Projects for Deployment 683 5. In the File System Editor, right-click the left-hand pane, choose Add Special Folder, and then choose Custom Folder to add a custom folder. 6. In the Add Project Output Group dialog box, select your project and choose Pri- mary Output. Click OK. 7. In the File System Editor, select Custom Folder #1. In the Properties window, set the DefaultLocation property to C:\. 8. In the File System Editor, right-click Custom Folder #1, choose Add, and then choose File. Browse to the folder that contains your partial solution and select myFile.txt. Click Open. 9. In Solution Explorer, select your application project (Chapter15BothLabsVB- Partial or Chapter15BothLabsCSPartial). 10. From the Project menu, choose Add New Item. In the Add New Item dialog box, select Installer Class. Then click Add. 11. In the Code Editor, add the following code to override the Install method of the Installer class. ' VB Public Overrides Sub Install(ByVal stateSaver As System.Collections.IDictionary) MyBase.Install(stateSaver) MsgBox("Install custom action executed") End Sub // C# public override void Install(System.Collections.IDictionary stateSaver) { base.Install(stateSaver); System.Windows.Forms.MessageBox.Show("Install custom action executed"); } 12. In Solution Explorer, right-click Installer1 and select View Code to open the Code Editor. 13. In Solution Explorer, right-click Setup1, choose View, and then choose Custom Actions. 14. In the Custom Actions Editor, right-click Install and choose Add Custom Action to open the Select Item In Project dialog box. 15. In the Select Item In Project dialog box, double-click Application Folder and select Primary Output from [application], where [application] is the project that contains your Installer class. 684 Chapter 15 Deployment 16. From the Build menu, choose Configuration Manager. Make certain that both projects are selected in the Build column and click Close. 17. From the Build menu, choose Build Solution to build your solution. 18. Close Visual Studio. In Windows Explorer, navigate to your solution folder. 19. Open the Setup1\Debug folder and double-click Setup1 to install your applica- tion. Follow the instructions in the wizard. Note that a message box appears when the custom action is executed. 20. Navigate to the folder in which you installed your application and double-click your application. It opens and runs. Lesson Summary ■ Setup projects allow you to create Windows Installer applications that you can use to install your solutions. Windows Installer projects are highly configurable and allow a great deal of control over the configuration of the install process. ■ Setup projects provide several editors that allow you to edit aspects of the install process, including the File System Editor, the Registry Editor, the File Types Edi- tor, the User Interface Editor, the Custom Actions Editor, and the Launch Con- ditions editor. ■ The File System Editor is used to add output from your projects and other files to your setup project. The File System Editor can create directories on the target system and can install files to those directories. You can also use the File System Editor to install shortcuts and associate icons with your application and install files conditionally, based on the operating system. ■ The setup project has several properties that expose descriptive information about the application and affect the behavior of the setup project at install time. You can change these properties by selecting the setup project and changing them in the Properties window. ■ Custom actions are code that is executed at install time or uninstall time. You can create a custom action by writing custom code in an Installer class, adding the Installer class to the project that you want to create a setup application for, and then, finally, designating the project that exposes the custom action in the Custom Actions Editor. ■ When errors that are unrecoverable occur in a custom action, you should throw an InstallException to roll back installation without damaging the target system. . Editor 2. Which of the following is an appropriate install condition if you want to restrict installation to Windows 20 00 or later? A. VersionNT= 500 B. VersionNT>= 500 C. VersionNT<= 500 D calculated by the following formula: MajorVersion * 100 + MinorVersion. Thus, Microsoft Windows 20 00 would report a VersionNT value of 500 or greater, based on the minor version. � To configure. For example, if you want to restrict installation to Windows 20 00 or later, you would type a condition that read VersionNT>= 500 . Setting Setup Project Properties The setup project properties