What happens when I run setup.exe?

The short answer is when you run a Windows Installer SETUP.EXE, you ‚ re invoking the Windows Installer executable program, MSIEXEC .EXE, that opens, reads, and processes the MSI database. The longer answer is that what happens depends not only on what the information in the MSI database tells Windows Installer to do, but also on the state of the target computer and on various runtime options that can be used to control the installation.

The setup launcher program

When you build a single-image distribution package for your product, the end result is a SETUP.EXE file your users can run to install your application. This is probably the most common way of distributing software, especially if you ‚ re an independent software developer deploying your products to individual users. Corporate developers and network administrators who need to deploy software to users across a LAN may prefer a different approach, such as the administrative install described later in this section.

Unlike third-party installers , where SETUP.EXE actually performs the installation, a Windows Installer SETUP.EXE is merely a launch pad for Windows Installer itself. Remember that Windows Installer is a service of the operating system, and this service is what actually performs the installation. After extracting the contents of the setup package, a Windows Installer SETUP.EXE runs MSIEXEC.EXE, which is where all the action takes place.

MSIEXEC ‚ the Windows Installer executable program

The Windows Installer executable program is MSIEXEC.EXE. This is the program that processes the Windows Installer setup package and performs the installation of the product. MSIEXEC accepts several options and parameters to control what it does. When MSIEXEC is run from SETUP.EXE, the appropriate options and parameters can be passed to MSIEXEC via the SETUP.INI file or directly to SETUP.EXE via the command line. If you are installing directly from an MSI file, though, you can run MSIEXEC.EXE from the command window and pass it the options and parameters you choose. Although this is not typically how you would want your users to install your product, it is useful to know how to do this for learning purposes. Let ‚ s look at the various options and see how they can be used to control what Windows Installer does.

The MSIEXEC command line interface

The basic syntax for the MSIEXEC command line interface is as follows :

 msiexec /[option] [msi file] 

For example, to install a product from MYPRODUCT.MSI you run

 msiexec /i myProduct.msi 

To uninstall that product you run

 msiexec /x myProduct.msi 

In all, MSIEXEC can accept 14 different options. ^[7] In addition to the /i and /x options mentioned above, there are three others of interest here. These are listed in Table 3 .

Table 3. Selected MSIEXEC command line options

Option	Description
/i	Install the product
/x	Uninstall the product
/a	Perform an administrative install
/p	Apply a patch to the product
/f	Repair the product

Administrative Install

Administrative installs are designed for use in deploying a product to several users in a network workgroup. An administrative install does not actually install the application. Instead, it writes out a set of files similar to the files created by building a CD-ROM setup package. After an administrative install is performed, the installation directory and its sub-directories contain the MSI database for the product along with all of the other files required for the actual installation of the product. Members of the network workgroup who want to install the product on their own computers can then do so by running Windows Installer against the MSI file created by the administrative install.

Administrative installs are useful as a learning tool, too. If you want to know what ‚ s inside a particular setup package, simply perform an administrative install to a temporary location on your computer. When the administrative install is finished, the temporary location contains the product ‚ s MSI database plus all of the other files required to install the product. This gives you a tool for deconstructing an MSI setup package and finding out what ‚ s inside without having to actually install the product on your computer.

To perform an administrative install, simply run MSIEXEC using the /a option, like this:

 msiexec /a myProduct.msi 

Applying a patch

A patch package contains information that identifies the product codes to which the patch can be applied. Therefore, when you apply a patch from the command line you do not need to specify the product you are patching, because the patch file itself tells Windows Installer what product(s) it can be applied to.

For example, if myProduct is installed on the computer and MYPRODUCTPATCH.MSP is a patch file that updates myProduct, then you can apply the patch simply by running MSIEXEC

with the /p option, as shown below:

 msiexec /p myProductPatch.msp 

Patches can be applied to administrative installs as well as to local installs of a product. To apply a patch file to an administrative install, use the /a option in addition to the /p option. For example, to patch the administrative install of myProduct we performed above, you use:

 msiexec /p myProductPatch.msp /a myProduct.msi 

Repairing a product

One of the key design objectives of Windows Installer was to make software ‚“self healing, ‚½ or in other words to make it be able to repair itself without having to do a complete uninstall and reinstall. When you run a Windows Installer setup package for a product already installed, one of the choices presented by the Windows Installer user interface is to perform a repair. You can also repair a product by running MSIEXEC with the /f option and specifying the desired parameters. The parameters determine how the reinstall (repair) of the product is performed. Table 4 lists the parameters for the /f option.

