Lesson 1: Windows Setup Programs

Deployment consists of two steps. The first step is to transfer all necessary files to the users' hard disks. The second step, which is potentially more complicated, involves configuring the host system so that it recognizes and correctly runs the installed application. To help ensure proper deployment, you should automate the process of getting an application up and running as much as possible. Windows users are accustomed to an installation program that does most of the work for them.

After this lesson, you will be able to:

• Describe how an application is installed on and removed from a user's system.
• List the services provided by a typical installation program.
• Describe various entries that an installation program places in a user's registry.
• Create cabinet and registry files.

Estimated lesson time: 20 minutes

Setup Program Conventions

An installation program should always be named Setup for two reasons:

• To conform to convention.
• To be recognizable to the Add/Remove Programs applet in Control Panel.

Consistent use of the Setup file name has become standard practice for application deployment programs, which helps to minimize confusion among users. The standard Windows user knows how to work with programs named Setup, though the programs can differ in individual style and methods. For purposes of discussion, this lesson refers to installation programs generically as Setup programs.

If your application distribution requires several disks or CD-ROMs, the Setup program should exist on the first disk or CD-ROM of the series to ensure that it is easily located by the Windows Add/Remove Programs applet.

A number of installation services can be provided to users. A typical setup program will:

• Prompt for selected program options.
• Create folders on a user's hard disk as required.
• Copy files from the distribution media to the hard disk.
• Add registry information for shared DLLs.
• Register an application's ActiveX controls and other COM components.
• Add information to the system registry specifying the command needed to remove the application. This allows the Add/Remove Programs applet to identify the application's uninstall program.
• Record the extension used for the application's document files in the system registry to allow users to launch the application from Windows Explorer by double-clicking a document in a file list.
• Add an entry to the Windows Programs menu, or a desktop shortcut if stipulated.
• Execute "run-once code" to minimize installation size if the Setup program is not copied to the hard disk.
• Add or make unavailable selected options from the installed application when the Setup program is run again.

The user should need only to select an installation option and insert any additional disks or CD-ROMs as prompted. Microsoft recommends that an installation program include the following four options:

• Compact for laptops and systems with limited disk space.
• Custom to give users control over what is installed.
• Typical to provide a common default suitable for most users.
• Silent for unattended installation.

Silent installation is necessary for systems managers who want to install an application across a network. While running in silent mode, the Setup program should not query or display error messages, and must assume intelligent default settings for all cases.

Guidelines for Writing a Setup Program

Keep the following points in mind when you plan a Setup program for your application's deployment. An intelligent Setup program should:

• Store private initialization (.ini) files in the application directory if the application is running locally, or in the directory returned by the GetWindowsDirectory() API function if the application is shared.
• Avoid inappropriately copying files to the Windows, WinNT, System, or System32 directories. If your application package includes font files, they should be copied to the system's Fonts folder.
• Check that a file does not already exist on the hard disk before copying it. If the Setup program finds a conflict, it should decide which file is most recent and avoid overwriting a newer file.
• Supply defaults. In particular, the Setup program should provide a common response to every option so users press only the ENTER key at each prompt for a successful default installation.
• Avoid prompting users to insert the same disk more than once.
• Inform users about required disk space.
• Display a progress indicator.
• Store intermediate files in the Temp directory. However, if the Setup program must restart Windows before reading intermediate files, it should confirm that the Temp directory exists on a hard disk and not on a RAM disk. This procedure ensures that the necessary files will still exist after restarting.
• Give users a chance to cancel installations before finishing. The Setup program should keep a log of files that have been copied and settings that have been registered so that it can clean up canceled installations.

A user installs your application either by running the Setup program directly or by running the Add/Remove Programs applet in Control Panel. Add/Remove Programs automatically searches the disk or CDROM drive for a program named Setup.exe. If the file is found and the user agrees to finish the installation, Add/Remove Programs starts the Setup program and closes. After Add/Remove Programs closes, the Setup program is responsible for guiding the user through the rest of the installation process.

Uninstall Program Conventions

An installed product should be able to safely, and as completely as possible, remove all traces of itself. This operation, sometimes known as de-installing or uninstalling, is typically carried out by a separate program with a descriptive name such as Uninstall or Uninst. Alternatively, the Setup program itself can be written to act as the uninstaller. You have much more flexibility when choosing a name for your uninstall program because the location and file name of the uninstall program are identified in the Setup program and written to the system registry during the installation process. This action assures that Add/Remove Programs can locate the correct uninstaller executable regardless of its name.

Uninstalling is an important feature for users, and also is one of the prerequisites for an application to be approved for the Windows compliance logo. Uninstalling includes deleting application files (but not documents) and removing entries added to the system registry.

