Using Windows side-by-side assemblies

As of version 5.1, Tarma Installer 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 Tarma Installer, 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, Tarma Workshop 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. Tarma Workshop 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 2000 and earlier

Tarma Installer's implementation of Windows side-by-side assemblies has one 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 Tarma Installer project and the file is or contains a Windows side-by-side manifest, then Tarma Workshop 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.

Tarma Workshop 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, Tarma Workshop 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. Tarma Workshop 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 Tarma Installer 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 Tarma Installer 5.x add-on (see Available add-ons below).
2. In your Tarma Installer 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, http://www.tarma.com/products/tin/download.htm. New ones may be added from time to time. These add-ons require Tarma Installer 5.1 or later to be present on your system. You only have to download and install them once, even if you update the Tarma Installer itself in the mean time.

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 Tarma Installer 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.