Structure of a Windows Installer setup package

Keep it simple. As simple as possible, but no simpler. ‚ Albert Einstein

Windows Installer setup packages are stored in a file with an MSI extension (we assume MSI stands for Microsoft Installer, although we haven ‚ t actually seen that documented anywhere ). Other file extensions are associated with other kinds of Windows Installer files. Table 1 lists some of the common Windows Installer file extensions.

Table 1. Common file extensions used by Windows Installer.

File Extension	File Description
.msi	Windows Installer database
.msm	Windows Installer merger module
.msp	Windows Installer patch file
.mst	Windows Installer transform

To understand what ‚ s inside an MSI file, you need to know something about how the different parts of an application are organized in a Windows Installer setup package. Some new terminology needs to be introduced here. First, you should start thinking of your application as a ‚“product. ‚½ Windows Installer installs , updates, and uninstalls products. Products have names , version numbers , and other attributes that identify them and distinguish them from other products. We ‚ ll discuss many of these attributes in some detail later in this chapter. The first thing to know about products, though, is they are made up of features and components .

Features and components

Features and components are the fundamental organizational elements of a product in a Windows Installer setup package. Features are the functional parts of a product as seen from the end user ‚ s point of view ( Figure 2 ). Components, on the other hand, represent the structural parts of the application as seen from the developer ‚ s point of view. Both features and components are logical containers. Inside a Windows Installer setup package, they are arranged to form a hierarchy: a product consists of one or more features, a feature consists of one or more components, and a component consists of one or more resources.

Figure 2. In Windows Installer, a product consists of one or more features, as illustrated by Microsoft Office. Some of the features may have sub-features. Behind the scenes, each feature consists of one or more components.

If you are going to deploy your product using Windows Installer, you will by necessity have to start thinking about your application in terms of features and components. This may seem strange and unfamiliar at first, and you may be tempted to put it off until you ‚ re forced to deal with it at deployment time. You will be much better off to adopt this view of your application when you first begin designing it, however, because if you wait until deployment time you may well find yourself wishing you had done things differently.

Features

A feature is a functional piece of a product. For example, one feature might comprise your application ‚ s main executable file and its related files such as INI files, DLLs, FLLs, etc. A second feature might be the application ‚ s Help file(s), and a third feature might be a module to generate PDF output.

Some features may be required while others may be optional. This decision is made by the setup developer in conjunction with the application developer. In the example from the previous paragraph, the first feature would be required while the other two features could be optional. If a custom installation is performed, Windows Installer allows the end user to decide whether or not to install one or both of the optional features.

A feature is a logical container for one or more components. A given component, however, can be part of more than one feature. If the user elects to install two features that both require the same component, the component is installed only once. For example, if two features in a VFP application each have an HTML Help file, both features require the HTML Help runtime library component. If both features are installed, however, the HTML Help runtime library is installed only once.

Components

Of the three logical containers ‚ products, features, and components ‚ components are the lowest level. A component contains ‚“resources, ‚½ as they are referred to in Window Installer terminology. A resource might be a file, a shortcut, or a registry entry for example. Windows Installer treats components as a unit: either all the resources in a component are installed, or none of them are installed.

A component typically consists of one or more files ‚ an EXE or a DLL, for example ‚ along with any corresponding shortcuts and registry entries. One resource in a component can be designated as the keypath . Windows Installer uses the keypath to determine whether a component installed properly or not. If the keypath resource is missing, Windows Installer treats the component as broken and attempts to repair it.

As mentioned earlier, a component may be part of more than one feature within an application. Moreover, a particular component may often be part of more than one product. For example, suppose you write a super-strength encryption algorithm for securing user passwords. You might compile this as a DLL and include it in several of your applications. Some of your customers may install more than one of your applications, but your encryption DLL would be the same in each application. In your applications ‚ installation setup, you would include your encryption DLL as a component and associate that component with the feature(s) of your application that require it.

