What are Merge Modules?

Merge modules provide a standard method by which developers deliver shared Windows Installer components and setup logic to their applications. Merge modules are used to deliver shared code, files, resources, registry entries, and setup logic to applications as a single compound file. A merge module is similar in structure to a simplified Windows Installer .MSI file. However, a merge module cannot be installed alone, it must be merged into an installation package using a merge tool. This is because its lacks some vital database tables that are present in an installation database. Merge modules also contain additional tables that are unique to themselves.. When a merge module is merged into the .MSI file of an application, all the information and resources required to install the components delivered by the merge module are incorporated into the application’s .MSI file. The merge module is then no longer required to install these components and the merge module does not need to be accessible to a user. A standard merge module has an .MSM file name extension.

Basic Structure of Merge Modules

• A Merge Module Database containing the installation properties and setup logic being delivered by the merge module. The following tables are required in the database of every .MSM file:
• Component
• Directory
• FeatureComponents
• File
• ModuleSignature
• ModuleComponents

A merge module database does not contain a Feature table and so the .MSM file cannot be installed alone. The ModuleSignature Table is only present in .MSI files that has been merged with at least one .MSM file. If this table is present in an .MSI file, it contains one record for each merge module that has been previously merged into the installation database. Merge modules may contain optional MergeModuleSequence tables. These tables occur only in .MSM files. When the .MSM files are merged into an .MSI file, these tables modify the action sequence tables of the .MSI file. Merge modules rarely require user interface tables. These tables need to be present only in rare cases where the merge module requires input from the user during installation.

• A Merge Module Summary Information Stream Reference describing the module.
• A MergeModule.CABinet cabinet file stored as a stream inside the merge module. This cabinet contains all the files required by the components delivered by the merge module.

A very important rule is to be followed while creating a Merge Module. In the Components tab of the Setup Editor, after right-clicking the component and going into Details tab the “Always Increment shared .DLL count” and “Leave installed on uninstall” checkboxes should be checked as shown below.

When the “Always Increment shared .DLL count” checkbox is checked, the attribute of that component becomes 8. When this happens, the reference count of the file in that component automatically gets incremented when it’s installed. This is particularly helpful when dealing with shared files because accidental deletion of that shared file may break down other applications using that shared file. When this option is checked the shared file will not get deleted unless its Reference count is 1.

When the “Leave installed on Uninstall” checkbox is checked, the attribute of that component becomes 16. When this happens that component becomes permanent and the files in that component will not be removed during uninstallation.

Why are Merge Modules required?

Because all the information needed to install the components is delivered as a single file, the use of merge modules can eliminate many instances of version conflicts, missing registry entries, and improperly installed files. There are several scenarios in which administrators might find merge modules useful or necessary. The following list provides some examples:

• To use vendor-built merge modules instead of the files repackaged with a setup.exe. Software vendors may build a setup.exe installation package that includes third-party runtime files that are also provided by the third-party as merge modules (for use by software vendors who are building Windows Installer packages). Using the merge module instead of building your own components ensures that reference counts of vendor-provided components are accurate when vendor-provided MSIs and repackaged MSIs both use the same versions of third-party runtimes.
• To alert in-house developers that they should be using vendor-provided merge modules if they are authoring packages that include runtimes that are distributed as merge modules by the runtime vendor.

When are Merge Modules created?

Merge Module are created in two cases:

1. When a COM component is present in a public folder, but does not come from the same manufacturer as the packaged application. (Exceptions are Microsoft, Crystal Reports etc. Merge Modules must be made here for all components, which are present in a public folder, even when the application comes from the same manufacturer.)
2. When a COM component is present in a private folder, which is not from the same manufacturer as the application, which installs it and lets the COM component be registered. It must be noted here that the component must change the place of installation, before a Merge Module can be made out of it. Such components are installed in a public folder!

Some problems with Merge Modules

Many administrators might want to replace repackaged runtimes with the vendor’s official merge modules or internally generated merge modules during the packaging process. You should be familiar with the following cautions when replacing repackaged files with merge modules:

• As of Windows Installer 2.0, merge modules can alter package logic (such as adding custom actions), which might result in unintentional package behavior.
• Merge modules may contain errors.
• Merge modules may add many more files than your setup.exe package originally contained due to dependency information that was not tracked by the developer who built the setup.exe program.
• Merge modules may have different versions of supporting files; although they should be the vendor’s specified matching versions, in some instances they may create compatibility difficulties with the software application if the original setup.exe contained mismatched file sets on which the application vendor built their software.
• Merge modules will need to be run through your conflict management tools if you are using them.
• Be sure you are familiar with the rules followed by automatic merge module scanning/replacing tools and ensure that they meet your guidelines for application integration and testing.
• Application testing can be made difficult when large portions of an application are replaced by merge modules. If merge modules replace 50 DLLs and there is a problem with integration testing, it can be very difficult to know where to start diagnosing the problem; you might want to keep a reference copy of the MSI as cleanly repackaged before merge modules are substituted.