Table 4. Parameters for the /f option of the MSIEXEC command line interface

Parameter	Description
a	Reinstall all files
c	Reinstall a file if the file is missing or its checksum is invalid
d	Reinstall a file if the file is missing or if a different version is installed
e	Reinstall a file if the file is missing or if the same or an older version is installed
m	Rewrite all machine-specific registry entries
o	Reinstall a file if the file is missing or if an older version is installed
p	Reinstall a file only if the file is missing
s	Overwrite the existing shortcuts
u	Rewrite all user-specific registry entries
v	Reinstall from the specified source (MSI file) and re-write the local cached package

One common way to repair a product is by running MSIEXEC with the /f option and the parameters ‚vomus. ‚ Looking at the list in Table 4, you can see the ‚v ‚ parameter instructs Windows Installer to perform the install from the specified MSI file and to rewrite the cached package on the local machine. The ‚o ‚ parameter tells Windows Installer to reinstall any missing files, or ones that are present but older. The ‚s ‚ parameter says to overwrite the existing shortcuts, and the ‚m ‚ and ‚u ‚ parameters tell Windows Installer to rewrite the product ‚ s registry entries.

The command line for this type of reinstall is therefore as follows:

 msiexec /fvomus myProduct.msi 

Passing property and value pairs to MSIEXEC

You can also use the command line interface to pass property and value pairs to MSIEXEC. In the example above, you saw how to repair a product by running MSIEXEC with /fvomus. The parameters associated with the /f option correspond to the values associated with the REINSTALLMODE property. Using the command line ‚“Property=Value ‚½ syntax, you can accomplish the same thing as in the previous example by running the following:

 msiexec /i myProduct.msi REINSTALLMODE=vomus REINSTALL=ALL 

As you saw earlier, the /i option says to install the product and names the MSI file from which it is to be installed. REINSTALLMODE=vomus sets the desired values for that property, and REINSTALL=ALL tells Windows Installer to reinstall all the features previously installed.

Some values for the REINSTALLMODE property can be set within the MSI database. For example, you can observe the value ‚omus ‚ in the ReinstallModeText property in the Property table in Figure 6. The value ‚v ‚ must be set externally at installation time, however, in order to tell Windows Installer to use the new MSI file and to rewrite the cached copy of the package. For this reason, it is customary to pass the entire ‚vomus ‚ string to the REINSTALLMODE property at installation time when performing a reinstallation.

Note ‚  

The correct capitalization of Windows Installer property names is important. Windows Installer uses both public and private properties. Public properties have names in all upper case, such as REINSTALLMODE and REINSTALL. Private properties have at least one lower case letter in their names, such as ProductVersion, ProductCode, and UpgradeCode.

Setting property and value pairs when using SETUP.EXE

All of the examples of the MSIEXEC command line interface we ‚ ve looked at are pretty straightforward. You, as a knowledgeable software developer, would have no problem working with your setup at this level, but you probably don ‚ t want to have to teach your users how to do this. (Imagine the phone calls, which would probably start with ‚“What ‚ s a command line? ‚½)

Fortunately, you can automate the process and spare your users the pain of dealing with the details. If you built a CD-ROM setup package, you ‚ ll notice that in addition to your MSI file you get a stub SETUP.EXE file. That SETUP.EXE file has a companion file named SETUP.INI. Among the information contained in SETUP.INI is a CmdLine entry that can be used to pass Property=Value pairs to MSIEXEC. You can modify the CmdLine entry in SETUP.INI and specify the parameters you want to pass to MSIEXEC.

The CmdLine entry appears in the [Startup] section of Setup.INI. It has several other entries as well, as shown in Figure 18 .

Figure 18. Command line parameters can be specified on the CmdLine entry in the Startup section of the STARTUP.INI file. This is the STARTUP.INI file for the small update for version 1.0.1 of the demo app.

To specify the same reinstall actions you used in the command line examples above, you simply modify the CmdLine entry and insert the same Property=Value pairs, as follows:

 [Startup]  CmdLine=REINSTALLMODE=vomus REINSTALL=ALL  

When SETUP.EXE is run, these parameters are passed to MSIEXEC exactly as if you had run MSIEXEC with those parameters from the command line. Note that the SETUP.INI file is rebuilt each time you build the setup, so if you make changes to SETUP.INI you need to remember to make them again after each build.

