Guidelines for Creating Side-by-side Assemblies

The following guidelines discuss how to author your own COM or Win32 side-by-side assemblies. You may not need to create your own side-by-side assemblies if the functionality needed is provided by one of the supported Microsoft side-by-side assemblies. In this case, use the assemblies provided by Microsoft and follow the procedures for using side-by-side assemblies in Using Isolated Applications and Side-by-side Assemblies.

First, consider whether your component makes a suitable candidate for a side-by-side assembly. For more information, see Should you provide a shared component as a side-by-side assembly?

To create a side-by-side assembly, follow these guidelines:

• Decide which resources to include in the assembly. Keep in mind that an assembly consists of one or more files that are always provided to applications and customers together. The assembly serves as the fundamental unit used for naming, binding, versioning, deployment, and default configuration. As a general rule, when uncertain about whether two resources belong in the same assembly, it is recommended that they be authored to go into separate assemblies. Typically, a side-by-side assembly consists of a single DLL.
• Create an assembly manifest for the assembly. The manifest should describe the COM object or type libraries in the assembly. For more information about what should be authored into an assembly manifest, see assembly manifests.
• Evaluate the usage of objects when more than one version of your assembly is run on the system. Determine whether different versions of the assembly require separate data structures, such as memory-mapped files, named pipes, registered Windows messages and classes, shared memory, semaphores, mutexes, and hardware drivers. Any data structures used across assembly versions must be backward-compatible versions. Decide which data structures can be used across versions and which data structures must be private to a version. Determine whether shared data structures require separate synchronization objects such as semaphores and mutexes.
• Author your DLL to work well as a side-by-side assembly by adhering to the guidelines in Authoring a DLL for a Side-by-Side Assembly.
• Author a set of header files and helper functions to provide an easy way to version registry keys containing the assembly state. Assemblies commonly save their state settings in registry keys. Registry settings must be written on an individual version basis to isolate multiple assembly versions that may be run at the same time. Design your side-by-side assembly and DLL to correctly store and handle the state of the assembly during side-by-side sharing scenarios. Follow the guidelines in Authoring State Storage for Side-by-Side Assemblies.
• Developers of applications that use private assemblies should secure the application directory. If the application is installed using the Windows Installer, then the application directory can be secured by using the LockPermissions table. Typically, the system is given read, write, and execute access to private assemblies; all other processes are given only execute and read access.
• Test the assembly using scenarios with side-by-side sharing to ensure that it is a valid side-by-side assembly. Successful installation of the assembly is not sufficient to guarantee that it will work as expected.
• Adopt a method for numbering updates for your assembly. Each assembly is associated with a four-part version number. Left-to-right, the major, minor, build, and revision parts are separated by periods. Change the major or minor number of an assembly for a version that is incompatible with earlier versions. Change only the build and revision parts for backward-compatible changes to the assembly. For example, a developer might adopt a numbering method in which all 1.0.0.* version numbers refer to update versions to assembly version 1.0.0.0.

About Side-by-Side Assemblies

A Windows side-by-side assembly is described by manifests. A side-by-side assembly contains a collection of resources—a group of DLLs, Windows classes, COM servers, type libraries, or interfaces—that are always provided to applications together. These are described in the assembly manifest.

Typically, a side-by-side assembly is a single DLL. For example, the Microsoft COMCTL32 assembly is a single DLL with a manifest whereas the Microsoft Visual C++ development system run-time libraries assembly contains multiple files. Manifests contain metadata that describes side-by-side assemblies and side-by-side assembly dependencies.

Side-by-side assemblies are used by the operating system as fundamental units of naming, binding, versioning, deployment, and configuration. Every side-by-side assembly has a unique identity. One of the attributes of the assembly identity is its version. For more information, see Assembly Versions.

Starting with WindowsВ XP, multiple versions of side-by-side assemblies can be used by applications running at the same time. Manifests, and the assembly version number, are used by the loader to determine the correct binding of assembly versions to applications. Side-by-side assemblies and manifests work with applications and the side-by-side manager as illustrated in the following figure.

In the preceding example, both Comctl32.DLL version 6.0 and Comctl32.DLL version 5.0 are in the side-by-side assembly cache and available to applications. When an application calls to load the DLL, the side-by-side manager determines whether the application has a version dependence described in a manifest. If there is no relevant manifest, the system loads the default version of the assembly. For WindowsВ XP, version 5.0 of Comctl32.DLL is the system default. If the side-by-side manager finds a dependence on version 6.0 stated in a manifest, that version is loaded to run with the application.

Several key system assemblies are being made available from Microsoft as side-by-side assemblies. For more information, see Supported Microsoft Side-by-side Assemblies. Application developers can also create their own side-by-side assemblies. For more information, see Guidelines for Creating Side-by-side Assemblies. In many cases it is possible to update existing applications to use side-by-side assemblies without having to change the application code.

Developers are encouraged to use side-by-side assemblies to create isolated applications, and to update existing applications into isolated applications for the following reasons:

• Side-by-side assemblies reduce the possibility of DLL version conflicts.
• Side-by-side assembly sharing enables multiple versions of COM or Windows assemblies to run at the same time.
• Applications and administrators can update assembly configuration on either a global or per-application configuration basis after deployment. For example, an application can be updated to use a side-by-side assembly that includes an update without having to reinstall the application.

Using Side-by-side Assemblies

Use the following procedure to develop a new application, or update an existing application, to use the side-by-side assemblies available from Microsoft or other side-by-side assembly publishers. For a list of the side-by-side assemblies currently provided by Microsoft, see Supported Microsoft Side-by-side Assemblies. Note that the application must be run on at least WindowsВ XP to install the assemblies as side-by-side assemblies. For more information, see Guidelines for Creating Side-by-side Assemblies.

To add a side-by-side assembly to an application

Identify the side-by-side assemblies that your application requires. Starting with WindowsВ XP, these side-by-side assemblies and their assembly manifests are installed with the operating system but are not globally registered.

Use an XML editor to create an application manifest. See the example application manifest below. For more information, see Application Manifests in the Manifest Files Reference.

Enter attribute values in the DEF-context assemblyIdentity subelement of the application manifest that uniquely defines the application. For more information about the DEF-context assemblyIdentity, see Application Manifests.

If the assembly contains any dependent assemblies, enter attribute values into the corresponding REF-context assemblyIdentity subelements of the application manifest. For more information about the REF-context assemblyIdentity, see Application Manifests.

You may include the application manifest in the application’s binary executable header file.

In this case, also add the following line to the application header file:

CREATEPROCESS\_MANIFEST\_RESOURCE\_ID RT\_MANIFEST «YourApp.exe.manifest»

As an alternative, you can place a separate manifest file in the same directory as your application’s executable file. The operating system loads the manifest from the file system first, and then checks the resource section of the executable. The file system version takes precedence.

Shared assemblies should be installed using the Windows Installer version 2.0. Author a Windows Installer package as described in How Do I Install Win32 Assemblies for Side-by-side Sharing on Windows XP?.

Private assemblies can be installed using the Windows Installer version 2.0. Author a Windows Installer package as described in How Do I Install Win32 Assemblies for the Private Use of an Application on Windows XP?. You can also use any other installer to copy a private assembly and its manifest into the same folder as the application’s executable file.

Test your application to ensure the results. Note that your test computer should not have the side-by-side assembly registered.

Deploy your application or update as a Windows Installer package.

Example Application Manifest

The following is an example of an application manifest:

About Isolated Applications and Side-by-side Assemblies

Isolated applications and side-by-side assemblies provide a solution that reduces DLL versioning conflicts. They enable applications to safely share assemblies. For more information, see Shared Assemblies.

An assembly is a fundamental unit for naming, binding, versioning, deploying, or configuring a block of programming code. Applications with common functionality may run shared blocks of programming code which are referred to as modules or code assemblies. These code assemblies may be placed in DLLs or COM assemblies. The infrastructure for the safe sharing of assemblies is referred to as side-by-side assembly sharing.

Side-by-side assemblies are code assemblies described by manifests and authored so that multiple versions may run at the same time without conflicting with each other. When developers author manifests and write applications to use side-by-side assembly sharing, multiple assembly versions can run on the system and each application can specify which assembly version it should use.

A typical side-by-side assembly is a single DLL with a single manifest. Side-by-side assemblies store the information about binding and COM activation, traditionally saved in the registry, in manifests. In some cases, the versions of the assembly specified in manifests can be changed, on a global or per-application basis, by assembly publishers, application developers, or administrators. For more information, see default configuration, publisher configuration, and per-application configuration.

Developers can use the side-by-side assemblies provided by Microsoft, or other side-by-side assembly publishers, in their applications. For example, developers can get the functionality of the updated common controls, such as theming, by designing their applications to use the side-by-side assembly that contains Comctl32.dll 6.0. For the list of side-by-side assemblies and manifests that ship with WindowsВ XP, see Supported Microsoft Side-by-side Assemblies. Developers can also create their own side-by-side assemblies. For more information, see Guidelines for Creating Side-by-side Assemblies.

What are Side-by-side Assemblies?

I came across Side-by-side Assemblies for the first time today while trying to install a Debug install set to a test machine. I managed it in the end, but was left with several questions:

1. Whare are Side-by-side assemblies?
2. How does Windows deal with these assemblies differently from other assemblies
3. How do applications depending on Side-by-side assemblies deal with these differently from normal assemblies
4. Under what situations might someone want to create a Side-by-side assembly?

2 Answers 2

A starting point for understanding side-by-side assemblies and what they’re for would probably be the «Isolated Applications and Side-by-Side Assemblies» reference on MSDN.

Essentially, side-by-side assemblies are a way to ensure that a given application will always use a specific version of a DLL, particularly Windows system DLLs (such as the Common Controls), no matter the Service Packs, Updates or new applications installed after it.

Other links of interest:

Side-by-side assemblies are collection of resources available at runtime. They may be collection of dlls, classes, type libraries or interfaces. An applicfation with all components as side-by-side assemblies is called an isolated application.

Side-by-side assemblies provide a way for implementing multiple dlls in one assembly