Because many applications share resources and make modifications throughout the system, deleting an application is rarely a matter of simply deleting files in a single subdirectory. Users must be able to uninstall cleanly and reinstall to correct problems, change configurations, or upgrade applications. The uninstall feature also allows users to free disk space and to abide by licensing agreements when deleting an application from one computer before installing it on others.

Uninstalling a Windows application must be done carefully. A potential problem arises when deleting a program's dependency modules such as DLLs and ActiveX controls. (Dependencies are described in Lesson 5 of Chapter 13.) The uninstall operation must not delete modules upon which other applications depend.

An uninstall program cannot directly determine if a module serves other programs, but can infer whether a module is shared by consulting a usage count stored in a common area of the registry. Usage counts are described in the next section.

Adding and Removing Registry Information

An installation program adds all the necessary information about your application to the registry. User preference data should be written to the registry's HKEY_CURRENT_USER\SOFTWARE key. In earlier versions of Windows, this information was written to the Win.ini file. For information specific to the application, add entries to the HKEY_LOCAL_MACHINE\SOFTWARE registry key using this format:

HKEY_LOCAL_MACHINE\SOFTWARE\CompanyName\ProductName\Version

Substitute names for the italicized placeholders that are appropriate for your application.

PATH Environment Variable

Each running application has its own PATH environment setting, containing a list of paths to various folders. The list specifies the paths that the operating system should search when looking for executable modules required by the application. By default, Windows searches certain system folders first in an effort to locate files required for loading an application. Since most applications are installed to unique directories, the path to the application's components must be specified in an application-specific PATH setting.

For example, consider an application in the MyApp folder that uses a DLL in the MyDLL folder. Assuming normal linkage—that is, assuming the application does not call the LoadLibrary() API function to load the DLL—the application cannot run unless MyDLL appears in the PATH list. The operating system will search only for DLL files in the default system folders and the folders specified in the PATH variable. If a referenced DLL is not located, the system will refuse to run the application. The application's installation program must therefore specify a PATH setting that includes the MyDLL folder where the required DLL file resides.

To register a PATH, a Setup program should write the desired value in the HKEY_LOCAL_MACHINE root under the \SOFTWARE\Microsoft\ Windows\CurrentVersion\App Paths key. This is the same string contained in the REGSTR_PATH_APPPATHS text macro defined in the Regstr.h file. Notice that the last nested key, App Paths, is two words.

The Setup program should create a new registry key having the same name as the application's executable file, and then insert a Path value containing the desired path. Here's an example of how the Path registry value might look for the NewApp program located in the MyApp folder of the preceding code:

HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ App Paths\NewApp.exe Default=D:\MyPrograms\MyApp\NewApp.exe Path=D:\MyPrograms\MyDLL;D:\MyPrograms\MyApp\Utilities

The Default value specifies the full path to the executable file. The operating system refers to this value when a user types the application name in the Run dialog box without specifying a full path to the executable file. Windows locates the requested executable by searching the App Paths key, then reads the full path from the Default value.

The Path value contains NewApp's PATH environment, which includes a reference to the MyDLL folder. When the operating system loads NewApp, it searches the prescribed locations for the DLL that NewApp needs. By including the MyDLL folder in the application's PATH, the Setup program ensures that the system can always locate the required DLL file when running NewApp.

Usage Counts for Shared Modules

For each shared module that it installs, the Setup program should consult the registry and increment the module's usage count. When the application is removed, the uninstall program must decrement the usage count. If the count drops to zero, the uninstaller can delete the module—though usually only after querying the user for permission. If every Setup program were to follow this procedure, dependency modules could be safely removed. Unfortunately, not every developer creating installation programs conforms to this convention; thus, it is customary to query users before removing a file for which the usage count has reached zero.

Usage counts for shared modules are stored in the HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\SharedDLLs key. Figure 14.1 shows an example in the RegEdit utility (described later), in which the usage count for an ActiveX control named msinet.ocx is currently 2.

Figure 14.1 Viewing a usage count in the RegEdit utility

Cabinet Files

A cabinet file contains files in compressed form, resulting in a single file that serves as a file library. Cabinet files, recognizable by their .cab extension, are often used when deploying large applications because they reduce the number of disks or CD-ROMs required. The application's Setup program reads the .cab files, decompresses their contents into the original files, and writes the files to the user's hard disk.

A .cab file is similar to a .zip file in that it serves as a compressed archive for a group of files. A .cab file can contain any kind of file, and can also have a digital signature that identifies the file's creator and ensures that the file has not been maliciously or accidentally altered. Digital signatures are described in more detail in Lesson 4 of this chapter.

