What is Transform?

MSI Transform is a collection of specified changes in the form of .mst files, which one apply to a base Windows Installer package file at installation time. When one applies transforms to an .msi file, Windows Installer can dynamically add or modify data in the installation database, customizing the installation of the application. Transforms tailor the installation of an application.

The four types of Windows Installer transforms are embedded, unembedded, secured, and unsecured.

Embedded transforms : (MSI Transform)

Embedded transforms are stored inside the .msi file of the package. This guarantees to users that the transform is always available when the installation package is available. If the installation source is read-only, such as a CD or a network share to which the person creating the transform has read-only access, this is not an option because one must be able to write to the source to embed the transform in the *.msi file. To add an embedded transform to the transforms list, add a colon (:) prefix to the file name. Embedded transforms are not cached separately on the client computer, because Windows Installer can always obtain the transform from the .msi file. Embedded transforms might be used in combination with secured or unsecured transforms.

Unembedded transforms :

Unembedded transforms are stored separate from the .msi file of the original package. Unembedded transforms are cached separately on the client computer. One can use unembedded transforms in combination with secured or unsecured transforms.

Secured transforms:

Securedtransforms are recommended for security reasons. If an application is installed at an elevated level, either per-user or per-computer, a user with low rights can modify an unsecured transform and use it to make changes to the computers that have elevated privileges. Secured transforms are stored locally on the client computer in a location where, on a secure file system such as NTFS, the user does not have write access. Such transforms are cached in this location during the installation or advertisement of the package. During subsequent installation-on-demand or maintenance installations of the package, Windows Installer uses the cached transforms.

To specify secured transform storage, set the TransformsSecure policy, or set the TRANSFORMSSECURE property, or pass the @ or | symbol in the transforms list.

Note: One cannot combine unsecured transforms and secured transforms in the same TRANSFORMS list.

If a user removes the product, Windows Installer removes all secured transforms for that product from that user’s computer. If Windows Installer finds that a secured transform is not locally available, it then attempts to restore the transform cache from a source. Secure transforms can be secure-at-source or secure-full-path:

• Secure-At-Source transforms that are missing from the local transform cache are restored from the root of the source of the .msi file.
• Secure-Full-Path transforms that are missing from the local transform cache are restored from the original full path specified by the transform list.

Unsecured transforms

Unsecured transforms have not been secured as described in Secured Transforms in the preceding list. When a package is installed or advertised as a per-user installation, and the package has unsecured transforms, Windows Installer saves the unsecured transforms in the Application Data folder in the user’s profile. This enables a user to maintain a customization of a product while roaming from computer to computer. When the package is installed or advertised as a per-computer installation, and the package uses unsecured transforms, Windows Installer saves the unsecured transforms in the %windir%\Installer folder. If the cached copy of the transform becomes unavailable, Windows Installer can restore the transform cache using a source listed in the SOURCELIST property. Windows Installer uses the same method to search for a transform source as it uses to search for an .msi file. To apply unsecured transforms when installing a package, pass the transform file names in the TRANSFORMS property or in the command-line string, and do not begin the string with the @ or | characters. Do not set the TransformsSecure policy or the TRANSFORMSSECURE property.

Why to use transforms

Command-Line Options versus Transforms

The major differences in functionality between customizing an application by using transforms, and customizing it by using the command line follow:

• A transform is persistent until the application is removed; as command-line actions apply only to the specific execution of the command line.
• Transforms can modify both public and private properties; command-line options for Windows Installer can only affect public properties. See the Windows Installer SDK for a complete list of public and private properties.
• Both transforms and Windows Installer command-line options can affect directories and files; only transforms can perform actions that affect the registry.
• The Group Policy-based software deployment technology of Windows .NET Server and Windows 2000 Server requires that transforms be used for any customization of applications. One cannot use command-line arguments.

How to apply transform to an .MSI file

One can apply a transform to an .msi file by one of two methods: dynamic and static.

Dynamic method:

Place the transform on the same share as the .msi file, and configure installation options to reference that transform. One can use this method where multiple sets of customizations exist for users in an organization and where the application vendor might need to update or patch the original .msi file. Keeping the customizations separate from the original package helps to isolate them from changes to the original .MSI.

