Lesson 2: Configuring Your Setup Project

Lesson 2: Configuring Your Setup Project

Windows Installer setup projects are highly configurable. You can specify locations for files on target computers, create file associations, check for preexisting conditions, or execute custom actions. In this lesson, you will learn how to create a fully configured Windows Installer setup application.

After this lesson, you will be able to

• Explain how to use the Setup Project properties to provide information about your application

• Describe how to configure the directory structure of the deployed application with the File System Editor

• Explain how to create registry keys upon installation with the Registry Editor

• Explain how to create file associations with the File Types Editor

• Describe how to edit the deployment user interface with the User Interface Editor

• Explain how to create a custom action for your setup project

• Describe how to specify a launch condition for your setup project

• Explain how to use Ngen.exe to create a native image of your application on the client machine

• Describe how to verify the security policies for an installed application

Estimated lesson time: 45 minutes

You can create, compile, and distribute a setup project using only what you learned in Lesson 1 of this chapter. For many applications, this will be adequate. For most applications, however, you will want to provide some degree of customization for your setup project. A series of editors in Visual Studio .NET allow you to set installation properties and actions to be taken by the setup program. After your application is installed, you can use command-line utilities to create a precompiled image of your application in the native image cache and to verify the security policies for an installed application.

Setting the 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. Note that this is the Properties window in the IDE, not the Properties page covered in Lesson 1. 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

• 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

• 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

• DetectNewerInstall.

  The setup project looks for a more recent version of the application on the target computer and aborts the installation if one is found.

• RemovePreviousVersion.

  The setup project looks for earlier versions of the application and uninstalls them in favor of the new version if one is found.

• Version.

  This property 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.

These properties are editable in the Properties window at design time. You can also set properties for individual files in your setup project.

Registering Components at Installation

If your setup project includes a font, COM component, or any other component that requires registration, you can register it upon installation by setting the file s Register property in the Properties window. The possible settings for this property are

• vsdrpDoNotRegister.

  Indicates that this object requires no registration

• vsdrpCOM.

  Indicates that this object will be registered as a COM object

• vsdrpCOMRelativePath.

  Indicates that this object will be registered as an isolated COM object

• vsdrpCOMSelfReg.

  Indicates that this item will be self-registered as a COM object when installed

• vsdrpFont.

  Indicates that this item will be registered as a Font upon installation

Note that some of these options might be unavailable for some component types. No registration is required for .NET assemblies and components, so the Register property for these elements should be set to vsdrpDoNotRegister. Fonts should be set to vsdrpFont, and COM files with OleSelfRegister in their version information will default to vsdrpCOMSelfReg.

To register a component upon installation

In Solution Explorer, select your component. In the Properties window, set the Register property to the appropriate value.

The Installation Editors

Visual Studio .NET provides six installation editors that allow you to impart a high degree of configuration to your setup project. The 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

File System Editor

The File System Editor is used to manipulate the file system on the target computer. You can add output files to various directories, create new directories on the target machine, or create and add shortcuts to the target machine. You can access the File System Editor by selecting your setup project in Solution Explorer and choosing View, Editor, File System Editor.

The File System Editor window is split into two panes, as shown in Figure 10.8.

Figure 10-8. The File System Editor.

The right pane of the File System Editor lists all the output files in your setup project. The left pane represents the directory structure of the target computer. Initially, the File System Editor consists of three folders: the Application Folder, the User s Desktop, and the User s Program Menu. By default, the output files are initially stored in the Application Folder. 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 10.9 appears.

Figure 10-9. The Add Special Folder shortcut menu.

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.

Adding a Loose File to Your Setup Application Using the File System Editor

You can use the File System Editor to add loose files and assemblies to your setup project. These files will be incorporated into the setup project and installed upon execution of the setup project, but they will not be compressed and packaged with the rest of the project output.

To add a loose file or assembly to your setup project

1. If the folder to which you want your file to be added is not present in the left pane of the File System Editor, right-click the left pane and choose the appropriate folder from the shortcut menu. You can also create subfolders under existing folders by right-clicking on an existing folder and choosing Add, Folder.

2. In the left pane of the File System Editor, right-click the folder to which you want the file to be added upon installation and choose File. If you are adding an assembly, choose Assembly.

3. Browse to the item you want to add and select it. Click OK (for assemblies) or Open (for files). The file or assembly is added to your setup project and will be installed to the specified folder at installation.

Installing an Assembly to the Global Assembly Cache upon Installation