When you build your Windows Installer package, each component is assigned a unique code called its component code . A component code is a GUID (Globally Unique IDentifier). Because GUIDs are globally unique, Windows Installer is guaranteed that a particular component code identifies a specific component and only that component. At installation time, Windows Installer can use the GUID to determine if a component is already installed. If so, it knows the component does not need to be installed again. The same principle applies when a component is part of two or more features in the same product: the component code allows Windows Installer to figure out the component needs to be installed only once.

Merge Modules

A word about merge modules is in order here. As you have seen, a given component may be common to more than one feature in an application, and may be used by more than one application on a given computer. Not only that, but a component may be used and distributed by more than one developer.

The Visual FoxPro Runtime Libraries are a good example of this. When you ship your VFP application, you also typically ship the VFP runtime files. When you construct your Windows Installer setup package, it assigns the components in that package a unique component code. What would happen if new and unique component codes were assigned to the VFP runtime files each time a developer ‚ any developer ‚ included them in a deployment package? When Windows Installer installs your product, it would have no way of determining whether or not the VFP runtime component was already installed by another product. Too much uniqueness is not a good thing.

Merge modules were invented to handle this situation. A merge module is a special kind of Windows Installer file used to redistribute a component or components common to more than one product. A merge module is essentially a product with no features. Merge modules are packaged as a file with an MSM file name extension. They cannot be installed on their own, but must be merged into another product ‚ s MSI setup package.

Component codes are assigned to the component(s) in a merge module at the time the module is constructed by its author or vendor. (In the case of the VFP runtime files, the author of course is Microsoft.) When you include a merge module in your Windows Installer setup package, its existing component codes are retained. The component codes of the components in a merge module are therefore the same for everybody who uses it, and so Windows Installer can determine whether or not a particular component is already installed even if that component was installed by different product at a different time.

Inside an MSI file

(Example: DFCHAPTER5_MSI100.ZIP) ^[1]

A Windows Installer setup executable contains several elements, of which the MSI file is the one of primary interest to us here. The MSI file comprises the Windows Installer database for the product. A Windows Installer database is a relational database, which makes it familiar territory for VFP developers. Although the physical structure of an MSI file is nothing like the structure of a VFP database ‚ in fact, an MSI file is a COM Structured Storage file ‚ we nonetheless find the logical structure of a Windows Installer database is based on the familiar concepts of tables, rows, columns , primary keys, and foreign keys.

Sample application

In order to have something consistent to work with throughout this book, we put together a sample VFP application called the DeployFox Demo App. The application doesn ‚ t do much ‚ it just opens a table of customer information and displays it in a browse window ‚ but the focus of this chapter isn ‚ t on what an application does, but rather how to deploy it with Windows Installer. Working with a very simple application makes it easier to concentrate on the deployment side of things.

Earlier in this chapter we encouraged you to start thinking about your application in terms of features and components from the beginning of the design phase. Following our own advice, we decided to organize our sample application into three features:

• the main program

• the Help file

• the sample data files

The first feature comprises the application ‚ s core functionality, and therefore we want that feature always to be installed whenever this product is installed. The other two features are useful but not required; the user can decide whether or not to install them, so they are optional.

We also noted that features consist of one or more components. So the next step is to think about how this applies to the sample application and determine the files and other components that belong in each of our application ‚ s three features.

The main program feature

The first feature installs the DeployFox Demo App main executable, so the key component of this feature should be the application ‚ s EXE file. Because this is a Visual FoxPro application, the EXE file requires the Visual FoxPro runtime support libraries. The VFP runtime support files may already be installed on the user ‚ s computer, but we can ‚ t assume this is the case so we need to include them as part of the setup package. To do this we simply include the Visual FoxPro Runtime Support Libraries merge module, VFP8RUNTIME.MSM, in the setup package and associate it with this feature.

The VFP Runtime Libraries for VFP 7 and VFP 8 require the Microsoft Visual C++ Runtime DLL MSVCR70.DLL. This file is in its own merge module, MSVCR70.MSM, which also needs to be added to the setup package as part of the main program feature. VFP 8 further requires the Graphics Device Interface Plus (GDI+) component GDIPLUS.DLL. This file is located in the VFP_GDIPLUS.MSM merge module, and it also needs to be included.

