Assembly Versioning

.NET versioning occurs at the assembly level. As discussed previously, a version number forms part of the assembly strong name , so it therefore constitutes part of the assembly identity. As different versions of the same assembly have different strong names (and therefore different identities), .NET considers them to be completely different assemblies. Note that although Windows executable files contain a version information resource (which can be viewed in Windows Explorer by viewing the properties of the file), this resource remains completely discrete from the .NET version information; thus .NET ignores the Win32 version information.

When you build your own assemblies, .NET records the complete strong names of all assemblies referenced by them. This practice allows the .NET runtime environment to know exactly which version of an assembly is required, and it can apply its versioning policy to determine which assembly to provide. The default .NET versioning policy states that applications use the same assembly version with which they were built and tested .

Example: Building a Second Version of an Assembly

Let's extend the progressive example by building a "version 2" of the assembly and installing it into the GAC. If all goes well:

• After installing the assembly into the GAC, you should see two AboutBox assemblies, each with a different version number.

• The earlier example code that uses version 1 should continue to use version 1 of the assembly (that is, the new version of the assembly will not automatically be used for applications that reference the old version).

• The new program should use version 2 of the assembly.

As you might guess, the changes to the code are minimal. You simply change the version number in the al command line and change the message text in the message.txt file. The files for the example appear in the AboutBoxGACV2 directory, but the new makefile has the following al command line:

 al /v:2.0.0.0 /keyfile:..\AboutBox.key /link:message.txt \     /out:AboutBox.dll AboutBox.netmodule 

The message.txt file has the following content:

 Second Public Assembly 

You build the example in the same way, by executing nmake . After building, you can check that two AboutBox assemblies appear in the cache. The gacutil tool supports a /l option to list the contents of the GAC, so executing gacutil /l AboutBox should show the entries:

 C:\>gacutil /l AboutBox  Microsoft (R) .NET Global Assembly Cache Utility.  Version 1.0.3617.0 Copyright (C) Microsoft Corporation 1998-2001. All rights reserved. The Global Assembly Cache contains the following assemblies:         AboutBox, Version=1.0.0.0, Culture=neutral, PublicKeyToken=...         AboutBox, Version=2.0.0.0, Culture=neutral, PublicKeyToken=... The cache of ngen files contains the following entries: Number of items = 2 

Both versions of the assembly are listed here. You can also use the Windows Explorer extension to see them.

When this sample code is executed, the new text is displayed in the About Box dialog. Executing the original code shows that it still uses version 1 of the assembly, as shown by the text displayed in that application. Thus .NET supports two versions of the same assembly, providing the correct assembly for each application.

.NET allows this version discrimination to happen per assembly, rather than just per application. Thus a single application can indirectly use two versions of the same assembly. This duality is more common than you might think ”your application might use ObjectA and ObjectB for different purposes, even though both use a common assembly for their implementation. If a vendor creates a new ObjectB (with a new version of the common assembly) but ObjectA remains the same, then your application will indirectly require two different versions of the common assembly. This results in side-by-side assemblies, which .NET supports in the same way it supports different assemblies across different applications.

Example: Binding to a Different Version of an Assembly

.NET uses configuration files to apply different versioning policies. Configuration files, which are discussed in more detail in Chapter 6, allow you to specify different assembly bindings per assembly, per application, or systemwide .

Let's bind the code in the progressive example to a different assembly version by using an application configuration file. Application configuration files are the simplest to create and set up. As implied by their name, each file applies to a single application.

An application configuration file appears in the same directory as the application, and has the same name as the application but a .config suffix. Note that the original file extension is maintained ; thus, for the example application, the application configuration file is named UseAboutBox.exe.config .

As discussed in more detail in Chapter 6, all configuration files are XML text files. The .NET documentation for configuration files lists all element and attribute names recognized by .NET, and the one that is of interest here is the dependentAssembly element. Listing 5.4 shows the relevant configuration file.

Listing 5.4 Configuration file for assembly binding

 <configuration>    <runtime>       <assemblyBinding         xmlns="urn:schemas-microsoft-com:asm.v1">         <dependentAssembly>           <assemblyIdentity name="AboutBox"             publicKeyToken="a0df1539bc79861c"/>           <bindingRedirect oldVersion="1.0.0.0"                            newVersion="2.0.0.0"/>         </dependentAssembly>       </assemblyBinding>     </runtime> </configuration> 

The dependentAssembly element contains the name and public key token of the assembly to which rebinding occurs. If necessary, you could also specify the assembly culture here. In the bindingRedirect element, you specify the oldVersion (that is, the version requested by the application) and the newVersion (that is, the new version provided to replace the old version).

In Listing 5.4, the file specifies that version 2.0.0.0 be used instead of version 1.0.0.0. For this reason, it makes sense to run the version 1 assembly with this configuration file; the second example is set up to use version 2.

To test the configuration file, simply place the application ( UseAboutBox.exe ) and the configuration file ( UseAboutBox.exe.config ) in the same directory and execute the application. Displaying the About Box dialog confirms that the application uses version 2 of the assembly. You can further confirm this fact by removing version 1 from the GAC and checking whether the application still runs correctly.

Although the demonstration program here has used an application configuration file, it would clearly generate a lot of work if each and every application using a common assembly required such a configuration file. To eliminate this problem, .NET allows you to specify such bindings in a systemwide configuration file ”more on that later.

Obviously, if you rebind one assembly to another, you must ensure that both assemblies are compatible. If they are not, your application will likely fail due to these differences as well as your direction to .NET to allow these versions to be interchanged. Use rebinding at your own risk, and even then only under the advice of the original assembly's author or publisher.