Static method:

Run the transform against an administrative image of an application to permanently change the .msi of the administrative image. The customizations the transform initiates are persistent until the administrative image is deleted and recreated. Because of this, applying a transform by this method is does less often.

Most often one applies a transform to the base .msi file dynamically at deployment time. By applying the transform at installation, the administrative image’s *.msi file is unchanged, even though one have tailored the installation of the application to meet the needs of the organization. The customizations that the transform initiates are persistent until the user uninstalls the application and subsequently reinstalls it.

When to create a transform?

Encapsulating numerous customizations of a base package required by different groups

For example, in organizations where the Finance and Marketing departments require different installations of a product, one can make the product’s base package available to everyone at one software distribution point by distributing the appropriate customizations to each group of users separately as transforms.

Adding new features to an existing application’s package

One example is adding custom corporate-developed Microsoft Excel templates for the Finance group. However, if the templates change frequently, it is better to package and distribute them separately.

Customizing

This can involve configuring installations so that a particular set of features from a specified software application, or suite of software applications, is installed locally on the computer.

A few of the more common tasks one can perform on an application by using a transform instead of a command-line option follow:

• Specify the install state of a feature: Advertised, Run Locally, orRun from Source.
• Make a feature unavailable and invisible to the user.
• Add, modify, or remove shortcuts.
• Modify the upgrade behavior.

Authoring Multiple Instances with Instance Transforms

To install multiple instances of a product from one Windows® Installer package, one need to author a base installation package for the product and an instance transform for each instance to be installed in addition to the base instance. Use the following guidelines when authoring the base package and transforms:

• The setup application can check for the presence of the installer running on a version of the Microsoft®Windows Server 2003 family, Windows XP SP1, Windows 2000 SP4 and the Windows Installer 3.0 redistributable. Any of these installer versions (or later) are required to install multiple instances from a single package using a product code–changing transform.
• Each instance must have a unique product code and instance identifier. One may define a property in the base package, the value of which can be set to the instance identifier.
• To keep the files of each instance isolated, the base package should install files into a directory location that depends on the instance identifier.
• To keep the non-file data of each instance isolated, the base package should collect non-file data into sets of components for each instance. The appropriate components should then be installed based on conditional statements that depend on the instance identifier.
• Author an instance transform for each instance being installed in addition to the base instance. The base package may install its own instance.
• The instance transform must change the product code and identifier for each instance.
• It is recommended that the product transform also change the product name so that the instance is readily distinguished in Add/Remove Programs through Control Panel.
• If the instance transform installs files, they should be installed in a directory that depends on the instance identifier.
• All non-file data, such as registry keys, should include the instance name in their path to prevent collisions. This can be accomplished by using the property whose value is the instance identifier in the path as shown by the following example of a Registry Table.

Installing Multiple Instances with Instance Transforms

This topic provides guidelines for installing or reinstalling a multiple instance installation that uses instance transforms.

When installing a new instance with an instance transform, include the MSINEWINSTANCE property and set MSINEWINSTANCE=1.

When installing a new instance with an instance transform, include the TRANSFORMS property and set the first transform in the list of transforms to the instance transform that changes the product code. Any customization transforms should follow the instance transform at the beginning of this list.

The easiest way to initiate a maintenance installation, and reinstall an instance, is to reference the product code of the instance. If one initiates the maintenance installation by using the package path, one must also specify the product code of the instance. From the command line, use the /n {Product Code} option. From code or script, use the MSIINSTANCEGUID property.

The following example shows installing a new instance from a command line where the instance Transform is prefixed by a colon which specifies that the transform is embedded in the package.

Msiexec /I mypackage.msi TRANSFORMS=:instance.mst MSINEWINSTANCE=1 /qb

Instance Transforms

What is the need for Instance Transforms?

Windows Installer permits one instance of a product code to be installed per context, and the two possible types of context are the following:

• Machine
• User