To demonstrate installation of an ActiveX control, the demo app uses the slider bar control from MSCOMCTL.OCX. The merge module for this ActiveX control is MSCOMCTL.MSM that in turn brings in a couple of dependencies, COMCAT.MSM and OLEAUT32.MSM.

The main program feature also includes the README.TXT file. The README.TXT file is a simple text file with no dependencies (we assume NOTEPAD is already installed on the user ‚ s computer). It could be argued that the README.TXT file should be part of the Help feature; this is certainly a valid point of view, and illustrates ‚ in very simplistic terms ‚ the kind of decision you need to make as a setup developer. In the case of our sample product, we assume the README.TXT file contains information we want our users to have access to regardless of whether they install the Help feature, so we make it part of the first feature.

The Help file feature

The second feature consists of the Help file for our product. This is an HTML Help file, so when this feature is installed we also want to install the Visual FoxPro HTML Help redistributable files. Our second feature should therefore include the merge module for the Visual FoxPro HTML Help Support Libraries, VFP8HTMLHELP.MSM. Again, this is something of a design decision; we could have decided to include the HTML Help Support Library in the first feature, along with the VFP runtime support libraries, but because the HTML Help support files are needed only if the Help file itself is installed, it makes sense to put them in the same feature as the Help file.

The sample data feature

The last feature in the application is the sample data files. This is nothing more than the Customers table, CUSTOMERS.DBF, and its index file, CUSTOMERS.CDX. These files do not have any external dependencies, so nothing else needs to be included in this feature.

Figure 3 illustrates the organization of the demo application into the features and components described above.

Figure 3. The components of the DeployFox Demo App are organized into three features.

Creating the MSI file

Now that we ‚ ve conceptualized our application, the only thing remaining to do is to write it and deploy it. We already know how to write applications, so let ‚ s imagine that ‚ s already done and move right into deployment.

On The Web ‚  

The DeployFox Demo App, along with all of the MSI files discussed in this chapter, are included in the downloads for this book. The files named DFCHAPTER5_MSIXXX.ZIP (where xxx is the version number) contain only the MSI file. These files are small and can be quickly downloaded, but cannot be used to actually install the demo app. Also available for download are complete setup packages named DFCHAPTER5_CDROMXXX.ZIP; these are large downloads and contain all the files necessary to install the various versions of the demo app.

At this point, you would use your favorite Windows Installer-based setup tool to create the setup package for the application. Because you already organized your application into features and components, creating the deployment package doesn ‚ t require any heavy lifting ‚ it ‚ s simply a matter of putting the pieces in the right places, and then telling the setup tool to build the deployment package.

The mechanics of doing this vary somewhat from tool to tool. There are several appendixes in this book that cover the specifics for some of these tools. The important thing for our purposes here is, regardless of the particular tool you use, when you ‚ re done you have an MSI file that describes your installation requirements to Windows Installer.

The files created by the setup tool depend on the type of setup package you choose to build. If you choose a single-image deployment configuration, the MSI file for your installation is embedded inside the setup launcher file SETUP.EXE. Other types of build configurations, such as CD-ROM, create the MSI file separately. The CD-ROM type of deployment configuration may or may not be preferable for the actual distribution and installation of your product, but because it creates the MSI file separately it is preferable for learning purposes. Figure 4 shows the directory structure of the CD-ROM build for the sample application. The MSI file is found in the DISK1 directory.

Figure 4. The directory structure of the CD-ROM build of the demo application shows how the product will be installed on the user ‚ s computer.

The shaded area in Figure 4 is the directory structure of the sample application as it will be installed on the user ‚ s computer. Note that with a couple of exceptions, everything is installed under the Program Files directory: the application ‚ s files go in Program Files\Deploy Fox\Chapter 5\DemoApp, while the VFP runtime and HTML Help support libraries, as well as the GDI+ DLL required by VFP 8, go in Program Files\Common Files\Microsoft Shared\VFP\. ^[2] Of course, on the user ‚ s computer the Program Files directory is under C:\, not under the My Setups directory structure shown here.