SETUP.EXE files built with InstallShield Express can accept certain command line parameters. This enables you to set the REINSTALLMODE and REINSTALL properties by passing the desired values directly to SETUP.EXE via the command line. To do this, use the /v option, like this:

  setup.exe /v"REINSTALLMODE=vomus REINSTALL=ALL"  

Some setup development tools, such as InstallShield Developer 8, enable you to create SETUP.EXE files specifically for small updates and minor upgrades that set these flags automatically at installation time. This eliminates the need to use any of the methods described above, and provides the easiest way for the end user to install this type of update.

Install sequence

As noted earlier, the Windows Installer execution sequence is based on a client/server model. We also noted that the entire installation process is treated like a database transaction, in the sense that the entire installation either succeeds or fails as a unit. During installation, the user interface and most of the preparatory tasks are handled by the client process, which runs in the user ‚ s security context. The core installation tasks ‚ installing files, writing registry entries, etc. ‚ are handled by the server process, which can run with elevated privileges in the system security context. On Windows 9x machines, there is of course no difference in the security context of the two sides of the installation process, but the installation sequence is essentially the same.

Windows Installer ‚ s ability to commit or to roll back the installation is accomplished by the server side process. If all of the installation tasks are successfully executed, the transaction is committed and the installation succeeds; if any of the installation tasks fail, the transaction is rolled back and the installation is terminated . Be sure to understand that the use of the word ‚“transaction ‚½ here is simply an analogy: we are not speaking about an actual database transaction, but rather about the entire series of actions performed by the Windows Installer engine to install the product.

Caching the MSI file

Among the results of a successful installation of a product by Windows Installer is the creation of a cached copy of the MSI database on the local computer. The cached copy of the MSI file is required to enable the Modify, Repair, and Remove features of Windows Installer. These files are also required when applying a patch to an installed product.

Under Windows 2000 and later, these cached files are located in the {Windows}\Installer folder. This folder is hidden in order to protect the cached files from being modified or deleted manually. If you want to, you can view this folder in Windows Explorer by turning off ‚“Hide protected operating system files ‚½ on the View tab of the Folder Options dialog. Figure 19 illustrates the contents of the installer ‚ s cached files folder on the machine being used to write this chapter.

Figure 19. The cached copies of MSI files are stored in the {Windows}\Installer folder.

Seeing the contents of the Windows Installer cache folder can be an eye-opening experience. If you have installed a lot of software on your machine you will likely find a large number of MSI and MSP files in this folder, occupying many megabytes of your hard drive space. Hard drive space is pretty inexpensive these days, though, so this is a reasonable price to pay for the capabilities gained in return.

Versioning rules during installs

After all is said and done, the primary function of an installation program is of course to copy files to the computer. This may seem straightforward enough, but can become problematic when another copy of a file being installed already exists in the target location. To handle all of the possible situations it may encounter, Windows Installer operates under a set of rules that determine when a file is replaced and when it is not replaced during installation of a product.

Files have many attributes. Among them are the Create date and the Modified date, which are common to all files. Other files, such as EXEs and DLLs, also have a Version attribute and a Language attribute. Files with a Version attribute are referred to as ‚“versioned ‚½ files, whereas files without a Version attribute are referred to as ‚“non-versioned ‚½ files. Examples of non-versioned files include TXT files, INI files, and ‚ of particular interest to VFP developers ‚ DBF, FPT, and CDX files.

The rules Windows Installer uses to determine whether or not to replace a file during installation are based on the file attributes mentioned above. These rules are referred to collectively as the Windows Installer ‚“versioning ‚½ rules. The versioning rules are actually pretty straightforward; they follow a logical pattern that produces the result most of us would expect. These rules are summarized below.

• If the new file and the existing file are both versioned files, the one with the higher version number prevails. This means, for example, MYAPP.EXE version 2.0 will replace MYAPP.EXE version 1.5, but not the other way around.

• If one copy of a file is versioned and the other copy of the file is not versioned, the versioned file prevails.

• If neither file is versioned, then a file whose Modified date is later than its Create date is assumed to have been modified by the user and is not replaced. If the Modified date is the same as the Create date then the file is assumed to be unchanged since installation and is replaced. Thus a README.TXT file, for example, is always replaced ( assuming it has not been modified by the user), whereas the data files MYDATA.DBF and MYDATA.CDX are not replaced if they have been updated by the user since being installed.

^[7] A complete list of the MSIEXEC command line options can be found in the Windows Installer SDK documentation.