You can use the File System Editor to install an assembly to the Global Assembly Cache upon installation. To do so, the assembly must be incorporated in the setup project as a loose file and not compressed with the other project output. To install the assembly to the Global Assembly Cache, you must first sign your assembly with a strong name. See Chapter 9 for more information on strongly naming your assembly. Once your assembly has been strongly named, all you need to do is add a Global Assembly Cache folder to the File System Editor and add your assembly to that folder. Upon installation, your assembly will be added to the Global Assembly Cache.

To install an assembly to the Global Assembly Cache upon installation

1. Sign your assembly with a strong name.

2. After creating your setup project, open the File System Editor.

3. Right-click the left pane, and choose Add Special Folder. In the shortcut menu, choose the Global Assembly Cache folder.

4. In the left pane, right-click the Global Assembly Cache folder. Choose Add, and then choose Assembly from the shortcut menu. Choose the appropriate assembly or browse to its location and click OK to add the assembly. The assembly will be added to the Global Assembly Cache upon installation. If the assembly was not already a part of your setup project, it is added to it.

Adding a Shortcut Using the File System Editor

You might want to configure your setup application to add a shortcut to the installed application on the target machine s desktop or another location. You can use the File System Editor to create shortcuts to files and add them to folders on the client machine.

To create a shortcut and add it to the target computer

1. In Solution Explorer, right-click the file for which you want to create a shortcut. Choose Find In Editor. The right pane of the File System Editor switches to the folder that contains that file.

2. In the right 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.

3. Drag the shortcut from the right pane to the appropriate folder in the left pane.

Registry Editor

You can use the Registry Editor to write registry entries upon installation. You can create new registry key entries or write new values to existing registry key entries. The Registry Editor is shown in Figure 10.10.

Figure 10-10. The Registry Editor.

Like the File System Editor, the Registry Editor window is divided into two panes. The left pane represents the registry on the target computer, and the right pane represents registry key values.

To add a new registry key

Right-click the key that you want to contain the new registry key, and choose New Key. A new subkey is added to that registry key. Name the key appropriately.

To add a new registry key value

1. In the left pane of the Registry Editor, right-click the registry key you want to add a value to, choose New, and then choose String Value, Environment String Value, Binary Value, or DWORD Value, depending on the type of key value you want to add. A new key value entry is added to the right pane.

2. In the Properties window, set the Value property of the new key value to an appropriate value.

File Types Editor

The File Types Editor allows you to create associations between files with a particular extension and your application. An example of a file association might be the association between files with the .txt extension and the Notepad application. When a .txt file is double-clicked, it is automatically opened with Notepad. The File Types Editor shown in Figure 10.11 allows you to create these associations.

Figure 10-11. The File Types Editor.

You can create a new file association by right-clicking the File Types Editor and choosing Add File Type. This causes a new blank file type to be added to the window. Beneath the new file type, &Open is added as an action. You can add additional actions by right-clicking the file type and choosing Add Action.

You can configure the file association in the Properties window for the file type and the action. The Name property of the file association is the name of the file types that it represents. You can add file types to this file association by setting the Extensions property to the extension of the file type you want to add. If you want to associate more than one file type with your application, you can add multiple file types separated by semicolons to this property. It is not necessary to prefix file extensions with a period.

The Command property for the association represents the application to launch when an action is taken. For example, if you are creating an association between your application and a file with the extension .tew, set the Command property to your application. Whenever an action is invoked on a .tew file, your application launches and performs the appropriate action.

Actions associated with a file type have three properties. The Name property is the text that appears in the context menu when a file with this extension is right-clicked. The Verb property specifies the verb that is used to invoke an action for the file type. The Arguments property allows you to supply any required command-line arguments to the application.

When a document that has a file association with your application is right-clicked, a context menu appears presenting the Name property of any defined actions. When one of the actions is chosen, the executable represented by the action is launched. The executable receives the path of the chosen document and any other parameters specified in the Arguments property as command-line parameters. The path of the document is always the first member of the argument array. These arguments are passed to the Main method of the application. You must add any appropriate program logic to cause the application to perform the desired task. The following example demonstrates how you would use the command-line argument to open a file with an application s Open command:

Visual Basic .NET

Shared Sub Main(ByVal args() As String) If Not args.Length = 0 Then ' Assumes that the application's Open command takes a ' string that contains the path of the file to open. The ' Open method must also be Shared, as you cannot call an ' instance method from a Shared method. Open(args(0)) Else Application.Run(New Form1()) End If End Sub

Visual C#