One exception is the Microsoft Visual C++ 7.0 Runtime DLL, MSVCR70.DLL, which is targeted for the Windows system folder. MSVCR70.DLL is required for both VFP 7 and VFP8, but not for VFP 6. Another exception is the ActiveX control MSCOMCT2.OCX and its dependencies, which also go in the system folder.

Exploring the MSI file

Now that the MSI file has been created, it ‚ s time to go exploring and see what ‚ s inside. As noted earlier, we can use Orca for this purpose. We start with the Summary Information that provides general information about the file such as its title and author, and then take an in- depth look at several of the MSI data tables to see how the conceptual structure of the application is reflected in the physical structure of the setup database.

Note ‚  

Rule number one for poking around inside an MSI file with Orca is this: remember Orca is an editor as well as a viewer. If you make any changes to the MSI database ‚ either inadvertently or deliberately ‚ you may render it unusable. Of course, if the MSI file is one you created yourself then you can simply rebuild it, but if it ‚ s from another source and you can ‚ t recreate it yourself, it ‚ s a good idea to make a backup copy before you begin exploring.

Summary Information

When you open an MSI file in Orca, one of the first things you may want to do is view the summary information. To do this, choose View Summary Information from the main menu. The summary information for our sample application is shown in Figure 5 .

Figure 5. The Summary Information of an MSI file can be viewed in Orca.

Note that although you accessed it from a ‚View ‚ menu, Orca ‚ s Summary Information window is in fact an edit window. You can use this edit window to change any of the information shown. Most of the fields in the Summary Information window are self explanatory, but two of them deserve comment: the Package Code and the Schema.

The Package Code is a GUID that uniquely identifies the particular MSI file. This GUID is typically assigned by the setup tool when the setup package is built. As you will see later on, the package code should change every time the package is rebuilt. The package code, along with many of the other fields in the summary information stream, can also be seen from Windows Explorer by viewing the MSI file ‚ s property sheet. An example of this is shown in Figure 12 in the section on GUIDs later in this chapter.

The value in the Schema field identifies the minimum version of Windows Installer required to process the MSI file. The format of this field is major version number times 100, plus minor version number, so a value of 100 indicates Windows Installer version 1.0 and a value of 200 indicates Windows Installer version 2.0.

MSI database schema

We already mentioned an MSI database is a relational database. As you might expect, there are many tables in this database; in fact, the Windows Installer database schema consists of 84 permanent tables and 7 temporary tables. In this chapter we concentrate on the ones that contain information about the product itself and about its features, components, and the target location for the files to be installed on the local computer. This list includes the following:

• The Property table contains the global variables for the installation, including the product name, the product version, the product code, and the upgrade code.

• The Feature table has one row for each feature defined in the installation. Some products are organized so certain features are sub-features of other features. In that case, the child feature ‚ parent feature hierarchy is also described by this table.

• The Component table has one row for each component in the installation. Among the columns in this table are the component name, the component code (GUID), and the component ‚ s keypath.

• The FeatureComponents table is a bridge table that implements the many-to-many relationship between features and components.

• The Directory table identifies the target directories for everything to be installed.

• The Upgrade table carries the information required to enable Windows Installer to perform major upgrades of a product.

Property table

When exploring the tables in an MSI file for the first time, the Property table is a good place to start. In the Property table you find the name of the product along with other important identifying information. Figure 6 shows the Property table from the MSI file for the sample application.

Figure 6. The Property table is a good place to start when exploring an MSI file.

Navigating inside an MSI database in Orca is simple: click a table name in the left pane to display its contents in the right pane. Click a column header in the right pane to sort the display by the values in that column. In Figure 6, we clicked the Property column header so the properties are listed alphabetically .

Find the ProductName property in the right pane. Also find the ProductVersion property and the two GUIDs, the ProductCode and the UpgradeCode . We talk about the importance of these three items in the next section.

Feature table

