MSI Factory

MSI Factory allows you to create two different kinds of projects: installers and merge modules. Installer projects are the ones that create full installation packages (.msi/.exe files). Merge Module projects are used to make merge module databases (.msm files).

About Merge Modules

Merge modules are Windows Installer database files that are used to describe installation logic that will be merged with a larger Windows Installer installation package (.msi file). Merge module files have the same format and use the many of the same tables as full MSI files with a few exceptions. When a merge module is merged with a installer database file its tables and files are combined with the host installer package to create a larger super set of the installer database. When the merged installer is run, the files and actions from the merge module are installed in the exact same way as the files that were directly authored into the installer package.

The Purpose of Merge Modules

Merge modules are used to deliver shared code, files, resources, registry entries, and setup logic to applications as a single compound file. They provide a way to "black box" the installation logic of files and actions so that the installation of such is consistent and reliable.

Most commonly, merge modules are used for files that are installed to a common location (such as the System folders) and/or shared by multiple applications. For example, many ActiveX and .NET controls that are sold by third-party tool vendors come with their own merge modules so that the developer can simply merge the installation logic of the control into their setup without worrying about having to manually specify the file's information and setup logic.

Creating a Merge Module in MSI Factory

To create a merge module in MSI Factory, you should create a new project (File > New) and then choose "Merge Module Project" from the Start a New Project dialog. If this dialog does not appear then select Edit > Preferences from the menu and ensure that the Show New Project dialog option is turned on in the Startup section of the Project tab.

If you have the Show project wizard checkbox turned on you will be able to specify some options for your merge module using the project wizard. Otherwise you will see an empty merge module project.

Differences Between Merge Module and Installer Projects

Although you are still in the same design environment as you are when you create an installer project, there are differences in the options available. Specifically:

- The Project Settings dialog has a Module tab instead of a Product tab.

- The Project Settings dialog is missing the Control Panel tab.

- You cannot edit Features. The feature that components in a merge module belong to is determined by the author of the installer package, not the merge module.

- There are less folders defined by default in the Folders dialog. By default, INSTALLDIR is defined directly below TARGETDIR and not inside of [ProgramFilesFolder] as it would be in an installer project. See the Working with Folders section below for more details.

- You cannot edit the Media. The media that the files in a merge module will be included on is determined by the author of the installer package, not the merge module.

- You cannot edit Launch Conditions.

- You cannot include Merge Modules. Merge modules cannot contain other merge modules. You can, however, declare other merge modules that yours depends on from the Module tab of the Project Settings dialog.

- You cannot specify any Bootstrapper options on the Setup File tab of the Build Settings dialog. Wrapping a merge module in an executable would not make sense.

- There is no user interface dialogs defined in the Dialogs dialog by default. It is very rare to author user interface elements into a merge module. Normally the user interface is authored by the main installation package.

Working with Folders

The way that you specify destination folders for files in a merge module is different from the way it is generally done in an installer project. There are two common ways to specify a file's destination:

1. Install it to a common system folder.

If you set the destination folder to be an MSI-defined system folder such as [SystemFolder] or [WindowsFolder] the file will be installed to that location. This is the method used to install shared system files and components.

2. Install to a target folder or a sub-folder of a target folder of the installer package author's choosing.

In this case you are letting the installation author choose where the files are installed to. To do this, the destination folder must be in or a subfolder of TARGETDIR. You can see how this target folder is specified in MSI Factory if you open or create an installer project and choose Project > Merge Modules. On the Merge Module Properties dialog, this folder is specified using the "Parent folder" field. When the modules are merged, folders in the merge module installed to TARGETDIR or a sub-folder of TARGETDIR will be installed to the parent folder (or a sub-folder of parent folder).

If you want to install directly to the parent folder, do the following:

- Create a folder under SourceDir (ID: TARGETDIR) in the Folders dialog.

- Give the folder an ID of your choice.

- Set the folder name to a period ("."). This will allow you to reference the folder as a folder ID but during installation the folder will resolve to the parent folder.

If you want to install to a sub-folder of the parent folder, do the following:

- Create a folder under SourceDir (ID: TARGETDIR) in the Folders dialog.

- Give the folder an ID of your choice.

- Set the folder name to the name of the sub-folder that you want to create.

Merge Module Identification

Merge modules are uniquely identified in their ModuleSignature table. The module signature is made up of three pieces of data: module ID, language and version.

The module ID is a combination of a short, descriptive identifier (specified in the "Module name" field of the Module tab) combined with a GUID. The GUID is taken from the "Package ID" field on the Package tab of the Project Settings dialog. In fact, the GUID is appended to every identifier in your merge module in order to avoid naming clashes when merged into a database file. This appending is done for you automatically when the merge module is built. An example of a Module ID is "MyModule.1BAE0FBA_6A0A_49E6_82EE_63AF13EC54BB".

One impact of this that you need to bear in mind is that if you are referencing something from your main installer that is defined in a merge module, you will need to append the module's GUID to it. For example, if the merge module defines a property called "MYPROPERTY" and the merge module's GUID is "1BAE0FBA_6A0A_49E6_82EE_63AF13EC54BB", it will end up being merged as "MYPROPERTY.1BAE0FBA_6A0A_49E6_82EE_63AF13EC54BB" into the main installer.

More Information

MSDN Online: About Merge Modules

MSDN Online: Authoring Merge Module Directory Tables

MSDN Online: Merge Modules

MSDN Online: Merge Module Database Tables

MSDN Online: ModuleDependency Table

MSDN Online: ModuleSignature Table

WiX Help File: Dependency Element

WiX Help File: IgnoreTable Element

WiX Help File: Module Element

Learn More: Indigo Rose Software - MSI Factory - Buy Now - Contact Us