static void Main(string[] args) { if(args.Length!=0) { // Assumes that the application's Open command takes a // string that contains the path of the file to open. The // Open method must also be static, as you cannot call an // instance method from a static method. Open(args[0]); } else { Application.Run(new Form1()); } }

NOTE
Visual Basic Windows Forms applications do not contain a Sub Main by default; it must be added manually. You must then set the startup object to Sub Main in the Property Pages for your project. For Visual C# applications, you must manually modify the static void Main declaration to accept the array of strings as an argument.

User Interface Editor

The User Interface Editor allows you to alter the visual interface that the user sees when installing your application. The User Interface Editor, shown in Figure 10.12, consists of two tree-view displays: Install and Administrative Install.

Figure 10-12. The User Interface Editor.

Each tree view graphically represents the dialog boxes that the user views during installation and is divided into three sections: Start, Progress, and End. Each section contains a series of preset dialog boxes appropriate to that phase of deployment.

In the Start phase, Windows Installer gathers information about the program installation from the machine and the user. Any dialog boxes requiring user choices (such as a dialog box for choosing the installation directory) should be in the Start phase. At the end of the Start phase, Windows Installer checks for available disk space. If there is insufficient disk space, the deployment aborts.

The Progress phase occurs while the application is installing. There is normally no user interaction during the Progress phase, and only a single dialog box indicating installation progress is displayed.

The End phase is entered after the application has installed. This phase is normally used to present information about the installation to the user.

You can change the properties of each dialog box by selecting it in the User Interface Editor and editing the properties in the Properties window. For example, you can set the BannerBitmap property of the Welcome dialog box to display a custom bitmap image for your company.

You can change the order that the dialog boxes are viewed during installation by selecting a dialog box and dragging it to the desired spot in the tree view. Although it is technically possible for any dialog box to appear in any position, there are some practical limitations. For example, a Finished dialog box cannot appear at the start of an application.

Administrative Installation vs. Regular Installation

When configuring the setup project for administrative installation (see Lesson 1 of this chapter), you might want to afford the administrator options that are unavailable during regular installation. For example, you might not want end users to choose the installation directory for an application, preferring instead to set the directory during administrative installation. In this case, you would remove the Installation Folder dialog box from the regular install tree but leave it in the administrative installation tree. Thus, the administrator chooses the folder for installation, and it is installed to that directory when the end users install the application.

Adding Dialog Boxes

Customizable dialog boxes that accept user input can be added to your installation choose check boxes, radio buttons, or text boxes. Editing the box properties in the Properties window allows you to customize their appearance. In addition to properties that control the appearance of the dialog box, such as BannerBitmap, BannerText, and BodyText, other properties allow the application to retrieve input from the user. For example, consider a dialog box of the type RadioButtons (2 buttons). You can add this dialog box to a node in your tree view by right-clicking the node, choosing Add Dialog, and then selecting RadioButtons (2 buttons) from the Add Dialog dialog box. This dialog box also exposes the following:

• Button1Label

• Button2Label

• Button1Value

• Button2Value

• DefaultValue

• ButtonProperty

The properties called ButtonNLabel, where N is the number of the button, represent the text that will appear next to the radio button. Similarly, ButtonNValue represents the value that is returned by the button group when that button is chosen. DefaultValue indicates the start value for the button group.

The ButtonProperty value is a string that represents the property name used by the installer to retrieve the value of the button group. This property can be referenced by custom launch conditions (as described later in this lesson) to make decisions concerning application installation. For example, if the ButtonProperty is set to Buttons, you create a launch condition that examines the value of the Buttons property. If the first radio button is selected, Buttons takes the value contained in the Button1Value property. Likewise, if the second radio button is selected, Buttons takes the value contained in the Button2Value property. Many of the customizable dialog boxes have similarly configurable properties, which allow you to create a rich and complex installation experience for your users.

Custom Actions Editor

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 10.13, to associate code with these Windows Installer events.

Figure 10-13. The Custom Actions Editor.

Any executable code can be executed as a custom action. 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. You can configure the custom action by setting the properties in the Properties window. These properties are summarized in Table 10.2.

Table 10-2. Custom Action Properties

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 property is applicable only when the custom action is implemented 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 property 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 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.
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 machine 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. From the View menu, choose Editors, Custom Actions Editor.

3. 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.

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

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

Launch Conditions Editor

You can use the Launch Conditions Editor to create conditions that must be met by the target machine before the installation will execute. For example, you can determine that the appropriate version of Windows is running or that an up-to-date version of a required component has been installed. You can search for files, search the registry, or search for Windows Installer components, and then make decisions based on whether the correct files were found. The Launch Conditions Editor is shown in Figure 10.14.

The Launch Conditions Editor window is divided into two parts. You can add a search that searches for a file, a registry key, or a Windows Installer component on the target computer. You can then add a condition based on the outcome of that search. If the condition is met, installation will proceed normally. If the condition is not met, installation will be rolled back.

Figure 10-14. The Launch Conditions Editor.

Creating Searches

You can create a search by right-clicking Search Target Machine in the Launch Conditions Editor and choosing the appropriate kind of search. The search types are summarized in Table 10.3.

Table 10-3. Launch Condition Search Types

Search Type	Description
File	Searches the target computer s file system for a specified file. You can configure the search to look for a specific version of the file, as well as specify minimum and maximum file sizes and dates for the object of the search.
Registry	Searches the registry of the target computer for a specified registry entry. You can specify a search for the root, the key, and the value.
Windows Installer	Searches the target computer for a specified Windows Installer component.

Each search has a Property property. This property specifies the property name that can be used to retrieve the Boolean value that indicates whether a search was successful. You use the name created in the Property property to create launch conditions, as addressed later in this section.

To create a search for requirements on the target machine

1. From the View menu, choose Editor, Launch Conditions.

2. In the Launch Conditions Editor, right-click Search Target Machine, and choose the option representing the kind of search you would like to add from the context menu.

3. In the Properties window, configure the conditions of your search.

Creating Launch Conditions

Once you have created a search, you can evaluate the results of that search and use them to create a launch condition. A launch condition represents an all-or-nothing decision about the fate of an installation. If the launch condition is met, the installation continues. If the launch condition fails, the installation aborts.

You can add a launch condition to a setup project by right-clicking Launch Conditions in the Launch Conditions Editor and choosing Add Launch Condition. A launch condition has three properties, which are summarized in Table 10.4.

Table 10-4. Launch Condition Properties

Property	Description
Name	The name of the launch condition as seen in the Launch Conditions Editor.
Condition	A string that contains a valid Boolean expression. The expression is evaluated at install time. If true, the installation continues. If false, the installation aborts. The string can also contain more than one Boolean expression connected by logical operators (AND, OR, and so on).
Message	Contains the message to be displayed in the event that the installation fails.

To create a launch condition

1. From the View menu, choose Editor, Launch Conditions Editor.

2. In the Launch Conditions Editor, right-click Launch Conditions and choose Add Launch Condition.

3. In the Properties window, configure the properties for your launch condition.

Installing a Native Assembly Image

Applications and assemblies developed in the .NET Framework are generally deployed as Microsoft intermediate language (MSIL) files. At run time, these files are just-in-time compiled to native code, which allows maximum efficiency and use of resources coupled with excellent application speed. In situations where performance is critical, you might be able to achieve a somewhat higher level of performance by precompiling your application to native code. You can use the Ngen.exe utility to create a native image for your application.

Ngen.exe is a command-line utility that generates a native image of your application or assembly and installs it to the Native Image Cache. After you have generated a native image, the runtime will locate and execute the native image whenever the assembly is called.

To create a native image of your assembly or application

1. Open the Visual Studio .NET command prompt. This can be accessed by opening the Windows Start menu and then choosing All Programs, then Microsoft Visual Studio .NET, and then Microsoft Visual Studio .NET Tools.

2. Change directories to the directory that contains your assembly or application.

3. Use the Ngen.exe utility as shown in the following code. For DLL assemblies, you must specify the name of the assembly. For executable applications, you must specify the path to the executable file. For example:

   Ngen myAssembly Ngen C:\myApp.exe

Verifying Installed Assembly Security Policies

Once your assembly is installed, you can use the Permview.exe utility to view the permissions it requests. To use the Permview.exe utility, open the Visual Studio .NET Command Prompt and type the following code:

Permview myAssembly.dll Permview myApp.exe

In the code lines, myAssembly is the name of the DLL while myApp is the name of the executable you want to examine. This assumes that the assembly manifest is contained in the specified file. If the assembly manifest is separate from the rest of the assembly, you should specify the file containing the assembly manifest in the command line instead.

Running this utility displays a list of all requested assembly level permissions. If you want to examine all declared permissions, including at the class and method level, use the /DECL flag as shown here:

Permview /DECL myAssembly.dll

You can also write the output to a file instead of the console. To write the output to a file, use the /OUTPUT flag to specify the output file, as follows:

Permview /OUTPUT myTextFile.text myAssembly.dll

Lesson Summary

• Setup applications are highly configurable. You can set setup properties that provide information about the origin of your application and behavior of your application at design time in the Properties window.

• Use the Register property to register a COM component or a font at install time.

• Use the File System Editor to edit the file system on the target computer.

• Use the Registry Editor to write registry entries to the target computer.

• Use the File Types Editor to create file associations on the target computer.

• Use the User Interface Editor to customize the installation user interface.

• Use the Custom Actions Editor to add a custom action.

• Use the Launch Conditions Editor to add a search and a launch condition.

• Use Ngen.exe to create a native code image of your application or assembly.

• Use Permview.exe to view the permissions granted to an assembly.