Next take a look at the Feature table. You know the sample application is organized into three features, so you would expect to find three features in the Feature table of the MSI file. And in fact you do, as shown in Figure 7 .

Figure 7. The Feature table contains one row for each feature in the product.

The first column, Feature , is the primary key for this table. The values in this column are the primary key values for this table and are created by the setup tool according to the naming conventions for Windows Installer. The Description column contains the names we chose for each feature when we configured this installation.

In an MSI database, column names with a trailing underscore character ( _ ) are foreign keys. In the Feature table in Figure 7, notice the trailing underscore in the name of the Directory_ column. This identifies the values in this column as foreign keys to the Directory table. The values in the Directory_ column tell Windows Installer where to look in the Directory table to find the target folder for each feature.

You may also notice the underscore character in the name of the Feature_Parent column. The values in this column refer back to the primary key for other rows in the Feature table itself. This provides a mechanism for implementing the child-feature / parent-feature hierarchy, which is used if the application is organized into sub-features.

The Display column determines the order in which features display in the Custom Setup dialog during installation. If a feature has sub-features, the value in this field also determines whether the feature tree for this feature displays as expanded or collapsed: odd values mean it displays as expanded, even values mean it displays as collapsed .

A value of zero in the Display column means the feature does not display at all. Why would you want to not display a feature? An example is provided by InstallShield Express, which forces one feature to be the ‚“Always Install ‚½ feature. By default, this ‚“Always Install ‚½ feature gets a Display value of zero, meaning it does not show up in the feature tree when a Custom Setup is chosen . If this feature has sub-features, they won ‚ t show up in the Custom Setup dialog either.

Component table

Knowing the components that comprise the sample application, you can guess what is in the Component table, too. The Component table for the sample application is shown in Figure 8.

Figure 8. Each component in the product has a row in the Component table.

The Component column is the primary key for this table. With the exception of the merge module components, the values in the primary key field of the Component table were created by the setup tool.

Many things are apparent as you investigate the Component table. You can spot not only the keypath files for the sample application itself, DEMOAPP.EXE and DEMOAPP.CHM, but also the VFP Runtime Libraries files and the VFP HTML Help Support Library files. These are the components brought into the setup package via the merge modules.

In the second column you can see the component code GUIDs for each component in the package. In the third column you find a foreign key to the Directory table, and in the KeyPath column on the far right you can see the keypath resource for the component.

Feature_Component table

The Feature_Component table is a bridge table that implements the many-to-many relationship between features and components. As you would expect in a many-to-many bridge table, it consists of nothing more than pairs of foreign keys to the two tables involved in the relationship. The Feature_Component table for our Demo App is shown in Figure 9 .

Figure 9. The Feature-Components table relates each component to the feature(s) with which it is to be installed.

Looking at the relationships established by the Feature_Component table in Figure 9, you can see, as intended, the application ‚ s EXE file and the VFP Runtime Libraries files are associated with the ‚“Always Install ‚½ feature, whereas the Help file and the VFP HTML Help Support Library files are associated with the feature whose primary key is ‚“NewFeature2. ‚½ If you look back at the Feature table in Figure 7 and find the feature named NewFeature2, you see, as expected, it is the ‚“Help files ‚½ feature. Similarly, you can trace the ‚“NewFeature1 ‚½ foreign key back to the ‚“Data files ‚½ feature.

Directory table

The last table we look at here is the Directory table. This is one of the more complex tables in the database, and even a simple installation such as the Demo App involves many more directories than you might think. In addition to the target directory for the application itself, there are other entries including the locations of the Program Files directory, the Start menu, the user ‚ s Desktop folder, and of course Windows itself. On top of that, this table describes the hierarchical structure of directories and sub-directories for the installation. Finally, many if not all of its values in the Directory table need to be resolved at installation time because their final value depends on factors such as the directory the user chooses to install the product in as well as the version of Windows running on the target computer.

The Directory table for the Demo App is shown in Figure 10 . The columns are displayed in their natural order.

Figure 10. The Directory table determines where files are to be installed.

