Using Windows side-by-side assemblies

This help topic refers to a previous version of InstallMate. It has not been updated for InstallMate 9 yet.

InstallMate supports the installation of Windows side-by-side assemblies (in addition to .Net assemblies, which were supported from version 3.1 onwards). There are two sides to Windows side-by-side (SxS, for short) assemblies:

• The assembly itself, which consists of one or more executable files plus some optional support files;
• Any applications that depend on the assemblies.

Both sides use XML-based manifests to describe themselves. For a large part, these manifests use the same syntax, but they differ in the following respect:

• Assembly manifests describe the files that make up the assembly. This is done through <file> tags inside the manifest.
• Application manifests describe the assemblies that the application requires for execution. This is done through <dependency> and <dependentAssembly> tags inside the manifest.

In InstallMate, both the assemblies proper and the applications that contain or are accompanied by manifests are represented by assembly objects. However, only proper assemblies are typically registered as such on the target system, which leads to another subdivision:

• Private assemblies are assemblies that are not registered on the target system, but are intended for private use by a single application. Private assemblies should be installed in a subfolder of the product installation folder.
• Public assemblies are assemblies that are intended to be used by more than one (and potentially many) applications. They are registered for general use on the target system and must be installed in the global WinSxS folder. Furthermore, the assembly as a whole must be digitally signed and must be accompanied by its digital signature plus the certificate chain, stored either in a separate security catalog or as part of the executable assembly file itself.

To make the use of SxS assemblies as easy as possible, InstallMate Builder supports several methods to add assemblies to your installation project:

• Add as an installation file (not recommended)
• Add as a side-by-side assembly (recommended)
• As a predefined project item (recommended if available)

Special requirements

The registration of public (global, shared) Windows side-by-side assemblies requires Administrator rights on all systems that support side-by-side assemblies. We therefore recommend that you set the Installation level on the Installer options page to Administrator if your installer project contains any public side-by-side assemblies. InstallMate Builder will issue a BLD:W0035 diagnostic if this requirement is not met. If your project only installs private assemblies, Administrator rights are not required.

Public side-by-side assemblies on Windows Vista

Although public side-by-side assemblies can be successfully installed and registered on Windows Vista, the system will not remove them during uninstallation. This appears to be a feature of Windows Vista, presumably to preserve system stability. The Tarma uninstallation log will show a TSU:A0052 message for each uninstalled assembly and a disposition=0 parameter, but the assembly itself will in fact remain on the system.

Private side-by-side assemblies are installed and uninstalled normally.

Public side-by-side assemblies on Windows XP

Windows XP has its own implementation of the side-by-side assembly installation interface IAssemblyCache. However, this implementation does not respect the "downlevel" side-by-side registration scheme that is used by MSI installers on Windows XP (and which predated IAssemblyCache). As a result, MSI-installed assemblies will be removed by the Windows XP implementation of IAssemblyCache, which renders MSI-installed applications that use the assemblies inoperable.

To prevent this problem, InstallMate uses its own side-by-side assembly installation implementation on Windows XP with the following characteristics:

• It is compatible with the Windows XP IAssemblyCache implementation and assemblies will be correctly recognized by the system (and never prematurely removed);
• It is also compatible with the MSI-based "downlevel" registration scheme and will never remove assemblies that are still registered by MSI-based products.

As a result, InstallMate can safely install and remove side-by-side assemblies on Windows XP.

Note: However, be aware that MSI might still inadvertently remove assemblies, because it doesn't follow the established assembly registration scheme.

Public side-by-side assemblies on Windows 2000 and earlier

InstallMate's implementation of Windows side-by-side assemblies has another special feature: on Windows versions that do not support these assemblies, the files that make up a public assembly are automatically redirected to the appropriate Windows System folder (32-bit or 64-bit). This allows some degree of backward compatibility and will allow most applications to operate correctly on older systems. Some notes:

• This redirection happens only for public assemblies (i.e., the ones that would normally be installed into the WinSxS folder tree and registered as such with the system); private assemblies are installed wherever you specify in your installer project. This is because private assemblies are meant to be local to your application and are not visible to the rest of the system anyway.
• Non-executable assembly files, in particular the manifest and the security catalog of a public assembly, are not installed at all on systems that do not support side-by-side assemblies. They have no function there and might cause conflicts with similar named regular files. Again, this applies only to public assemblies; the manifest of a private assembly is always installed as per your specification.

