Run-Time Behavior for Installing Multiple Instances of a Product

Project:This information applies to Basic MSI projects.

For information on multiple-instance support for InstallScript projects, see Running an InstallScript Installation Multiple Times.

Running a First-Time Installation that Includes a Setup.exe File

The first time that an end user runs the Setup.exe file for your installation that supports multiple instances, Windows Installer installs the base instance that corresponds with your base installation package without any of the instance transforms. By default, the standard dialogs are displayed, regardless of whether your installation supports multiple instances.

If your product is successfully installed and the end user runs your installation again, the setup launcher displays a dialog that lets them select which instance they want to install. This instance selection dialog is displayed after the language selection dialog, if your installation includes one, but before the InstallWelcome dialog. The dialog contains two radio buttons:

Install a new instance—This option lets end users install a new instance of your product. When an end user selects this option, the new instance of the product is installed.
Maintain or upgrade an existing instance—This option lets end users maintain or upgrade an instance that they select from a list of already installed instances. When an end user selects this option, selects the instance that they want to change, and then clicks Next, the installation displays the following dialogs for the selected instance: the PreparingToInstall dialog, the MaintenanceWelcome dialog, and then the MaintenanceType dialog.

Instance Selection Dialog Displayed the Second Time the Product Is Being Installed

If an end user installs the last supported instance and then runs the installation again, the same dialog is displayed, but the Install a new instance option is disabled. The Maintain or upgrade an existing instance option is selected, and the end user can select the instance that they want to maintain or upgrade.

Tip:To suppress the instance selection dialog, you can use the /instance command-line parameter.

Running an Upgrade Packaged as a Full Installation that Includes a Setup.exe File

When a multiple-instance installation is an upgrade that is packaged as a full installation and that has a Setup.exe file, it behaves as a first-time installation if an end user is installing a new instance by launching the Setup.exe file. If an end user selects the Maintain or upgrade an existing instance option for an already installed instance, the installation lets the end user upgrade or maintain that instance, just as it would for a first-time installation.

Tip:To suppress the instance selection dialog, you can use the /instance command-line parameter.

Launching a First-Time Installation or an Upgrade that Is Packaged as a Full Installation Without a Setup.exe File from the Command Line

When you do not include a Setup.exe setup launcher with your multiple-instance installation, an end user can run your .msi file to install the base instance that corresponds with your base installation package without any of the instance transforms.

In order to install any instance that corresponds with one of the instance transforms in your package, the end user needs to include the appropriate command-line parameters for MsiExec.exe.

For example, the following command line installs a new instance, since the MSINEWINSTANCE property is set to 1. Windows Installer applies the InstanceId1.mst instance transform during installation of the new instance. The colon before the name of the instance transform is required because InstallShield embeds the instance transforms within the .msi file.

msiexec /i MyPackage.msi MSINEWINSTANCE=1 TRANSFORMS=:InstanceId1.mst

Note that the convention that InstallShield uses for naming instance transform files is the property name InstanceId, followed by the instance’s value of the InstanceId property, followed by .mst. Thus, for the instance whose InstanceId property is set to 5, the name of the transform is InstanceId5.mst.

The MSINEWINSTANCE property should be set to 1 only if it is the first time that the end user is installing the specified instance; otherwise, an error is displayed.

To perform maintenance for an instance or to upgrade an instance, use the /n parameter to pass the instance’s product code. For example, the following command line displays the MaintenanceType dialog, which lets the end user specify whether they want to upgrade, maintain, or remove the instance of the product that has the specified product code:

msiexec /i MyPackage.msi /n {00000001-0002-0000-0000-624474736554}

To uninstall an existing instance, use the following format at the command line:

msiexec /i MyPackage.msi /n {00000001-0002-0000-0000-624474736554} /x

Running an Upgrade that Is Packaged as a Patch with an Update.exe File

If you package your upgrade as a patch and you specify that you want to include an Update.exe file, the installation displays the patch version of the instance selection dialog. The dialog contains two radio buttons:

Patch all of the existing instances—This option lets end users apply a patch to all installed instances of your product. When an end user selects this option, Windows Installer applies the patch to each instance separately, until all instances are updated. The instances are updated in order from the lowest InstanceId property value to the highest.
Patch an existing instance—This option lets end users apply a patch to an instance that they select from a list of already installed instances. When an end user selects this option, selects the instance that they want to change, and then clicks Next, the installation displays the PreparingToInstall dialog and then the PatchWelcome dialog.

Tip:To suppress the patch version of the instance selection dialog, you can use the /instance command-line parameter

Running an Upgrade Packaged as a Patch Without an Update.exe File

If you use an .msp file without an Update.exe file for your patch, and the end user runs your .msp file without passing any command-line parameters, Windows Installer behaves as if the end user selected the Patch all of the existing instances option in the patch version of the instance selection dialog: Windows Installer applies the patch to each instance separately, until all instances are updated. The instances are updated in order from the lowest InstanceId property value to the highest.

To apply an .msp patch to a specific instance, pass the /p option, as well as the /n option. The /n option must specify the product code of the installed instance to which the patch should be applied. For example:

msiexec /p mypatch.msp /n {00000001-0002-0000-0000-624474736554}