Two things to notice when looking at the Directory table in Figure 10 are the row for the ‚“DeployFox ‚½ directory and the row for the ‚“Data ‚½ directory. The ‚“DeployFox ‚½ directory entry points to the default installation directory for the application as we specified it in the setup program, which is \ProgramFiles\DeployFox\Chapter5\DemoApp. Because it involves subdirectories, more than one row in the Directories table is involved in identifying this directory. You can trace it through as follows , starting with the lowest level:

• The DEMOAPP1 row has a default value of ‚“DemoApp ‚½ and identifies CHAPTER5 as its parent directory.

• The CHAPTER5 row has a default value of ‚“Chapter5 ‚½ and identifies DEPLOYFOX as its parent directory.

• The DEPLOYFOX row has a default value of ‚“DeployFox ‚½ and identifies ProgramFilesFolder as its parent directory.

• The value of the ProgramFilesFolder row points to the physical location of the Program Files folder on the user ‚ s computer.

Thus, at installation time, Windows Installer can resolve the default location for the application to be Program Files\DeployFox\Chapter5\DemoApp.

You can also look in the Directory table and find the location of the sample data files that will be installed in a Data sub-directory under the application ‚ s main directory. Find the row named DATA in Figure 10 and you see it points to a directory named Data whose parent is INSTALLDIR. The value of INSTALLDIR is resolved at installation time to the physical directory where the user chooses to install the application. Thus the sample data files, if installed, are copied to the Data sub-directory under the directory where the application itself is installed, wherever that might be.

Other tables

There are many other tables in the MSI database besides the ones described above. In addition to the tables that are part of the basic schema, Windows Installer allows third-party products like InstallShield to add their own custom tables to the database. Looking at the lower left corner of Figure 10, for example, you can see there are a total of 101 tables in the database for the sample application.

Among the other tables you might be interested in exploring are the File table, the Registry table, and a pair of tables that control the sequence of steps during the installation process. The File table and the Registry table are fairly self-explanatory. The InstallExecuteSequence table and the AdminExecuteSequence table may need a little explanation.

Both the InstallExecuteSequence table and the AdminExecuteSequence table contain a row named Sequence. The values in the sequence table determine the order in which the steps are processed . When you explore these tables in Orca, click on the Sequence column header to sort the rows in the order the steps are executed.

Figure 11 shows a portion of the AdminExecuteSequence table for the chapter ‚ s sample application. You can get a pretty good sense of what ‚ s going on just by reading the names of the rows in this table and seeing the order they ‚ re executed. Note that the sequence numbers are integer values and are generally multiples of 100. The basic steps and their sequence numbers are defined by the MSI database schema; the purpose of numbering them by multiples of 100 is to leave room to insert other steps if necessary.

Figure 11. The AdminExecuteSequence table shows the steps taken during the core portion of the installation sequence.

One other table that needs to be mentioned here is the Upgrade table. This table is empty for a fresh install ‚ in other words, for the first release ‚ of a product, but when you distribute subsequent versions of your product in the form of major upgrades this table contains the information that determines how Windows Installer handles your upgrade. You ‚ ll find more information about major upgrades and the Upgrade table later in this chapter in the section on ‚“Upgrades, Updates, and Patches. ‚½

Now would be a good time for you to open an MSI file in Orca and look around on your own. Use one of the MSI files for the sample application that accompanies this chapter, or pick another file you are familiar with. Again, remember Orca is an editor as well as a viewer, so be sure you have a current backup before experimenting with changes to the MSI database.

GUIDs, GUIDs, everywhere a GUID

‚“ Signs, signs, everywhere a sign ‚ Do this, don ‚ t do that, can ‚ t you read the sign ‚½ ^[3]

In the real world we rely on signs to identify places and things (Chicago City Limits; Golden Gate Bridge), to tell us where we are in relation to places we know or can identify on a map (Redmond ‚ 5 miles), and sometimes even to tell us what to do or not do (Merge Left, Do Not Pass). In the world of an MSI package, the Windows Installer service relies on GUIDs ‚ Globally Unique IDentifiers ‚ for the same purposes. GUIDs identify installation packages and the components they contain, allow Windows Installer to recognize things in the installation package that relate to things it may already know about, and tell Windows Installer what to do in order to processes the contents of the installation package.