In practice, this means that side-by-side assemblies work as intended on Windows XP, Vista, and later systems. On Windows 2000 and earlier systems, a public assembly's files are available from the Windows System32 folder and will be installed and used as any system DLL by your application. You do not have to do anything to accomplish this; the installer performs the required adjustments automatically.

Add as an installation file (not recommended)

If you add an installation file to your InstallMate project and the file is or contains a Windows side-by-side manifest, then InstallMate Builder will detect this and will automatically create a corresponding assembly object to represent it. The file is then added to this assembly.

This goes some way towards defining an SxS assembly for installation, but it fails to do the following:

• It will not add any assembly member files to the assembly;
• It will not add the security catalog, if any, to the assembly;
• It will not place a public assembly in the correct WinSxS folder.

For this reason, we do not recommend this method except under the following circumstances:

• As a fallback if other methods fail.
• For regular application executable files that happen to have an embedded SxS manifest.

If you decide to use this method, then you should be familiar with the Windows side-by-side assembly concepts.

Add as a side-by-side assembly (recommended)

The preferred method to add a Windows side-by-side assembly is as follows:

1. Go to the Files and folders project page and select the folder in which you want to install the assembly. For private assemblies, select a folder under your main installation folder or your main installation folder itself; for public assemblies, select the WinSxS folder that can be found as Target System\Windows\WinSxS.
2. Right-click on this folder, choose Add Side-by-side Assembly..., then select the manifest file of the assembly in the standard Windows Open dialog box that appears.

InstallMate Builder will analyze the manifest file, create a suitable assembly object to represent it, then add the manifest file itself, any member files, and the assembly's security catalog, if any. Furthermore, InstallMate Builder will warn you if you are trying to install a private assembly in the WinSxS folder (which is not allowed), and will offer to place any public assembly in the correct folder under WinSxS.

For this procedure to work correctly, you must ensure that the assembly's manifest file (with a .manifest file name extension), all of its member files, and the optional security catalog file are all located in the same folder. The security catalog file, if any, must have the same name as the manifest file, but with a .cat extension instead of .manifest. You must also set the Installation level on the Installer options page to Administrator if you add a public side-by-side assembly. InstallMate Builder will issue a BLD:W0035 diagnostic if this requirement is not met.

This is the recommended method to add a side-by-side assembly to your project, unless the assembly happens to be one of the predefined ones (see next section).

As a predefined project item (recommended if available)

Because the most often installed side-by-side assemblies are the Microsoft C/C++ runtime libraries, we have predefined a number of project items that you can add to your InstallMate project to get the correct files and settings. These project items work just like MSI merge modules, but are much less complicated and error prone.

To use this method, do the following:

1. Download and install the required InstallMate 9.x add-on (see Available add-ons below).
2. In your InstallMate project, choose File > Import > Project Items..., then select the desired item (see Available project items below).

When the project item is added to your project, it will be selected in the project for your inspection. You do not (and should not) have to change anything. If at any point you want to remove the item and its contents, then simply remove it as you would any component or assembly and be sure to select Delete this item and all referenced items in the Delete Object dialog box that asks for confirmation.

Available add-ons

The following add-ons related to Windows side-by-side assemblies are currently available from the download page on the Tarma web site, https://tarma.com/im9/download.htm. New ones may be added from time to time. These add-ons require InstallMate 9 or later to be present on your system. You only have to download and install them once, even if you update the InstallMate itself in the mean time.