Creating a .cab file requires either the MakeCab or CabArc (Cabinet Archiver) utilities. Both programs are part of the Microsoft Cabinet Software Development Kit (SDK), available as a free download from msdn.microsoft.com/workshop/management/cab/cabdl.asp. MakeCab creates compressed disk images containing a product's files, and is designed to work with Setup programs. CabArc is a console-based program that can read and write .cab files. To run CabArc, type a list of options, the name of the .cab file, and a list of files to compress or decompress. For example, the line

cabarc n images.cab \myapp\images\*.jpg \myapp\images\*.gif

creates the Images.cab file, and adds, in compressed form, all the .jpg and .gif graphics files in the MyApp\Images folder. The n option tells CabArc to create a new file. The Cabinet SDK contains examples and documentation for the CabArc and MakeCab programs.

Registry Files

Setup programs sometimes use registry files to write entries into the system registry. Recognizable by its .reg extension, a registry file serves as a script that lists keys, values, and locations to be added to the registry. Because a registry file is in ASCII format, it can be viewed and edited in a text editor. For example, the registry file for the NewApp program mentioned earlier specifies the program's PATH environment as shown in the following code:

REGEDIT4 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\ App Paths\NewApp.exe] @="D:\\MyPrograms\\MyApp\\NewApp.exe" "Path"="D:\\MyPrograms\\MyDLL;D:\\MyPrograms\\MyApp\\Utilities"

Although long lines in the script have been broken to fit on the printed page, each entry must occupy a single unbroken line in the registry file. No continuation character for registry scripts exists.

The code as shown assumes that the NewApp program is in the MyPrograms\ MyApp subdirectory, and demonstrates a potential problem with registry files. The Setup program must ensure that any paths specified in the script correspond to the location where a user ultimately decides to install the application. Therefore, the Setup program must be prepared to alter a .reg file before using it.

Windows provides the RegEdit utility to read and write registry files. A Setup program can use RegEdit to write (or import) the script into the user's system registry, and supply a registry file in the command line like this:

regedit newapp.reg

This command writes the contents of the NewApp.reg file to the system registry. The following code demonstrates how to create a file named IEpath.reg, which contains a copy of the path information for Internet Explorer:

regedit /e IEpath.reg "HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\ CurrentVersion\App Paths\IEXPLORE.exe"

The /e switch causes RegEdit to read (or export) a section of the registry to a specified file. It is necessary to include the registry key information in double quotation marks only when the key contains a space, as in App Paths. Otherwise, quotation marks are not required.

The RegEdit utility provides a simple Windows user interface, so it does not need to be run from the command line. The following exercise demonstrates how to write a .reg file by invoking a command on the program's Registry menu.

To create the IEpath.reg file in RegEdit

1. On the taskbar, click the Start button, and then click Run. In the Open box, type regedit, and then click OK to start the RegEdit utility.
2. Beginning with the HKEY_LOCAL_MACHINE root, expand the tree view and select the IEXPLORE.EXE key as shown in Figure 14.2. The full path to the IEXPLORE.EXE key is shown at the bottom of the RegEdit window in the figure.



Figure 14.2 Selecting Internet Explorer's PATH entry in the system registry

3. On the Registry menu, click Export Registry File.
4. Select the desired folder and type IEpath in the File name box.
5. Click Save, and then exit RegEdit.
6. Start a text editor such as Notepad and open the new IEpath.reg file that has been created in your default document directory. The script shows that, like many programs, Internet Explorer includes its own application folder as part of its PATH environment.

A registry file is most useful when a large amount of registry data is being manipulated or when the data is transitory and the Setup program must load and then unload the information again. A Setup program can also use the RegEdit utility to create a backup copy of selected registry information. The uninstall program can then restore the original settings if the user chooses to delete the application.

Lesson Summary

This lesson presented a general overview of the installation process in which a Setup program configures a user's computer to run an application.

A Setup program should ideally provide installation options labeled Compact, Custom, Typical, and Silent. Silent installation allows administrators to run the Setup program unattended when installing the application across a network. Professional-quality Setup programs seek to make the installation process as easy as possible for the user.

If the application requires a custom PATH environment, the Setup program should record the desired variable in the registry. This specifies the PATH setting that Windows makes current when the application runs. The Setup program should also consult the registry when installing shared modules such as DLLs and ActiveX controls, incrementing usage counts for the modules. When the application is removed, the uninstall program decrements the counts and prompts to remove the file when the count reaches zero.

The lesson finished with an introduction to cabinet and registry files. Cabinet files serve as archives that contain other files in compressed form. Microsoft makes available utilities such as MakeCab and CabArc for creating and using cabinet files. Registry files are scripts that can be inserted into the system registry using the RegEdit utility.