GUIDs in a Windows Installer package are the same as GUIDs you are used to seeing in other contexts: they are 128-bit (16-byte) integer values, commonly written and displayed as a hexadecimal character string in the familiar format with curly braces and dashes, as in {AE17EAA0-6859-11D7-803D-A71AFC909D6E}. In Windows Installer GUIDs all characters are uppercase. The value of a GUID has no intrinsic meaning. All that matters is it ‚ s unique to whatever it identifies.

There are three important GUIDs you should know about: the package code , the product code , and the upgrade code . These GUIDs are established by the installation developer (or by the setup tool) at the time the setup package is first created for a product, and, with the exception of the upgrade code, may need to be changed whenever the package is subsequently modified. These GUIDs are important because they control how Windows Installer processes the setup package when installing the product.

In addition to the GUIDs, there is one other important identifier you need to be aware of as a developer, namely the product version . This refers not to the version number you may assign to the main EXE of your application, but rather to the value you assign to the ProductVersion property of the MSI setup package. You ‚ ll learn more about the importance of the product version when we discuss upgrades and updates later in this chapter.

Package code

The package code, not surprisingly, identifies the MSI installation package and distinguishes it from all other MSI installation packages. Each MSI package should have a unique package code, so you should change the package code each time you change the contents of your installation package. Failing to do this can lead to failed installs and frustrated users. (See ‚“Common problems and what to do about them ‚½ later in this chapter.) Fortunately, most Windows Installer-based setup tools automatically change the package code each time you build a release.

The package code is the only one of the three GUIDs that can be viewed externally, i.e., without opening the MSI file. To view the package code for an MSI file, select the file in

Windows Explorer, display the file ‚ s property sheet, and select the Summary page ^[4] . The package code GUID is shown as the ‚“Revision Number, ‚½ as you can see in Figure 12 .

Figure 12. The package code GUID is shown as the ‚Revision Number ‚ on the property sheet of an MSI file.

In Windows 2000 and Windows XP the property sheet is also an edit window that allows you to change certain properties. Note the pencil icon next to the Revision Number field and other fields in Figure 12. The fields marked with this icon can be edited directly from the property sheet.

Upgrade code

The upgrade code is the ‚“master ‚½ code for the product. It should remain unchanged for all versions of a product throughout its lifetime. Think of the upgrade code as the product ‚ s family name: all products with the same upgrade code are part of the same family, and the upgrade code, just like a family name, remains the same over several generations.

When performing an installation, Windows Installer uses the upgrade code to determine whether or not a previous version of the same product is already installed on the computer. This allows Windows Installer to determine whether the product is brand new to the computer (a fresh install), or whether it is a different version of a product already installed on the computer (an update or an upgrade).

Product code

From its name, you might think the product code would fulfill the role we just described for the upgrade code. The product code, however, actually identifies the particular version of the product. In general, the product code should be changed whenever a new version of an existing product is released. When a new version of an existing product is released, any versioned files ‚ such the primary EXE file ‚ that changed from the previous release should receive a new version number (for example, MYAPP.EXE version 1.0.0 becomes MYAPP.EXE version 1.0.1). A rule of thumb is you should change the product code of the MSI package whenever you change the version number of your application ‚ s main EXE file. The full set of rules governing when the product code should be changed can be found in the Windows Installer SDK documentation.

Component codes

In addition to the three GUIDs described above, Windows Installer also relies on GUIDs to identify the components contained in an MSI package. Components may be common to more than one application, and whether they come from you, from Microsoft, or from some third party, they should have the same component code in all Windows Installer packages in which they are used. This is only logical: if another product installs a common component your application already installed, or vice versa, Windows Installer needs to be able to recognize that the component is already present on that computer and therefore it should simply increment the component ‚ s use counter rather than installing the component again. The way Windows Installer recognizes a component is by its component code.

Product Version

