MSI Installation Design Issues and Best Practices

by Robert Dickau, Principal Technical Training Writer, Flexera Software


To avoid common errors with MSI installation, there are some techniques and design issues that you should be aware of when working with different parts of the Windows Installer (MSI) technology. This white paper provides an overview of the following Windows Installer concepts related to the design of your installation project, which should help you avoid certain types of problems at build and deployment time:

  • Working with features and components
  • Working with files
  • Working with custom actions
  • Working with properties

It also highlights how InstallShield® from Flexera Software assists you in avoiding these problems.

Learn More about InstallShield

If you wish to learn more about the capabilities of InstallShield, please visit the Flexera Software Web site at

Using the InstallShield Environment

This white paper frequently refers to the InstallShield development environment. It is assumed you are familiar with the general layout of the InstallShield interface, which contains a list of views with which you can modify different portions of your installation project.

For example, the General Information view is where you set general product and project properties; the Setup Design view enables you to edit the features, components, and component data used by your project; the Registry view enables you to modify the registry data installed by your installation program; and the Direct Editor view gives you access to the raw MSI database tables.

It is also assumed you are familiar with some of the wizards available with InstallShield, such as the Release Wizard and Component Wizard.

  • The Release Wizard, available under the Build menu and also from the Releases view, lets you describe the properties—media type, compression settings, and so forth—of a release, and then builds the specified release image.
  • The Component Wizard, available by right-clicking a feature in the Setup Design view, lets you create special types of components, such as components for COM servers, fonts, and Windows services.

The InstallShield Help Library contains information about using every view and wizard in the InstallShield environment. The InstallShield Help Library is available when you press F1 with any view selected; you can also select Contents from the Help menu to view the help library.

In addition to the graphical environment, InstallShield provides several tools for modifying and building projects from the command line or an external script. For example, to build a project from the command line, batch file, or other automated process, you can use the executable IsCmdBld. exe. The IsCmdBld executable is located in the System subdirectory of the InstallShield distribution directory.

To rebuild a project, you pass IsCmdBld the project file path, the product configuration name, and the release name that you want to rebuild. A sample command appears as follows:

iscmdbld -p C:\ProductName.ism -a BuildConfig -r ReleaseName

In addition, InstallShield provides an Automation interface, with which you can modify the contents of a project file without using the graphical environment.

Working with Features and Components

Features represent the end user’s view of your installation program, and components represent your view of the installation. Part of your responsibility as the installation designer is to decide how many separately installable pieces of the installation should be presented to the user. Each of these pieces should be a feature or subfeature.

When designing features and components, you should consider the following points:

  • All of the file contents of a component must be installed to the same directory. If application files need to be installed in multiple directories, you must create at least one component for each destination.
  • A component is the lowest level to which a condition can be attached. There is no method for installing only some of the files in a component, or for installing the files but not registry data for a component. If you have data that need to be installed under different conditions—such as different target operating systems or languages—the data must be separated into different components.
  • No resource—file, registry key, shortcut, and so forth—should be placed in more than one component, even across different products and organizations. (Placing the same resource in multiple components breaks Windows Installer reference counting.) Instead, if a resource is required by multiple pieces of the application, you can share entire components among multiple features, or use merge modules to share components among multiple products.
  • As described in the following section, for the most effective file transfer, a component should contain at most one executable or DLL—ideally, a versioned file— and this file should be marked as the key file of its component.
  • Because component and feature names can occasionally be returned in Windows Installer log files, for the sake of maintainability you should give components and features descriptive internal names. In the case of components, one common practice is to name the component after its key path (usually its key file).
  • When there are identical properties for both components and features, the component property is the setting used. For example, both components and features have a Destination property. The feature’s Destination property is the one displayed to the end user in the Custom Setup dialog box, while the component’s Destination property is the one actually used. In the common special case of the values being the same public property (as in INSTALLDIR), the destination selected in the Custom Setup dialog box is passed along to the component.

Working with Files

In order to avoid or troubleshoot unexpected file installation and uninstallation behavior, it is important to understand the file-overwrite rules that Windows Installer uses, along with the standard uninstallation behavior.

File-Overwrite Rules

When deciding whether to install a component, Windows Installer checks only the key path of the component. If the key path does not need to be replaced, the component will not be installed. For this reason, Windows Installer best practices strongly suggest that the key path of each component be a versioned file, and that each EXE, DLL, and help file be placed in its own component and be marked as the key file.

When testing if one file is “newer” than another—by default, a newer file overwrites an older file—Windows Installer uses the following rules:

  • If both files have version resources, the file with the higher version will be installed. Note that if the two files have equal versions, Windows Installer does not check the file dates.
  • If one file has a version resource and the other does not, the versioned file will be installed.
  • If neither file has a version, if the file on the system has identical creation and modification dates, the file in the installer will overwrite it. Otherwise, the file is assumed to contain user data and settings, and will not be overwritten.

Modifying File-Transfer Behavior

Some of the techniques that exist for modifying the default Windows Installer file-transfer behavior for installation and uninstallation are the following:

  • Using the Never Overwrite component setting.
  • Changing the REINSTALLMODE property.
  • Specifying companion-file relationships.
  • Using the Permanent component setting.
  • Using the RemoveFile table to delete files created by your application.

You can modify the Never Overwrite setting in the Components view or the Setup Design view of the InstallShield environment. If you set the Never Overwrite component property to Yes, Windows Installer will skip installing the component if its key file is already present on the target system. If the component’s key file is not present on the target system, Windows Installer will follow the normal file-overwrite behavior.

This is an excerpt. Download the entire pdf: MSI Installation Design Issues and Best Practices