Directives

Creating a Custom Setup Program

Visual Basic .NET includes a new tool that generates installation programs for .NET projects. In the past, you used the Visual Basic Setup Wizard to accomplish this task, and often you had to hack script files to get your custom setup program to do exactly what you needed it to do. There are no more text files to hack, but there are a lot of things you can do with the new interface. Unfortunately, this particular tool is probably one of the least intuitive so far, and getting the most of it requires some patience. In this section, I'll show you the ins and outs of this tool so that you can create setup programs that effectively install your applications using a wizard interface to which users have become accustomed. (See Figure 16-1.)

Figure 16-1. You can create friendly setup wizards that users can run to install your application.

The new distribution tool isn't a wizard, nor an add-in, and it doesn't appear on the Start menu. In fact, if you're not sure where to look for it, you might think the tool was forgotten. The tool is fact an actual .NET project. To start the tool, create a new project in Visual Basic .NET. When the New Project dialog box appears, follow these steps:

1. Click the Setup And Deployment Projects project type.

2. Click the Setup Project icon. (See Figure 16-2.)

3. Name the setup project. The name you use here is the name that appears in the custom setup wizard's title bar. You should name the project "ProgramName Installer," where ProgramName is the name of the program you are installing.

   Figure 16-2. To generate a custom setup wizard for your program, start by creating a setup project.

   

   Tip

   Use the Web Setup Project type when creating a setup program to create a custom setup wizard for Web projects.

   
    

The interface for a setup project consists primarily of two panes. (See Figure 16-3.) You can change what appears in the left pane I'll explain how to do this later but by default, this pane represents the file system of the target machine (the computer on which the software is being installed). These aren't physical file folders; they're logical folders: although the paths to these folders might differ from target machine to target machine, they are always found and used accordingly by the setup program.

Figure 16-3. The interface of the setup project consists primarily of a list of logical folders and the contents of the selected folder.

The pane on the right shows the contents of the selected item in the left pane. Using these two panes, you can accomplish a lot of functionality to tailor your custom setup program. The interface isn't all that intuitive, as you'll see, but once you learn your way around the interface you'll find yourself rather productive.

Adding the Output of a Project

At this point, your setup program doesn't actually do anything. The first step you'll want to take is to add the output of another project. This is the component of the primary application you want installed on a target computer (such as the compiled executable or DLL). You accomplish this by adding to the current solution the project of the application you want to distribute. The easiest way to do this is to right-click the solution name in the Solution Explorer window and choose Existing Project from the Add menu. (See Figure 16-4.) Visual Basic will then display the Add Existing Project dialog box, which you use to locate and select the project whose output you want installed. (See Figure 16-5.)

Figure 16-4. You have to right-click the solution, not the project, to add an existing project.

Figure 16-5. In order to distribute the output of a project, the project must be part of the solution.

Simply adding a project to the current solution doesn't automatically cause its output to be installed on the target machine; you have to tell the setup project to include the compiled component. Things can get tricky here because you have to use the Project menu, which changes its contents according to the project you have selected in the Solution Explorer window. If you have the wrong project selected in Solution Explorer, you won't get the menu items that you expect when you open the Project menu.

Important

You have to make sure the left pane is active, not the right pane, before performing the next step. If the right pane is active when you open the Project menu, you'll get the standard Project menu that you see when working with the project see Figure 16-6 not the options used to add the output to the project. (See Figure 16-7.) This is a morphing form, and the first time you open the Project menu only to discover that the options that you're looking for don't exist, you'll fully appreciate the confusion a user experiences when a form adjusts its contents in an illogical manner.

 

Figure 16-6. This is the Project menu you'll see if you have the right pane selected.

To designate the output of a project to be installed on a target machine, first select the project whose output you want installed, open the Project menu, and then choose Project Output from the Add submenu. Doing so displays the Add Project Output Group dialog box shown in Figure 16-8. As you can see from Figure 16-8, there are a number of different output types you can choose to install. To install the actual build (EXE or DLL), choose Primary Output and click OK.

Figure 16-7. This is the Project menu you'll see if you have the left pane selected (the file system pane).

Figure 16-8. Choose Primary Output to have the project's distributable file installed on the target computer.

After choosing to include the output of a project, the output (EXE or DLL) is added to the Application Folder. You can view this content by clicking the Application Folder item in the left pane. (See Figure 16-9.)