If a product code remains unchanged, only one instance can be installed in the machine context and only one instance can be installed in each user context. For multiple instances to remain isolated, they must have different product codes and cannot share file data or nonfile data. The Windows Installer cannot install multiple instances of products using concurrent installations. However, you can install multiple instances of a product if you have a separate installation package for each instance of a product or patch. Then each package can keep its own set of data and have its own unique product code.  Starting with the installer running the Microsoft Windows Server 2003 family and Windows XP SP1, you can install multiple instances of a product by using product code transforms and one .MSI package or one patch. You can also use product code transforms to install multiple instances of a product with Windows 2000 SP4 and Windows Installer 3.0. The only way to install more than one instance of a product with previous versions of the installer is to have a separate installation package for each instance.

Using instance transforms significantly reduces the effort needed to support multiple instances of a product. You can author one base Windows Installer package for a product and then multiple instance transforms that change the product code and manage data for each instance.

How to Authoring Multiple Instances with Instance Transforms

To install multiple instances of a product from one Windows Installer package, you need to author a base installation package for the product and an instance transform for each instance to be installed in addition to the base instance. Use the following guidelines when authoring your base package and transforms:

Your setup application can check for the presence of the installer running on a version of the Microsoft Windows Server 2003 family, Windows XP SP1, Windows 2000 SP4 and the Windows Installer 3.0 redistributable. Any of these installer versions (or later) are required to install multiple instances from a single package using a product code–changing transform.

Each instance must have a unique product code and instance identifier. You may define a property in the base package, the value of which can be set to the instance identifier.

To keep the files of each instance isolated, the base package should install files into a directory location that depends on the instance identifier.

To keep the nonfile data of each instance isolated, the base package should collect nonfile data into sets of components for each instance. The appropriate components should then be installed based on conditional statements that depend on the instance identifier.

Author an instance transform for each instance being installed in addition to the base instance. The base package may install its own instance.

The instance transform must change the product code and identifier for each instance.

It is recommended that the product transform also change the product name so that the instance is readily distinguished in Add/Remove Programs through Control Panel.

If the instance transform installs files, they should be installed in a directory that depends on the instance identifier.

All nonfile data, such as registry keys, should include the instance name in their path to prevent collisions. This can be accomplished by using the property whose value is the instance identifier in the path as shown by the following example of a Registry Table.

How to Install Multiple Instances with Instance Transforms

This topic provides guidelines for installing or reinstalling a multiple instance installation that uses instance transforms.

• When installing a new instance with an instance transform, include the MSINEWINSTANCE property and set MSINEWINSTANCE=1.
• When installing a new instance with an instance transform, include the TRANSFORMS property and set the first transform in the list of transforms to the instance transform that changes the product code. Any customization transforms should follow the instance transform at the beginning of this list.
• The easiest way to initiate a maintenance installation, and reinstall an instance, is to reference the product code of the instance. If you initiate the maintenance installation by using the package path, you must also specify the product code of the instance. From the command line, use the /n {Product Code} option. From code or script, use the MSIINSTANCEGUID property.

The following example shows installing a new instance from a command line where the instance transform is prefixed by a colon which specifies that the transform is embedded in the package.

Msiexec /I mypackage.msi TRANSFORMS=:instance.mst MSINEWINSTANCE=1 /qb

The following example reinstalls an instance without re-caching the package. The instance is referred to by its product code {00000001-0002-0000-0000-624474736554}.

Msiexec /I {00000001-0002-0000-0000-624474736554} REINSTALL=ALL REINSTALLMODE=omus /qb

The following example reinstalls an instance and re-caches the package from the command line. The instance is referred to by the package path. You are only required to include the /n {Product Code} option if the product is originally installed with an instance transform.

msiexec /I c:\newpath\mypackage.msi /n {00000001-0002-0000-0000-624474736554} REINSTALL=ALL REINSTALLMODE=vomus /qb

The following example shows how to advertise an instance using the command line.

Msiexec /jm mypackage.msi /t :instance.mst /c /qb

The following example shows how to apply a patch to an instance from a command line. You are only required to include the /n {Product Code} option if the product was originally installed with an instance transform.

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