Unlike the product code, the upgrade code, and the package code, which are GUIDs, the product version is a simple numeric string in the familiar format of major.minor.build . The value of the major and minor version number can range from 0 to 255. The value of the build number can be between 0 and 65,535.

Windows Installer uses only the first three segments of the product version. If a fourth segment is present, as in 1.00.00.310, Windows Installer ignores it.

The purpose of the product version is to provide additional information to Windows Installer beyond what is provided by the other three codes. When performing an upgrade or an update, Windows Installer uses the product version number in conjunction with the three GUIDs to determine how the new setup package relates to any previously installed versions of the product.

You should always change the product version of the MSI file when you release a new setup package into the wild. Whether you change the build number, the minor version number, and/or the major version number depends on what type of upgrade you are releasing. The main thing to remember is not to distribute a release of your product using the same product code, upgrade code, and product version you used in a previous release or problems can result.

As a VFP developer, you are probably accustomed to assigning a version number to your application when you build it from the VFP Project Manager. The version number you assign to your application ‚ s EXE file in VFP, however, is separate and distinct from the product version you assign to your product in its MSI database. It is not necessary that the product version in the MSI setup package be the same as the version number of the main EXE in the application. In other words, the value you put in the ‚“major, ‚½ ‚“minor, ‚½ and ‚“revision ‚½ fields of the Version window of the VFP Build Options window does not need to be the same as the value you enter into the ProductVersion property in your Windows Installer setup package. Unless there are good reasons to do otherwise , though, it makes sense to us to keep these two the same, if only for the sake of consistency.

This does not mean the version number you assign to your application ‚ s EXE file is irrelevant to Windows Installer. The version number of your application ‚ s EXE file is important because it ‚ s part of the versioning rules Windows Installer uses when determining which files to replace during installation of a product. See ‚“Versioning rules during installs ‚½ later in this chapter for details about how this works.

Finding the GUIDs in an MSI file

As we saw in Figure 12, the package code GUID for an MSI file can be seen simply by looking at the file ‚ s property sheet. The other two GUIDs ‚ the upgrade code and the product code ‚ are not exposed in this manner, but are nonetheless easily viewed by opening the MSI file in Orca. Both of these GUIDs are stored in the Property table of the MSI database, as shown in Figure 13 .

Figure 13. An MSI database open in Orca with the Property table selected. The product code GUID and the upgrade code GUID are highlighted. This is the MSI file for the Windows Installer Clean Up utility mentioned later in this chapter.

Setting GUIDs and product version

Setting the appropriate values for the setup package GUIDs is the responsibility of the setup developer. If you are using a Windows Installer-based setup tool, that tool should provide a way for you to enter or change the Upgrade Code and the Product Code for your product. It probably also changes the Package Code for you automatically every time you build a release. If necessary, though, you can use Orca to view and edit these GUIDs directly.

It is also your responsibility as the setup developer to update the product version number for each release of your application. Most if not all Windows Installer-based setup tools provide a way for you to do this from within the tool, but as with the GUIDs you can also view and edit the product version with Orca. The product version is stored in the ProductVersion property of the Property table, as you can see in Figure 13. Remember that Windows Installer uses only the first three segments of the product version, so in the example in Figure 13, product version 1.0.0.310 is equivalent to version 1.0.0 as far as Windows Installer is concerned .

^[1] For size reasons, this download includes only the MSI file itself. It is not a complete setup package and cannot be used to actually install the demo app. The MSI file is provided so you can open and inspect it with Orca and relate its contents to what you see in the chapter. A full setup package is also available for download as DFCHAPTER5_CDROM100.ZIP.

^[2] This location for the VFP runtime and HTML Help support libraries applies to VFP 7 and VFP 8. Under VFP 6, all of the runtime support files are installed to the system folder.

^[3] From the hit song Signs , ‚ 1970, 2002 Five Man Electrical Band

^[4] The appearance of and the arrangement of information on the property sheet of an MSI file depends on which version of Windows is being used. All figures in this chapter were captured under Windows 2000 Professional.