Figure 16-9. The primary output of a project is added to the Application Folder.

Specifying the Build Options of a Project's Output

Usually, you'll define the build options for a project when creating and maintaining the project. However, it's always a good idea to verify the options when you add the output of a project to the setup project. To view and change the build options, you right-click the project in the Solution Explorer window (not the setup project, but the project whose build is included) and choose Properties from its context menu. This displays the project Property Pages dialog box. To change the build options, click the Build item in the options tree. (See Figure 16-10.)

The icon specified as the application icon appears whenever a shortcut is created for the program, and you should make sure that you use a custom icon that is meaningful to your application. You should also make sure that, at the very least, Option Explicit is turned on. The best way to build a component is using Option Strict, which you should turn on unless your project uses late binding.

Figure 16-10. Use this dialog box to control aspects of the build of a program being distributed.

Adding a File to the Installer

You aren't limited to installing the output of a project; you can install any file that you choose. For example, you might want to include sample data or support files with your program. As mentioned earlier, be sure you have the left pane selected when working with the project, or you won't find the menu items you expect on the Project menu. To add a file to the installer, select the setup project (not another project that has been added to the solution for its output), open the Project menu, and then choose File from the Add menu. Visual Basic .NET then displays the Add Files dialog box, which you can use to browse and select any file from your file system. (See Figure 16-11.)

Figure 16-11. You can add any file you like to be installed on a target machine.

As when adding the output of another project to your setup project, files added to the project are placed in the Application Folder by default.

File Properties

Once you've chosen a file to be included in the installer, you can change a number of properties to manipulate the way in which the file is installed on the user's machine. To change a file's installation properties, select it in the right pane of the setup project interface (you must first make sure you have the folder containing the file selected in the left pane, of course), and then display the Properties window. Table 16-1 lists the properties you can change for a file being installed, along with a description of each property.

 

Table 16-1. File Properties 

Property	Description
Condition	Specifies a Windows Installer condition that must be satisfied (evaluate to True) in order for the selected item to be installed at installation time.
Exclude	Determines whether a file will be excluded from an installer or merge module. If set to True, the file will be remain in the project but it will not be installed on a target computer.
Folder	Specifies the folder where the selected file will be installed on the target computer. You can use this property rather than dragging and dropping the file onto another folder.
Hidden	Specifies whether to install the file as a hidden file. By default, hidden files do not appear in the user's directory listings.
PackageAs	If you don't change the default value, the file is packaged using the values specified for the project (compressed, CAB files, or loose). You can override the default and force the file to be packed loose by using this property.
Permanent	Specifies whether the file should be removed when the application is uninstalled.
ReadOnly	Specifies whether to install the selected file as a read-only file. Users cannot edit or delete read-only files.
Register	Specifies whether the file should be registered during installation. You can have a file registered as a COM object or a font.
SharedLegacy	Specifies whether to mark the selected file as a shared legacy file that requires reference counting.
SourcePath	Displays the path to the selected file on the development computer.
System	Specifies whether to install the selected file as a system file. A system file is normally a binary file that is part of the operating system.
TargetName	Specifies a name for the file when it is installed on a target computer. The file is renamed during installation if it differs from the source file name.
Transitive	Determines whether the installer will reevaluate the Condition property for the selected item when installing or reinstalling on a target computer.
Vital	Specifies whether the selected file is vital for installation. If a vital file cannot be installed correctly, the entire installation will fail.

 

Changing the Default Location of the Application Folder

The Application Folder is the primary folder that gets created on the target computer. Most program files (including the output of other projects) are usually installed in the Application Folder. Other files that you add to the setup project default to the Application Folder, but you can use just about any folder that you can think of.

I mentioned earlier that the folders listed in the left pane are logical, or virtual folders these folders are mapped to real folders on a target machine during installation. You can see the mapping of a folder by clicking it in the left pane and looking at its DefaultLocation property in the Properties window. (See Figure 16-12.)

Figure 16-12. Logical folders are mapped to real folders during an installation.

By default, the Application Folder has the following path mapping:

[ProgramFilesFolder][Manufacturer]\[ProductName] 