Add-on	Version	Description
VC2005 Runtime Libraries, amd64 version	8.0.50727.42	Microsoft Visual Studio 2005 C/C++ runtime libraries for amd64 processors. Note: This is version 8.0.50727.42 of the libraries, which have been superseded by the SP1 version. If your VC2005 environment is up to date, you should use the SP1 versions instead.
VC2005 Runtime Libraries, x86 version	8.0.50727.42	Microsoft Visual Studio 2005 C/C++ runtime libraries for x86 processors. Note: This is version 8.0.50727.42 of the libraries, which have been superseded by the SP1 version. If your VC2005 environment is up to date, you should use the SP1 versions instead.
VC2005-SP1 Runtime Libraries, amd64 version	8.0.50727.762	Microsoft Visual Studio 2005 C/C++ runtime libraries for amd64 processors, SP1 update.
VC2005-SP1 Runtime Libraries, x86 version	8.0.50727.762	Microsoft Visual Studio 2005 C/C++ runtime libraries for x86 processors, SP1 update.
VC2008 Runtime libraries, amd64 version	9.0.21022.8	Microsoft Visual Studio 2008 C/C++ runtime libraries for amd64 processors. Note: These libraries will only be installed on Windows 2000 or later systems with amd64 processors.
VC2008 Runtime libraries, x86 version	9.0.21022.8	Microsoft Visual Studio 2008 C/C++ runtime libraries for x86 processors. Note: These libraries will only be installed on Windows 2000 or later systems.

Available project items

After installing one or more of the above add-ons, you will find the following project items if you use the File > Import > Project Items... command in your InstallMate project. (There may be other project items, depending on what other add-ons you have installed.)

Note: For best results if you add any of the amd64 variants to your installer project, your project should be a 64-bit project or a combined 32-bit and 64-bit project. If necessary, use the Insert 64-bit support project item before adding any of the amd64 library variants. You only need to add amd64 variants if your application is compiled for that processor and depends on its assemblies.

Project item	Description
VC2005 All libraries (amd64)	Inserts all VC2005 runtime libraries for amd64 processors into your project: ATL, CRT, MFC, MFC localizations, MSDIA, and OpenMP. This is equivalent to the Microsoft vcredist_x64 redistributable. Note: This is version 8.0.50727.42 of the libraries, which have been superseded by the SP1 version. If your VC2005 environment is up to date, you should use the SP1 versions instead.
VC2005 All libraries (x86)	Inserts all VC2005 runtime libraries for x86 processors into your project: ATL, CRT, MFC, MFC localizations, MSDIA, and OpenMP. This is equivalent to the Microsoft vcredist_x86 redistributable. Note: This is version 8.0.50727.42 of the libraries, which have been superseded by the SP1 version. If your VC2005 environment is up to date, you should use the SP1 versions instead.
Other VC2005 items	The other VC2005 items insert individual library assemblies into your project; this may be preferred if your application only uses some of the runtime libraries (for example, only ATL or CRT). Note: This is version 8.0.50727.42 of the libraries, which have been superseded by the SP1 version. If your VC2005 environment is up to date, you should use the SP1 versions instead.
VC2005-SP1 All libraries (amd64)	Inserts all VC2005 SP1 runtime libraries for amd64 processors into your project: ATL, CRT, MFC, MFC localizations, MSDIA, and OpenMP. This is equivalent to the Microsoft vcredist_x64 SP1 redistributable.
VC2005-SP1 All libraries (x86)	Inserts all VC2005 SP1 runtime libraries for x86 processors into your project: ATL, CRT, MFC, MFC localizations, MSDIA, and OpenMP. This is equivalent to the Microsoft vcredist_x86 SP1 redistributable.
Other VC2005-SP1 items	The other VC2005-SP1 items insert individual library assemblies into your project; this may be preferred if your application only uses some of the runtime libraries (for example, only ATL or CRT).
VC2008 All libraries (amd64)	Inserts all VC2008 runtime libraries for amd64 processors into your project: ATL, CRT, MFC, MFC localizations, MSDIA, and OpenMP. This is equivalent to the Microsoft vcredist_x64 redistributable. Note: These libraries will only be installed on Windows 2000 or later systems with amd64 processors.
VC2008 All libraries (x86)	Inserts all VC2008 runtime libraries for x86 processors into your project: ATL, CRT, MFC, MFC localizations, MSDIA, and OpenMP. This is equivalent to the Microsoft vcredist_x86 redistributable. Note: These libraries will only be installed on Windows 2000 or later systems.
Other VC2008 items	The other VC2008 items insert individual library assemblies into your project; this may be preferred if your application only uses some of the runtime libraries (for example, only ATL or CRT). Note: These libraries will only be installed on Windows 2000 or later systems.