ProgramFilesFolder is, logically enough, the Program Files folder on the user's computer. The Manufacturer token is replaced at install with the name of your company that you entered when you installed Visual Basic .NET. The ProductName token is replaced with the name of your setup project. You can override these settings by selecting the setup project in the Solution Explorer window and then viewing the project properties in the Properties window. (See Figure 16-13.) Be aware that the user is prompted by your custom setup program for the Application Folder and that the logical path specified by the DefaultLocation property is presented to the user as a default. (See Figure 16-14.) The user can change this folder to any folder he or she chooses. The user even has the ability to view the "cost" associated with installing to each disk on the system. (See Figure 16-15.)

Figure 16-13. Use the properties of the setup project to control many aspects of the installation.

Figure 16-14. Users can change the default location of the Application Folder when they install your program.

Figure 16-15. Your custom setup program lets the user easily see the total, available, and required space when choosing a drive to which to install.

Working with Folders on the Target Machine

The pane on the left lists logical folders that correspond to real folders on the target computer. By default, only three folders are listed: Application Folder, User's Desktop, and User's Programs Menu. I discussed how to create a default location for the Application Folder in the previous section. The User's Desktop Folder and User's Programs Menu folder are self-explanatory. You aren't limited to using these three folders, however. In addition, you can specify a folder that already exists on the user's computer (such as the user's Favorites folder), and you can create new folders that don't exist (such as creating a Sample folder under your application folder).

To add a new folder to the list, right-click the File System On Target Machine root node in the left pane and then open the Add Special Folder submenu. (See Figure 16-16.) The first section of the menu contains all of the existing folders that you can use on a target machine you're probably familiar with most, if not all, of these folders. Table 16-2 lists these folders along with descriptions of each. If you want to install a file into one of these folders, simply choose the folder form the list and it will be added to the File System On Target Machine list in the left pane.

Figure 16-16. You can add folders that already exist on the target machine, as well as create custom folders.

 

Table 16-2. Folders You Can Use That Already Exist on a Target Computer 

Folder Name	Description
Common Files Folder	A folder for components that are shared across applications. Typically, C:\Program Files\Common Files.
Fonts Folder	A virtual folder containing fonts. Typically, C:\Windows\Fonts.
Program Files Folder	The root node for program files. Typically, C:\Program Files.
System Folder	The Windows System folder for shared system files. Typically, C:\Windows\System32.
User's Application Data Folder	A folder that serves as a repository for application-specific data on a per-user basis. Typically, C:\Documents and Settings\username\Application Data.
User's Desktop	A folder that contains files and folders that appear on the desktop on a per-user basis. Typically, C:\Documents and Settings\username\Desktop.
User's Favorites Folder	A folder that serves as a repository for the user's favorite items. Typically, C:\Documents and Settings\username\Favorites.
User's Personal Data Folder	A folder that serves as a per-user repository for documents. Typically, C:\Documents and Settings\username\My Documents.
User's Programs Menu	A folder that contains a user's program groups. Typically, C:\Documents and Settings\username\Start Menu\Programs.
User's Send To Menu	A folder that contains a user's Send To menu items. Typically, C:\Documents and Settings\username\SendTo.
User's Start Menu	A folder that contains a user's Start menu items. Typically, C:\Documents and Settings\username\Start Menu.
User's Startup Folder	A folder that contains items that are run when Windows first starts.Typically, C:\Documents and Settings\username\Start Menu\Programs\Startup.
User's Template Folder	A folder that contains document templates on a per-user basis. Typically, C:\Documents and Settings\username\Templates.
Windows Folder	Windows or system root directory. Typically, C:\Windows.

 

Note

If an item is grayed out in the Add Special Folder menu, it is because the folder is already added to the list in the left pane.

 

To use or create a custom folder on the target machine, choose Custom Folder from the Add Special Folder menu. The custom folder is then added to the list using the name Custom Folder #1 (2, 3, and so forth). To change the name of the folder, right-click it in the left pane, choose Rename, and enter the new name of the folder. The next step is to determine where the new folder will be created. (Note: If the folder already exists on the target machine, it's left alone it does not lose its contents.) The DefaultLocation property of the custom folder controls the location of the custom folder. (See Figure 16-17.) Note that you can choose from a list of tokens that represent folders on the target machine. The [TARGETDIR] token represents the Application Folder mentioned earlier. The user is given an opportunity to overwrite the default location of the Application Folder, and whatever folder is chosen is stored in [TARGETDIR].

You might think that the new folder would be created in the specified target using the name you've assigned to the custom folder. (I know I sure did.) This isn't so. The DefaultLocation needs to be the full relative path of the folder. So, to create a folder called Samples underneath the main application folder, you would have to enter the following DefaultLocation:

[TARGETDIR]\Samples 

Realize that the name you assign the folder in the designer might have nothing to do with the name of the folder actually created on the user's computer unless the name is used appropriately in the DefaultLocation property.

Figure 16-17. The DefaultLocation property determines where a custom folder is created.

Changing the Folder in Which a File Is Installed

New files added to the setup project default to being installed in the Application Folder. To specify a different folder, simply click the folder in which the file resides in the left pane and then click and drag the folder from the right pane to the appropriate folder shown in the left. This is just like moving a file in Windows Explorer.

Creating Shortcuts

Adding a file or the output of a program to a setup project ensures that the file is installed. However, the setup wizard doesn't automatically create shortcuts for the items. Most applications create shortcuts in a custom folder on the user's Programs menu on the Start menu. To create a shortcut for a file, such as the primary output of your main application, click the folder containing the file in the left pane so that the file is displayed in the right. Next right-click the file for which you want to create a shortcut and choose Create Shortcut from the context menu. A new item will be added to the list of files this is the shortcut. The name will be in Edit mode, so change the name to something meaningful (such as the name of your main program) and press Enter to save it. Realize that the shortcut is now defined but it exists in the same folder as the item to which the shortcut points. So, the next step is to drag the shortcut to the appropriate folder, such as the User's Programs Menu folder. (Directive 16.13 offers suggestions on where to place shortcuts.) You can use the Properties window to tailor many aspects of a shortcut, such as assigning a custom icon and choosing to show the target application normal, minimized, or maximized.

Modifying the Registry on Installation

Using the setup project, you can define modifications to be made to the registry on a target machine. To access the registry settings, right-click the setup project in the Solution Explorer window and choose Registry from the View submenu. In fact, this View submenu is used to switch to many different types of items, including the File System view with which you have been working. The interface to the registry is similar to that used for file systems. (See Figure 16-18.) To add a new key or value, right-click the parent key and choose the appropriate item from the New submenu of the context menu. (See Figure 16-19.)

Figure 16-18. Adding registry keys is similar to adding files to an installation.

Figure 16-19. You can add new keys and values to the registry with relative ease.

Modifying the User Interface of Your Custom Setup Program

For simple applications, the default interface created for your custom setup program will be adequate. When defining installations for large and complex programs, however, you'll probably need to tailor the interface. To access the user interface definition for your setup project, right-click the setup project in the Solution Explorer window and choose User Interface from the View submenu. The integrated development environment (IDE) will change to show you the current layout of the user interface. (See Figure 16-20.)

Figure 16-20. The user interface of your custom setup program is presented as a tree.

Some stock dialog boxes have properties that you can change in the Properties window. For example, you can click the Welcome dialog box and then change its CopyrightWarning and WelcomeText properties to change the text that appears to the user.

To add a new dialog box, you have to right-click a category (Start, Progress, or End) and choose Add Dialog from its context menu. Visual Basic .NET then displays the Add Dialog window shown in Figure 16-21. Choose the template that most closely matches what you want to accomplish, and click OK to add it to the interface tree.

Figure 16-21. Visual Basic .NET includes a number of predefined dialog templates to choose from.

You don't actually manipulate dialog boxes in a form designer; rather, you set properties of the dialog box as required. For example, in Figure 16-22, I added a Checkboxes (A) dialog box. Notice that I have specified text and a default value for a single check box and that I've set the visible property of all other check boxes available on the dialog box to False.

Notice in Figure 16-22 that I supplied a property name for the check box (INSTALLSAMPLES). You can use these property names to define conditions for installing files. For example, I could create a sample folder as explained in this chapter, specify it to be installed in the Application Folder, and set its Condition property to INSTALLSAMPLES=TRUE. Doing so would cause the folder to be created only if the user chose the option in my dialog box. Figure 16-23 shows how the custom dialog box I created appears at run time.

Tip

The order in which the dialog boxes appear in the tree is the same order in which they are presented to the user. To move a dialog box up or down, right click it and choose Move Up or Move Down from its context menu.

 

Figure 16-22. After choosing a custom dialog box template, set its properties as you see fit.

Figure 16-23. It's easy to gather specific information from a user during installation.

Specifying Configuration Details

Before creating your custom setup program, you'll want to verify the project settings of the setup project, which are accessed by right-clicking the setup project in the Solution Explorer window and choosing Properties. (See Figure 16-24.) Using the Property Pages dialog box, you can:

• Change the configuration (Active, Release, Debug, or custom).

• Change the output file name. By default, the installer file is created in a subfolder (either Release or Debug, depending on the chosen configuration) under the project folder. You can change this if you need to.

• Choose the way files are packaged. By default, all files are included in the setup file. You can also choose to have the files compressed into CAB files or have all the files left loose (uncompressed). If you choose CAB files, you can specify the maximum size of a CAB file, and the compiler will create as many CAB files as necessary to hold the install files.

• Specify the type of bootstrapper (if any) to build into the setup file. The custom installation program that you distribute to target machines is built upon Windows Installer technology. Not all machines have the latest Windows Installer technology available. Including a bootstrapper ensures that the necessary Windows Installer files are installed as part of your setup program. If you don't include a bootstrapper, your install will fail if a target machine doesn't have the necessary Windows Installer files installed.

• Select a compression level (Optimized For Speed, Optimized For Size, or None) if you choose to package the files in the setup file or in CAB files.

• Digitally sign the custom setup program.

  Figure 16-24. Use the Property Pages of the setup project to tailor the details of your setup program.

  

Specifying Uninstall Information

Earlier, in the "Creating a Custom Setup Program" section, I suggested that you name your setup project "ProgramName Installer," where ProgramName is the name of the application you are installing. The primary reason I recommend that you do this is that you can't have two projects with the same name in a single solution, so you wouldn't be able to add a project for output if the project name was the same name as the setup project name. Because it's common to name a project using the product name, it's easy to create a conflict here. By using the name format I suggest, you avoid the conflict. The one problem with this approach is that, without further intervention, the name of the program in the Add Or Remove Programs dialog box in Windows will appear as ProgramName Installer. Obviously, this isn't desirable.

You can change the name that appears in the Add Or Remove Programs dialog box, as well as other information shown there, by setting some properties of the setup project itself (using the Properties window, not the Property Pages dialog box). You should set the following properties:

• AddRemoveProgramsIcon

  This property determines the icon that appears in the uninstall list.

• Author

  Give credit where credit is due.

• Description

  This property determines the descriptive text that appears if the user clicks the support link in the Add Or Remove Programs dialog box. (See Figure 16-25.)

• Manufacturer

  This value might help protect you legally.

• ManufacturerUrl

  Fill this in to make it easy for users to get to your site.

• ProductName

  This is the name assigned to the program in the Add Or Remove Programs dialog box.

• SupportPhone

  The telephone number of your technical support department.

• SupportUrl

  The link where users can get help with your program.

By setting these properties, the uninstall information presented to the user will be as accurate as possible. (See Figure 16-26.)

Figure 16-25. Some property values appear in this dialog box.

Figure 16-26. You can, and should, tailor the uninstall information for your program.

Building the Custom Setup Program

Building the custom setup program is the same as building any other type of project: you choose Build Solution from the Build menu, and the compiler creates the installation file in the path specified in the project Property Pages dialog box.

After building the setup program, and if you chose to install a bootstrapper, you'll notice that a number of files were generated. (See Figure 16-27.) The .msi file is the Windows Installer file that actually installs your application. The Setup.exe file is the bootstrapper it's what the end-user should run. The setup program will determine whether a bootstrapper needs to install Windows Installer files, and if so, it will install the appropriate bootstrapper. Instmsia.exe is the Windows Installer bootstrapper for Windows 95, Windows 98, and Windows Me. The file Instmsiw.exe is the bootstrapper for Windows NT. You should distribute all of these files to end users and have them run Setup.exe to install your application.

Figure 16-27. Building a setup program produces multiple files all of which should be distributed to end users.

 

Goals of Distributing Solutions

The goals of distributing solutions include

• Presenting your product and company in a positive light

• Making it quick and easy for a user to install your program

• Installing each file and component in a manner and location consistent with other commercial applications

• Avoiding breaking existing applications or the operating system itself