A .NET Framework assembly is said to have either a weak name or a strong name. Throughout this chapter, I demonstrate how the factors you must consider when loading an assembly are different based on whether the assembly has a strong name or a weak name. For example, I’ll show that the CLR uses different rules for locating an assembly when referring to it by its strong name rather than its weak name.

An assembly has a strong name if it has been signed with a cryptographic key pair using either a compiler or the sn.exe SDK tool. If an assembly has not been signed, it has a weak name. Structurally, assemblies with strong names are different from assemblies with weak names in two key ways:

This second characteristic is particularly important to the process of referencing and loading an assembly.

An assembly’s identity consists of four parts:

Assemblies with weak names have a friendly name, a version, and an optional culture. Assemblies with a strong name have a friendly name, a version, a public key, and a culture. You can see this difference in the portion of an assembly’s metadata that records its name. In the following listing, I’ve used the ildasm.exe SDK tool to display a portion of the metadata for an assembly with a strong name. Note the presence of a public key in the name.

.assembly BoatRaceHostRuntime
{
  .publickey = (00 24 00 00 04 80 00 00 94 00 00 00 06 02 00 00
                00 24 00 00 52 53 41 31 00 04 00 00 01 00 01 00
                07 D1 FA 57 C4 AE D9 F0 A3 2E 84 AA 0F AE FD 0D
                E9 E8 FD 6A EC 8F 87 FB 03 76 6C 83 4C 99 92 1E
                B2 3B E7 9A D9 D5 DC C1 DD 9A D2 36 13 21 02 90
                0B 72 3C F9 80 95 7F C4 E1 77 10 8F C6 07 77 4F
                29 E8 32 0E 92 EA 05 EC E4 E8 21 C0 A5 EF E8 F1
                64 5C 4C 0C 93 C1 AB 99 28 5D 62 2C AA 65 2C 1D
                FA D6 3D 74 5D 6F 2D E5 F1 7E 5E AF 0F C4 96 3D
                26 1C 8A 12 43 65 18 20 6D C0 93 34 4D 5A D2 93 )
  .hash algorithm 0x00008004
  .ver 1:0:0:0
}

In contrast, the following listing shows the metadata stored for an assembly with a weak name:

.assembly Utilities
{
.ver 1:0:0:0
}

Assemblies are given strong names when you intend them to be shared among several applications on the system. Shared code has much more stringent requirements than code that is private to only one application. These additional requirements are primarily related to security and versioning. For example, assemblies used by many applications require a robust approach to versioning to avoid the versioning conflicts associated with Win32 DLLs. New versions of the shared assembly must be able to be added to the system without breaking applications that depend on previous versions. A cryptographically strong name is required to ensure that a given assembly can’t be altered by anyone other than the original assembly author.

For a more thorough description of assembly names, including more discussion on the motivation behind using strong names, see Chapter 2 and Chapter 3 in Applied Microsoft .NET Framework Programming (Microsoft Press, 2002) by Jeffrey Richter.

Assemblies can be referenced in either an early-bound or a late-bound fashion. Early-bound references are recorded in metadata when an assembly is compiled. Late-bound references are specified on the fly using the APIs on such classes as System.Reflection.Assembly, System.Activator, or System.AppDomain.

Extensible applications are likely to use both early- and late-bound references. Assemblies that are part of the implementation of the extensible application are likely to be referenced using early binding. In contrast, the add-ins that are dynamically added to the application to extend it are loaded using late binding because the application doesn’t know which add-ins it will load (and, hence, can’t reference them) when the application is compiled.

Let’s return to the boat race example introduced in Chapter 5 to illustrate more concretely how these two types of references are likely to be used in an extensible application. Assume that our boat race application is written entirely in managed code and consists of a main executable called boatracehost.exe and three utility DLLs called boatracehostruntime.dll, weather.dll, and sailconfigurations.dll. When boatracehost.exe is compiled, it statically references the utility DLLs using the /r compiler switch, like so:

C:	empBoatRaceHost>csc /target:winexe /
r:BoatRaceHostRuntime.dll, SailConfigurations.dll,Weather.dll BoatRaceHost.cs

After compiling boatracehost.cs using this command line, the manifest for boatracehost.exe looks like this (produced with ildasm.exe):

.assembly BoatRaceHost
{
  .ver 1:0:0:0
}
.assembly extern BoatRaceHostRuntime
{
  .publickeytoken = (4B 7D 48 01 D8 95 67 95)
  .ver 1:0:0:0
}
.assembly extern SailConfigurations
{
  .publickeytoken = (4B 7D 48 01 D8 95 67 95)
  .ver 1:0:0:0
}
.assembly extern Weather
{
  .publickeytoken = (4B 7D 48 01 D8 95 67 95)
  .ver 1:0:0:0
}
.assembly extern System.Windows.Forms
{
  .publickeytoken = (B7 7A 5C 56 19 34 E0 89)
  .ver 1:0:5000:0
}
.assembly extern System
{
  .publickeytoken = (B7 7A 5C 56 19 34 E0 89)
  .ver 1:0:5000:0
}
.assembly extern mscorlib
{
  .publickeytoken = (B7 7A 5C 56 19 34 E0 89)
  .ver 1:0:5000:0
}
  .assembly extern System.Drawing
{
  .publickeytoken = (B0 3F 5F 7F 11 D5 0A 3A)
  .ver 1:0:5000:0
}

Each .assembly extern statement in the previous listing represents an early-bound reference to an assembly. Notice that in addition to the references to SailConfigurations, Weather, and BoatRaceHostRuntime, our application has early-bound references to the .NET Framework assemblies it uses, including System.Drawing and System.Windows.Forms.

To illustrate when late-bound references are used, let’s assume our boatracehost application includes a menu command that enables users to add boats to the race dynamically. During a particular run of the application, the end user adds two boats to the race. These two boats are contained in the assemblies Alingi and TeamNZ. Both Alingi and TeamNZ are loaded dynamically; hence, late binding is used as shown in Figure 7-1.

Figure 7-1. Early- and late-bound assembly references in extensible applications

This chapter focuses primarily on late binding because the flexibility introduced by loading assemblies on the fly introduces several considerations unique to extensible applications. In particular, the fact that late-bound references can be partially specified introduces complexities you don’t run into when all assembly references are early bound.

As described, assemblies in .NET Framework are identified by a friendly name, a public key, a version number, and a culture. When referencing an assembly, you can specify all four of these fields or you can specify just the friendly name—the public key, version number, and culture are all optional. When all four fields are specified, the assembly reference is said to be fully specified. If anything less than all four fields is included, the reference is partially specified.

Partially specified references are unique to late binding. When a compiler records an earlybound reference to an assembly in metadata, it stores values for all four fields. These values can be null (as the value for the public key is when an assembly has a weak name), but they are values nonetheless. In contrast, the APIs that enable you to load an assembly dynamically allow you to omit values for the public key, version number, and culture fields. Referencing an assembly by only a portion of its name results in looser binding semantics than a fully specified reference does. For example, if you want to load an assembly by its friendly name only, without regard to version, you can simply omit a version number from your reference. If the CLR finds an assembly whose friendly name matches, it loads it regardless of which version it is. These looser binding semantics are useful in some scenarios. Microsoft ASP.NET, for example, uses partial binding and weakly named assemblies to implement loose version binding for assemblies stored in the bin subdirectory under the application’s root directory. You might have noticed you can place any assembly in the bin directory and, as long as its name matches, it is loaded, regardless of version.

Although the flexibility allowed by partially specified assembly references is useful in scenarios like these, you should also be aware of its complexities. For example, the rules for which of the four fields must match are different depending on whether the assembly that matches the friendly name has a strong name or a weak name. I discuss these complexities in the section "Partially Specified Assembly References" later in this chapter.

As described, strong names are part of the infrastructure the CLR uses to provide a system that employs strict version checking to minimize inadvertent conflicts between different versions of an assembly. By default, the CLR loads the exact version of the assembly you specify in your reference. However, this version can be redirected to a different version through a series of statements called version policy. Version policy is useful in several scenarios. For example, a machine administrator can specify version policy that would prevent anyone on the machine from using a version of an assembly that is known to have security vulnerabilities or other serious bugs. In addition, an application can use version policy to load a version of a .NET Framework assembly different from the default.

These version policy statements are specified in Extensible Markup Language (XML) files and are most easily created with the .NET Framework Configuration tool. The following is an example of a version policy statement that causes version 6.0.0.0 of an assembly whose friendly name is Alingi to be loaded, regardless of which version was specified:

<assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
  <dependentAssembly>
    <assemblyIdentity name="Alingi" publicKeyToken="ae4cc5eda5032777" />
      <bindingRedirect oldVersion="0.0.0.0-65535.65535.65535.65535"
        newVersion="6.0.0.0" />
  </dependentAssembly>
</assemblyBinding>

Version policy can be specified at three different levels. First, the author of an application that uses shared assemblies can specify version policy in the application configuration file. Second, the publisher of a shared assembly can provide version policy in what is called a publisher policy assembly. Finally, the machine administrator can specify version policy through entries in the machine.config file. When the CLR resolves a reference to a strong-named assembly, it begins by looking in these three locations for version policy statements that might redirect the assembly reference to a different version. The three policy levels also form a hierarchy in that they are evaluated in sequence with the output of one level feeding into the next. For example, say an application configuration file contains a policy statement that redirects all references to an assembly from version 1.0.0.0 to version 2.0.0.0. If the policy statement in the application configuration file applies to the reference being resolved, the CLR next evaluates publisher policy looking for any policy statements that redirect version 2.0.0.0 of the assembly. Likewise, administrator policy is evaluated based on the outcome of the publisher policy phase.

This brief description of version policy gives you what you need to understand the concepts presented in this chapter. For more details on how version policy is specified and resolved, see Chapter 2 and Chapter 3 in Applied Microsoft .NET Framework Programming (Microsoft Press, 2002) by Jeffrey Richter.

In Chapter 1, I introduced the typical architecture of an extensible application. In the last few chapters, I’ve made this architecture more concrete by describing the role that application domains play in applications that are extensible. Application domains exist for one purpose: as containers for assemblies. The main goal of this architecture is to provide the infrastructure in which to load assemblies dynamically. Let me review this architecture now and highlight the key design points that affect how the add-in assemblies are loaded (see Figure 7-2). The key points include the following:

Figure 7-2. The architecture of an extensible application

As described, the primary goal to keep in mind when designing your assembly loading infrastructure is always to call the assembly loading APIs from the application domain in which you intend the add-in assembly to be loaded. This design is shown in Figure 7-2 by the calls to AppDomain.Load originating in the application domain manager and resulting in the add-in assembly being loaded into the same domain. To get a clear picture of why this design goal is desirable, take a look at how assemblies are represented in the .NET Framework class libraries and how that representation relates to the CLR’s infrastructure for calling methods on a class in a different application domain.

System.Reflection.Assembly and CLR Remote Calls

Recall from Chapter 5 that calling a method on a type in another application domain is a remote call. The mechanics for a remote call are different depending on the marshaling characteristics of the type you are calling. Generally speaking, types are either considered marshaled by value or marshaled by reference in CLR remoting terminology. Types that are marshaled by reference are those types that derive from the System.MarshalByRefObject base class. When you call a method on a type derived from MarshalByRef in a different application domain, the CLR creates a proxy for that type in the calling application domain. All calls are made through the proxy to the actual type as shown in Figure 7-3.

Figure 7-3. Calling a MarshalByRefObject in a different application domain

In contrast, when a call is made to an object in another application domain that is marshaled by value, a copy of the instance is made in the calling domain. All objects that are marshaled by value must be marked with the [Serializable] custom attribute so the CLR knows how to transfer the object into the new domain. All calls on the type are made to the copy instead of through a proxy to the original as shown in Figure 7-4.

Figure 7-4. Calling a type in a different application domain that is marshaled by value

At this point, you might be wondering what this discussion about CLR remoting has to do with loading assemblies. This matters because the type used to represent assemblies in the .NET Framework class libraries, System.Reflection.Assembly, is marshaled by value, not by reference. Because instances of System.Reflection.Assembly are copied between application domains, it’s easy to inadvertently end up loading an assembly into an application domain unintentionally. Look at a concrete example to see how easy it is to make this mistake.

In Chapter 5 and Chapter 6, we used a CLR host called boatracehost.exe as an example of how to make effective use of application domains in an extensible application. We continue that example in this chapter as we discuss how to use the assembly loading APIs in conjunction with application domains. As described, you can use several APIs in the .NET Framework class libraries to load assemblies dynamically. AppDomain.Load is one of these methods that enables you to load an assembly into an application domain. Let’s say for purposes of example that a new boat is entering a race hosted by boatracehost. We’d like to load this add-in into a new application domain, so we use AppDomain.CreateDomain to create the new domain. We then call AppDomain.Load to load the boat add-in in the new domain as shown in the following code:

static void Main(string[] args)
{
   AppDomainSetup adSetup = new AppDomainSetup();
   adSetup.ApplicationBase = @"c:Program FilesBoatRaceHostAddins";

   AppDomain ad = AppDomain.CreateDomain("Alingi Domain",
                                          null,
                                          adSetup);

   Assembly alingiAssembly = ad.Load("Alingi, Version=5.0.0.0,
                                     PublicKeyToken=5cf360b40180107c,
                                     culture=neutral");
}

The call to AppDomain.Load in the preceding code is a remote call from the default application domain (in which main() is running) to the new domain held in the variable of type AppDomain named ad. AppDomain.Load takes as input the name of the assembly we’d like to load and returns an instance of System.Reflection.Assembly. Because Assembly is marshaled by value, a copy of the instance of the Assembly type is made in the default domain when the call to App-Domain.Load returns as shown in Figure 7-5.

Figure 7-5. An assembly inadvertently loaded into two application domains

Instances of Assembly contain data describing the underlying assembly they represent. For example, given an instance of Assembly, you can determine the assembly’s name, the assemblies it depends on, and so on. The underlying assembly represented by an instance of Assembly must be loaded into the application domain where the instance resides. In this example, this means that the Alingi assembly must be loaded into both the default application domain and the Alingi Domain. This side effect of calling AppDomain.Load affects our application design in a few key ways. First, the fact that the add-in assembly has been loaded into our default application domain means we can’t unload that assembly from our application without terminating the entire process. This is clearly undesirable from both the perspectives of memory usage and type visibility. Because we can never unload the assembly, we might be stuck dealing with the additional memory it consumes even when we no longer need the assembly within the application. Also, once an assembly is loaded into a given application domain, it can discover all other assemblies in that same domain using the GetAssemblies method on the AppDomain type. Once another assembly is discovered, it can be reflected upon using the types in the System.Reflection namespace. If the code access security policy for that domain isn’t configured to disallow it, code in an add-in assembly could even invoke methods on any other assembly loaded in the same domain.

The other reason loading an add-in into the default application domain affects our design is that it complicates the deployment of the add-in. Recall from Chapter 6 that each application domain has an ApplicationBase that establishes a root directory in which assemblies for that domain can be deployed. In the preceding code sample, the ApplicationBase for Alingi Domain has been set to c:program filesoatracehostaddins. By deploying the Alingi assembly to that directory, it is found by the CLR when we call AppDomain.Load. However, because we’ve also inadvertently added Alingi to the default application domain, the add-in must be deployed to a location where the CLR will find it for that domain as well. This means deploying the add-in to another ApplicationBase or adding it to a global location such as the global assembly cache (GAC). This subtlety often results in unexpected failures to load an assembly. For example, in looking at the previous code, it’s obvious that we need to deploy our add-in to c:program filesoatracehostaddins. However, if we did just that, we’d get a FileNotFoundException telling us that the assembly we’re loading cannot be found. When I see these errors, I typically look in the directory in which I expect the assembly to be found, and, seeing it there, I’m at a loss for a few minutes before I realize that the CLR is trying to load my assembly into an application domain I never intended. Because of all this, it is far better to call the assembly loading APIs from within the domain in which you intend the add-in to be loaded.

public interface IBoatRaceDomainManager
{
   // loads the boat identified by boatTypeName from the
   // assembly in assemblyName into the application domain
   // in which this instance of the domain manager is
   // running.
   void EnterBoat(string assemblyName, string boatTypeName);
}

public class BoatRaceDomainManager : AppDomainManager,
                                     IBoatRaceDomainManager
{
   void EnterBoat(string assemblyName, string boatTypeName)
   {
      // load the boat into this application domain...
   }
}

AppDomainSetup adSetup = new AppDomainSetup();
adSetup.ApplicationBase = @"c:Program FilesBoatRaceHostAddins";

AppDomain ad = AppDomain.CreateDomain("Alingi Domain",
                                    null,
                                    adSetup);

BoatRaceDomainManager adManager = (BoatRaceDomainManager)ad.DomainManager;

adManager.EnterBoat("AlingiBoat", "Alingi, Version=5.0.0.0,
                     PublicKeyToken=5cf360b40180107c,
                     culture=neutral);

public class BoatRaceDomainManager : AppDomainManager,
                                     IBoatRaceDomainManager
{
   void EnterBoat(string assemblyName, string boatTypeName)
   {
      // load the assembly containing boat into this
      // application domain...
      Assembly alingiAssembly = AppDomain.CurrentDomain.Load(assemblyName);

      // load the type from the new assembly...
   }
}

Now that I’ve shown how best to make use of the assembly loading APIs within your application, let’s dig into the details of the APIs themselves. As described, several methods in the .NET Framework provide the ability to load an assembly dynamically given an assembly identity—the AppDomain.Load method used in the previous section is just one such API. In some cases, multiple APIs provide the same functionality and are therefore redundant, but in other cases the APIs offer different capabilities. For example, some APIs enable you to load an assembly into a different application domain, whereas some load an assembly only into the current domain. Following are the methods in the .NET Framework that enable you to load an assembly and brief descriptions of each method’s capabilities. Keep in mind that these are the APIs that enable you to load an assembly given an assembly name. Several APIs enable you to load an assembly by providing the name of the file containing the manifest. I cover these APIs later on in the section, "Loading Assemblies by Filename."

As you can see from the preceding list, the assembly loading APIs enable you to specify the assembly to load either by supplying its identity as a string or by providing an instance of System.Reflection.AssemblyName. In addition, each API has an overload that lets you associate security evidence with the assembly you are loading. I cover the details of using this parameter in Chapter 10.

Note

It’s often the case that the first thing you’d like to do after loading an assembly is create a type from that assembly. To support this scenario, the .NET Framework provides several APIs that enable you to load an assembly and create a type with a single method call. When using these APIs, you pass the name of the type you’d like to create in addition to the name of the assembly you’d like to load. These convenience methods eliminate a lot of boilerplate code you’d find yourself writing over and over again. The methods that enable you to load an assembly and create a type are these:

• System.AppDomain.CreateInstance

• System.AppDomain.CreateInstanceAndUnwrap

• System.Activator.CreateInstance

With respect to assembly loading, these methods work just like the ones in the preceding list, so I don’t talk about them explicitly in this chapter. Documentation of these methods can be found in the .NET Framework SDK.

Specifying Assembly Identities as Strings

When specifying an assembly identity by string, you must follow a well-defined format that the CLR understands. This format enables you to specify all four parts of an assembly’s name: the friendly name, version number, culture, and information about the public portion of the cryptographic key pair used to give the assembly a strong name. The string form of an assembly is as follows:

"<friendlyName>, Version=<version number>, PublicKeyToken=<publicKeyToken>,
   Culture=<culture>"

When specifying identities in this format, the <friendlyName> portion of the identity must come first. The PublicKeyToken, Version, and Culture elements can be specified in any order. Strings that follow this format are passed directly to the assembly loading APIs as shown in the following simple example:

public class BoatRaceDomainManager : AppDomainManager,
                                     IBoatRaceDomainManager
{
   void EnterAlingi()
   {
      // load the assembly into this application domain...
      Assembly a = Assembly.Load("Alingi, Version=5.0.0.1,
                                  PublicKeyToken=3026a3146c675483,
                                  Culture=neutral");
      // load the type from the new assembly...
    }
 }

As I explained earlier, it is possible to reference an assembly by supplying less than the full identity. I cover the details of how such references work in the section "Partially Specified Assembly References" later in the chapter.

Specifying assembly identities using the string format is generally straightforward as long as the CLR can correctly parse the string you supply. Any extra characters in the string (such as duplicate commas) or misspelled element names will cause a FileLoadException exception to be raised and your assembly will not be loaded.

Note

The CLR error checking process when parsing assembly identities in .NET Framework 2.0 is much stricter than it was in previous versions of the CLR. For example, any extra characters or unrecognized element names (such as those caused by misspellings) were simply ignored instead of flagged as errors in previous versions. As always, make sure you thoroughly test your application on all versions of the CLR you intend to support to catch subtle differences like this.

Failures to load an assembly because of errors in parsing the assembly identity are easy to diagnose because the instance of FileLoadException that is thrown contains a specific message and HRESULT. The HRESULT indicating a parsing error is 0x80131047 (this error code is defined as FUSION_E_INVALID_NAME in the file corerror.h from the include directory in the .NET Framework SDK). The message property of the exception will say, "Unknown error -HRESULT 0x80131047."

In addition to forming the string correctly, it’s important that the values you supply for each element are valid. The following points summarize the valid values for friendly name, culture, and version.

• Friendly name. Friendly names can contain any characters that are valid for naming files in the file system. Friendly names are not case sensitive.

• Version. Assembly version numbers consist of four parts as specified in the following format:

  Major.minor.build.revision

  When specifying a version number, it’s best to include all four parts because the CLR will make sure that the version number of the loaded assembly exactly matches the version number you specify. You can omit values for some portions of the version number, but doing so results in a partial reference. When resolving an assembly based on a partial version number reference, the CLR matches only those portions of the version number you provide. This looseness in binding semantics can cause you to load an assembly inadvertently. For example, given the following reference:

  "Alingi, Version=5, PublicKeyToken=3026a3146c675483, Culture=neutral"

  the CLR only makes sure that the major number of the assembly you load is 5—none of the other portions of the version number are checked. In other words, the first assembly found in the application directory (the global assembly cache is not searched when resolving a partial reference) whose major number is 5 will be loaded regardless of the values for the other three portions of the version number. I cover partial references in more detail later in the chapter.

• Culture. Values for the culture element of the assembly name follow a format described by RFC 1766. This format includes both a code for the language and a more specific code for the region. For example, "de-AT" is the culture value for German-Austria, whereas "de-CH" represents German-Switzerland. See the documentation for the System.Globalization.CultureInfo class in the .NET Framework SDK for more details.

The public key token portion of an assembly name requires a bit more explanation. Typing an entire 1024-bit (or larger) cryptographic key when referencing an assembly would be overly cumbersome. To make referencing strong-named assemblies easier, the CLR enables you to provide a shortened form of the key called a public key token. A public key token is an 8-byte value derived by taking a portion of a hash of the entire public key. Fortunately, the .NET Framework SDK provides a tool called the Strong Name utility (sn.exe) so you don’t have to be a cryptography wizard to obtain a public key token. The easiest way to obtain the public key token from an assembly is to use the -T option of sn.exe. For example, issuing the following command at a command prompt:

C:ProjectsAlingi> sn –T Alingi.dll

yields the following output:

Microsoft (R) .NET Framework Strong Name Utility Version 2.0.40301.9
Copyright (C) Microsoft Corporation 1998-2004. All rights reserved.

Public key token is 3026a3146c675483

From here, you can paste the public key token value into your source code.

public class BoatRaceDomainManager : AppDomainManager,
                                     IBoatRaceDomainManager
   {
       void EnterBoat()
       {
          // load the assembly into this
          // application domain...
          AssemblyName name = new AssemblyName();
          name.Name = "Alingi";

             Assembly a = Assembly.Load(name);

          // load the type from the new assembly
       }
   }

The CLR follows a consistent, well-defined set of steps to locate the assembly you’ve specified when calling one of the assembly-loading APIs. These steps are different based on whether you are referencing a strong-named assembly or a weakly named one.

Note

All aspects of the CLR’s behavior for loading assemblies can be customized by you as the author of an extensible application. In Chapter 8, I write a CLR host that shows the extent of customization possible.

Understanding the steps the CLR follows to load an assembly is essential when building an extensible application that can work well in a variety of add-in deployment scenarios. Several factors influence both the version and the location of the assembly the CLR loads given your reference. Some factors are aspects of the deployment environment that you can control, such as the base directories for the application domains you create. Other factors, such as the specification of version policy by an administrator or the author of a shared assembly, are beyond your control. Fortunately, great tools are available for you to understand how the CLR locates assemblies and diagnose any problems you might encounter. I cover how to use these tools after describing the steps the CLR uses to locate assemblies.

The factors the CLR considers when resolving an assembly reference include deployment locations and the presence of any version policy or assembly codebase locations as shown in Figure 7-6 and described in the following points.

Figure 7-6. Factors that influence how the CLR locates assemblies

How the CLR Locates Assemblies with Weak Names

Weakly named assemblies can be loaded only from an application domain’s ApplicationBase or a subdirectory thereof. As a result, the CLR’s rules for finding such an assembly are relatively straightforward. The CLR follows two steps when resolving a reference to an assembly with a simple name:

1. Look for a codebase in the application configuration file.

2. Probe for the assembly in the ApplicationBase and its subdirectories.

Step 1 rarely applies when loading add-ins into extensible applications. This is primarily because authoring a configuration file to specify a location for an assembly requires up-front knowledge that such an assembly will be loaded. As I mentioned, this isn’t the case with extensible applications because the add-ins are typically loaded dynamically. So the only way to use a configuration file to specify a codebase in this case is if somehow the configuration file was shipped along with the add-in and you set the ConfigurationFile property of your application to use it. Although possible, this scenario is unlikely to occur in practice.

Given that step 1 isn’t likely to apply, loading weakly named add-ins into extensible applications typically involves looking for the assembly in the ApplicationBase and its subdirectories. This process, termed probing, is described in detail in Chapter 6. Remember, too, that weakly named assemblies are loaded by name only—no other elements of the assembly name, such as the assembly’s version, are checked.

Note

It is possible to end up loading a strongly named assembly given a reference that appears to be to a weakly named assembly. This happens if you have a strong-named assembly deployed somewhere in your ApplicationBase directory structure whose friendly name matches the name you are referencing using one of the assembly loading APIs. For example, given the following reference:

Assembly a = Assembly.Load("Alingi");

The CLR will load the first file it finds named alingi.dll, regardless of whether it has a strong name or a weak name. If the assembly it loads has a strong name, the CLR essentially starts over by taking the identity of the assembly and loading and treating that as a strong-name reference to resolve. In the next section I describe the steps involved in loading a strong-named assembly. A strong-named assembly could get loaded given the preceding reference because that reference is partial—no value is supplied for the public key token. This situation would not occur in scenarios in which the reference is fully specified, such as when an assembly is referenced in an early-bound fashion. If you want to be sure that only a weakly named assembly is loaded in this case, you must specify a null public key token like this:

Assembly a = Assembly.Load("Alingi, PublicKeyToken=null");

Using System.Reflection.Assembly to Determine an Assembly’s Location on Disk

Once an assembly has been loaded, you can use the CodeBase, Location, and GlobalAssemblyCache properties of the Assembly class to determine information about where the CLR found it.

The Location and CodeBase properties are very similar in that they both provide information about the physical file from which the assembly was loaded. In fact, these two properties have the same value when an assembly is loaded from the local computer’s disk into an application domain that does not have shadow copy enabled. In this scenario, these two properties simply give you the name of the physical file on the local disk from which the assembly was loaded. The CodeBase and Location properties differ in two scenarios, however. First, if the assembly was downloaded from an HTTP server, the CodeBase property gives the location of the file on the remote server, whereas the Location property gives the location of the file in the downloaded files cache on the local machine. These properties also have different values if an assembly is loaded into an application domain in which shadow copy is enabled. In this scenario, CodeBase gives you the original location of the file, whereas Location tells you the location to which the file was shadow copied. See Chapter 6 for more information about how to enable shadow copy for the application domains you create.

Note

The Assembly class also has a property called EscapedCodeBase that gives you the same pathname as CodeBase, except the value returned has the original escape characters.

The GlobalAssemblyCache property is a boolean value that tells you whether the CLR loaded the assembly from the GAC.

The .NET Framework SDK includes a tool called the Assembly Binding Log Viewer (fuslogvw.exe) that is great not only for diagnosing errors encountered when loading assemblies, but also to help understand the assembly loading process in general. Fuslogvw.exe works by logging each step the CLR completes when resolving a reference to an assembly. These logs are written to .html files that can be viewed using the fuslogvw.exe user interface. The logging is turned off by default because of the expense involved in generating the log files. You can turn on logging in one of two modes: you can choose to log every attempt to load an assembly or log only those attempts that fail. Logging is enabled using the Settings dialog box from the fuslogvw.exe user interface as shown in Figure 7-7.

Figure 7-7. Enabling logging using fuslogvw.exe

Take a look at how the output generated by fuslogvw.exe helps you understand how the CLR locates assemblies. After turning logging on, I ran boatracehost.exe and had it load an add-in from an assembly called TeamNZ. In this simple example, fuslogvw.exe logged that we attempted to load three assemblies as shown in Figure 7-8.

Figure 7-8. Fuslogvw.exe after running boatracehost.exe

Double-clicking the row labeled TeamNZ displays the log generated while the CLR resolved the reference to that assembly. The log text is as follows:

0| *** Assembly Binder Log Entry (4/2/2004 @ 4:30:15 PM) ***
1| The operation was successful.
2| Bind result: hr = 0x0. The operation completed successfully.
3| Assembly manager loaded from:
   C:WINDOWSMicrosoft.NETFrameworkv2.0.40301mscorwks.dll
4| Running under executable
   C:Program FilesBoatRaceHostBoatRaceHostinDebugBoatRaceHost.exe
5| --- A detailed error log follows.
6| === Pre-bind state information ===
7| LOG: DisplayName = TeamNZ
 (Partial)
8| LOG: Appbase = file:///C:/Program Files/BoatRaceHost/BoatRaceHost/bin/Debug/
9| LOG: Initial PrivatePath = NULL
10| LOG: Dynamic Base = NULL
11| LOG: Cache Base = NULL
12| LOG: AppName = BoatRaceHost.exe
13| Calling assembly : BoatRaceHost, Version=1.0.1553.29684, Culture=neutral,
   PublicKeyToken=null.
===
14| LOG: Attempting application configuration file download.
15| LOG: Download of application configuration file was attempted from
   file:///C:/Program Files/BoatRaceHost/BoatRaceHost/bin/
   Debug/BoatRaceHost.exe.config.
16| LOG: Application configuration file does not exist.
17| LOG: Using machine configuration file from
   C:WINDOWSMicrosoft.NETFrameworkv2.0.40301configmachine.config.
18| LOG: Policy not being applied to reference at this time (private, custom,
   partial, or location-based assembly bind).
19| LOG: Attempting download of new URL
   file:///C:/Program Files/BoatRaceHost/BoatRaceHost/bin/Debug/TeamNZ.dll.
20| LOG: Attempting download of new URL
   file:///C:/Program Files/BoatRaceHost/BoatRaceHost/bin/
   Debug/TeamNZ/TeamNZ.dll.
21| LOG: Assembly download was successful. Attempting setup of file:
   C:Program FilesBoatRaceHostBoatRaceHostinDebugTeamNZTeamNZ.dll
22| LOG: Entering run-from-source setup phase. 23| LOG: A partially-
specified assembly bind succeeded from the application
   directory. Need to re-apply policy.
24| LOG: Policy not being applied to reference at this time (private, custom,
   partial, or location-based assembly bind).

I annotated the log text with line numbers so we can step through this in detail.

Lines 1–2 show whether the attempt to load the assembly succeeded. In error conditions, you can look up the HRESULT in the corerror.h file in the .NET Framework SDK to help determine what went wrong. However, the rest of the log explains the failure in detail.

Line 3 shows the directory from which the CLR was loaded. You can use this to determine which version of the CLR was running when this assembly bind was attempted.

Line 4 displays the name of the executable that initiated the assembly load. In our case, the executable is boatracehost.exe.

Line 7 shows the identity of the assembly we are trying to load. In late-bound cases such as this, this is the assembly identity that was passed to the assembly loading APIs. In addition to providing the identity, line 7 tells you whether the reference is partial or fully specified. This particular reference is partial. It was initiated with a simple call to Assembly.Load such as this:

Assembly a = Assembly.Load("TeamNZ");

Line 8 displays the ApplicationBase directory for the application domain in which the assembly load was initiated.

Lines 9–12 show some of the application domain properties that can affect how assemblies are loaded. These properties are covered in Chapter 6.

Line 13 gives the name of the assembly from which this assembly load was made. This information is useful for debugging in cases in which you might make the same attempt to load an assembly in several places throughout your application.

Lines 14–16 show the CLR attempting to find the configuration file associated with the application domain making the request. As described, this configuration file is consulted both for version policy information and for codebase locations.

Line 17 gives the location of the administrator configuration file. Again, this file can contain either version policy or codebase information.

Line 18 states that version policy is not being applied to this reference. In our case, version policy isn’t being applied because we have a partial reference. I discuss the output generated when resolving a fully qualified reference to a strong-named assembly in a bit. Version policy gets applied in that example.

Lines 19–22 show how the CLR probes for the assembly in the ApplicationBase directory. In this example, you can see that the first attempt to find the assembly failed, but the second one succeeded. The statement "Entering run-from-source setup phase" means that the CLR is loading the assembly directly from its location on disk. In contrast, if the assembly were located on an HTTP server, it would have to be downloaded first before it could be loaded.

Lines 23–24 state that the assembly was loaded from the ApplicationBase and that version policy is not being applied. In our case, version policy isn’t being applied because the assembly that was found has a weak name. If we had happened to load a strong-named assembly from the ApplicationBase, the CLR would look at the identity of the assembly that was loaded and go back and reapply version policy to determine whether a different version of the assembly should be loaded. If so, it would start the process of finding the assembly over again with the new reference.

You will see two primary differences in the log when you load a strong-named assembly—version policy is applied to the reference, and the CLR looks in the GAC as shown in the following output from fuslogvw.exe:

0| *** Assembly Binder Log Entry (4/4/2004 @ 12:27:26 PM) ***
1| The operation was successful.
2| Bind result: hr = 0x0. The operation completed successfully.
3| Assembly manager loaded from:
   C:WINDOWSMicrosoft.NETFrameworkv2.0.40301mscorwks.dll
4| Running under executable
   C:Program FilesBoatRaceHostBoatRaceHostinDebugBoatRaceHost.exe
5| --- A detailed error log follows.
6| === Pre-bind state information ===
7| LOG: DisplayName = Alingi, Version=5.0.0.0, Culture=neutral,
   PublicKeyToken=ae4cc5eda5032777
   (Fully specified)
8| LOG: Appbase = file:///C:/Program Files/BoatRaceHost/BoatRaceHost/bin/Debug/
9| LOG: Initial PrivatePath = NULL
10| LOG: Dynamic Base = NULL
11| LOG: Cache Base = NULL
12| LOG: AppName = BoatRaceHost.exe
13| Calling assembly : BoatRaceHost, Version=1.0.1555.20566, Culture=neutral,
   PublicKeyToken=null.
===
14| LOG: Attempting application configuration file download.
15| LOG: Download of application configuration file was attempted from
   file:///C:/Program Files/BoatRaceHost/BoatRaceHost/bin/
   Debug/BoatRaceHost.exe.config.
16| LOG: Application configuration file does not exist.
17| LOG: Using machine configuration file from
   C:WINDOWSMicrosoft.NETFrameworkv2.0.40301configmachine.config.
18| LOG: No redirect found in host configuration file.
19| LOG: Machine configuration policy file redirect found: 5.0.0.0 redirected
   to 6.0.0.0.
20| LOG: Post-policy reference: Alingi, Version=6.0.0.0, Culture=neutral,
   PublicKeyToken=ae4cc5eda5032777
21| LOG: Found assembly by looking in the GAC.

In this example, I used the .NET Framework Configuration tool to specify machine-level version policy to redirect the version of the assembly I’m referencing from 5.0.0.0 to 6.0.0.0. The differences between this assembly load and the previous one are shown in lines 7, 19, 20, and 21.

Line 7 shows that the reference is fully specified. Values are supplied for all four parts of the assembly’s name.

Line 19 shows that the CLR found my version policy statement in the machine configuration file.

Line 20 shows my reference after policy has been applied. Notice that the CLR is now looking for version 6.0.0.0 of Alingi.

Line 21 shows that the assembly was found in the GAC.

As you can see, stepping through the logs generated by fuslogvw.exe removes the mystery behind how the CLR locates assemblies. Fuslogvw.exe has several other options I haven’t discussed here. See the .NET Framework SDK documentation for more details.

Failures to load assemblies typically show up in your application as one of three types of exceptions:

All three exceptions have a string property called FusionLog that contains the text of a log file like those you viewed earlier in the discussion of fuslogvw.exe. In this way, you get the diagnostic information about why your call to the assembly loading APIs failed without having to enable logging using the fuslogvw.exe user interface.

As described, only the assembly’s friendly name is required when you’re using late-bound references. Values for the public key token, version, and culture can be omitted. Such partially specified assembly references are convenient to use, especially when your intent is to load weakly named assemblies, regardless of version, from your application directory. To do so, all you need to do is called Assembly.Load with the assembly’s friendly name as I’ve done several times throughout this chapter:

Assembly a = Assembly.Load(TeamNZ);

However, a few complexities might cause you to load an assembly unintentionally. As always, you can use the fuslogvw.exe tool to find out exactly what’s going on.

The following points summarize how the CLR treats a partially specified reference:

I mentioned earlier that the CLR makes sure applications behave deterministically regardless of the order in which their dependencies are loaded. To provide this guarantee, the CLR must ensure that assemblies loaded dynamically by filename do not conflict with the assemblies the application has referenced statically. Take a look at an example to better understand how these rules work and how they might affect you as the author of an extensible application.

The .NET Framework SDK contains a tool called regasm.exe. Regasm.exe takes an assembly as input and creates a set of registry keys that allow the public types in that assembly to be created from COM. What makes regasm.exe interesting for our example is not this core functionality, but rather the fact that it takes the filename of an assembly and loads it dynamically using Assembly.LoadFrom. You can expect to encounter this same sort of scenario in an extensible application—it’s entirely possible that your extensibility model involves obtaining the filenames of the add-in assemblies you’d like to load into your application domains.

Regasm.exe depends on a utility assembly called regcode.dll, which, for the purposes of this example, has a weak name and is installed in the same directory as regasm.exe.

C:
egasm
   Regasm.exe
   Regcode.dll

The dependency between these two assemblies is specified at compile time, so regasm.exe has an early-bound reference to regcode.dll recorded in its assembly manifest. Now say that a user invokes regasm.exe and passes in the filename to a completely different assembly that is coincidentally also called regcode.dll:

C:
egasm
egasm.exe c:	emp
egcode.dll

If the regcode.dll in c: emp were substituted for the "real" regcode.dll in the application directory, regasm.exe wouldn’t run if for no other reason than the types it expects to find in regcode.dll wouldn’t exist.

To solve this problem, the CLR isolates assemblies loaded using Assembly.LoadFrom from those that are referenced statically by the application by using a concept called binding contexts. Every application domain maintains two load contexts, or lists of loaded assemblies. One context, called the load context, contains those assemblies referenced statically by the application. The other context, the loadfrom context, contains those assemblies loaded dynamically given a filename. In our case, the regcode.dll from the ApplicationBase is loaded into the load context, and the regcode.dll that was loaded dynamically from c: emp is placed in the loadfrom context as shown in Figure 7-9. Notice also that the application also has some static dependencies on the .NET Framework assemblies; thus, they are loaded in the load context as well.

Figure 7-9. The CLR maintains a load context and a loadfrom context in every application domain.

0| *** Assembly Binder Log Entry (4/8/2004 @ 8:46:58 AM) ***
1| The operation was successful.
2| Bind result: hr = 0x0. The operation completed successfully.
3| Assembly manager loaded from:
   C:WINDOWSMicrosoft.NETFrameworkv2.0.40301mscorwks.dll
4| Running under executable
   C:Program FilesBoatRaceHostBoatRaceHostinDebugBoatRaceHost.exe
--- A detailed error log follows.

=== Pre-bind state information ===
5| LOG: Where-ref bind. Location = c:	empAlingi.dll
6| LOG: Appbase = file:///C:/Program Files/BoatRaceHost/BoatRaceHost/bin/Debug/
7| LOG: Initial PrivatePath = NULL
8| LOG: Dynamic Base = NULL
9| LOG: Cache Base = NULL
10| LOG: AppName = BoatRaceHost.exe
11| Calling assembly : (Unknown).
===
12| WRN: Native image will not be probed in LoadFrom context. Native image will
   only be probed in default load context, like with Assembly.Load().
13| LOG: Attempting application configuration file download.
14| LOG: Download of application configuration file was attempted from
   file:///C:/Program Files/BoatRaceHost/BoatRaceHost/bin/
   Debug/BoatRaceHost.exe.config.
15| LOG: Application configuration file does not exist.
16| LOG: Using machine configuration file from
   C:WINDOWSMicrosoft.NETFrameworkv2.0.40301configmachine.config.
17| LOG: Attempting download of new URL file:///c:/temp/Alingi.dll.
18| LOG: Assembly download was successful. Attempting setup of file:
   c:	empAlingi.dll
19| LOG: Entering run-from-source setup phase.
20| LOG: Re-apply policy for where-ref bind.
21| LOG: No redirect found in host configuration file.
22| LOG: Post-policy reference: Alingi, Version=5.0.0.0, Culture=neutral,
   PublicKeyToken=ae4cc5eda5032777
23| LOG: GAC Lookup was unsuccessful.
24| LOG: Where-ref bind Codebase does not match what is found in default
   context.

Assembly loadFromAssembly = Assembly.LoadFrom(@"c:	empRegcode.dll");
Object loadFromInstance =
    loadFromAssembly.CreateInstance("Regcode.UtilClass");
  Regcode.UtilClass loadInstance = (Regcode.UtilClass)loadFromInstance; //FAIL!

Assembly alingiA = Assembly.LoadFrom(@ c:addinsAlingi.dll );
Assembly alingiB = Assembly.LoadFrom(
   @ c:program filesoatracehostcommonAlingi.dll");

The Loadfrom Context and Dependencies

Earlier in this chapter and in Chapter 6, I describe how the CLR looks for weakly named assemblies only within the ApplicationBase directory structure of the referencing application. As with many things, there is an exception to this rule. When you load an assembly with LoadFrom, the CLR adds the directory from which that assembly came to the list of directories in which it probes for static dependencies. For example, say that alingi.dll has an early-bound dependency on an assembly in spars.dll. Furthermore, boatracehost.exe loads alingi.dll from c: emp using Assembly.LoadFrom. In this case, you can deploy spars.dll to c: emp, and the CLR will find it, even though it is not located in boatracehost.exe’s ApplicationBase directory. This feature makes it convenient to deploy an add-in and all of its dependencies to the same directory. However, be aware that this directory is searched last. Specifically, the CLR looks in the GAC (if the assembly has a strong name) and in the ApplicationBase directory before consulting the directory from which the referring assembly was loaded. As a result, if the CLR happens to find an assembly that satisfies the reference to spars.dll (in this case) in any other location, that DLL would be loaded instead of the one in c: emp.

Note

In an effort to reduce some of the confusion around using Assembly.LoadFrom, the CLR introduced a new API called Assembly.LoadFile in .NET Framework 1.1. The intent of this API was to load the exact file specified as opposed to issuing a second bind and doing identity checks that can cause an assembly other than the intended one to be loaded. Although LoadFile did work this way in .NET Framework 1.1, its behavior has been changed in .NET Framework 2.0 to be subject to version policy and rebinding just as LoadFrom is. As a result, the CLR team is discouraging its use. I expect LoadFile to be removed in a future version of the .NET Framework.

The 2.0 version of the .NET Framework introduces a new set of APIs called the ReflectionOnly APIs. I mention them here only because the ReflectionOnly APIs provide a way to load an assembly by filename without any of the subtleties inherent in Assembly.LoadFrom. That is, you can use the ReflectionOnly APIs to load exactly the file you want—no policy is applied, no second bind occurs, and so on. Although this might sound like exactly what you’re looking for, the scenarios for which the ReflectionOnly APIs were built do not include the ability to load and execute assemblies dynamically. Specifically, the ReflectionOnly APIs enable you only to discover information about an assembly, they do not enable you to execute any code in that assembly. For this reason, they will not help you if you need to load and execute add-ins in an extensible application. For this reason, I don’t discuss them here. For more information, see the documentation for the following methods in the .NET Framework SDK guide:

As described in Chapter 4, every assembly contains information about the version of the .NET Framework it was compiled with. Being able to determine which version of the .NET Framework was used to build a particular add-in can be useful, especially if you begin to see problems in your application that you believe are version related. The version of the .NET Framework used to build an assembly can be obtained using the ImageRuntimeVersion property on System.Reflection.Assembly. Keep in mind, however, that the version number this property returns is the CLR version number, not the version number of the .NET Framework itself. For example, Assembly.ImageRuntimeVersion returns the string "v1.1.4322" for an assembly built with .NET Framework 1.1. Table 7-3 shows the CLR versions and the corresponding versions of the .NET Framework. Refer to Chapter 4 for a more complete description of how these version numbers relate.

There is one caveat when using the ImageRuntimeVersion property. The fact that ImageRuntimeVersion is a member of the Assembly class means that the CLR must load the assembly for which you’d like version information into the process before you can access the property. If you then decide that you don’t want to use the assembly, you can’t unload it without unloading the application domain containing the assembly. If you need to be able to determine which version of the CLR was used to build an assembly without having to load it, you need to use an unmanaged API. The CLR startup shim, mscoree.dll, provides an unmanaged API for exactly this purpose. This API, called GetFileVersion, takes an assembly’s filename and returns the version number used to build that assembly in a buffer. Here’s the signature for GetFileVersion from mscoree.idl in the .NET Framework SDK:

STDAPI GetFileVersion(LPCWSTR szFilename,
                      LPWSTR szBuffer,
                      DWORD  cchBuffer,
                      DWORD* dwLength)

As discussed in Chapter 3, only one version of the CLR can be loaded into a given process. It’s up to you, as the author of the extensible application, to decide which version to load. The add-ins that you dynamically load into your process have no say in which version of the CLR is loaded. Furthermore, no infrastructure currently available allows an add-in to express a dependency on a particular version of the CLR.

As discussed in Chapter 3 and Chapter 4, it’s typically best to load the same version of the CLR that you used to build your application. Refer to those chapters for both the strategies to consider and the mechanics involved in loading the CLR.

At any point you can determine which version of the CLR is loaded into your process using the Version property on the System.Environment class. This property returns the CLR version, not the .NET Framework version. For example, the value of System.Environment.Version for a process running .NET Framework 2.0 is "2.0.41013." Table 7-3 contains the mapping between CLR version numbers and the corresponding versions of the .NET Framework.

When you load an add-in assembly into your process, that assembly contains static references to the versions of the .NET Framework assemblies it was built against. For example, an assembly built with .NET Framework 1.1 has references to the 1.1 versions of System, System.XML, System.Data, and so on. If you load several add-ins into your process, some of which are built with different versions, you’ll have references to multiple versions of the .NET Framework assemblies. Figure 7-10 shows a scenario in which an extensible application built against .NET Framework 2.0 has loaded add-ins built against all three versions of the .NET Framework.

Figure 7-10. An extensible application with references to add-ins built with multiple versions of the .NET Framework

Given this scenario, the question arises as to whether it is preferable to load multiple versions of the .NET Framework assemblies into the same process or redirect the various references to a single version of the .NET Framework assemblies. Clearly, there are arguments for doing it either way. On the one hand, it might be desirable to load the exact version of the .NET Framework assemblies that a given add-in has requested. After all, presumably the add-in was tested against this version; therefore, it has the best chance to work. On the other hand, loading multiple versions of the .NET Framework assemblies into the same process has two complications: one is technical, whereas the other is a matter of logistics. Although it is technically feasible to load multiple versions of the same assembly into a given application domain or process, complications arise if two add-ins built against different versions of the .NET Framework need to communicate by exchanging types. Because the identity of the assembly in which a type is contained is part of that type’s identity, a given type from two different versions of the same assembly is considered a different type by the CLR. For example, an XMLDocument type from version 2.0.3600 of System.XML is a different type than the XMLDocument type from version 1.0.3705 of System.XML. As a result, the CLR throws an exception if an assembly tries to pass an instance of the 1.0.3705 version of XMLDocument to a method on a type expecting a 2.0.3600 version of XMLDocument. The amount different add-ins need to communicate with each other clearly varies by scenario, so it might be possible that this particular restriction isn’t an issue for you. However, the other complication that arises when multiple versions of the .NET Framework assemblies are loaded simultaneously is related to the consistency between assemblies. From the beginning, the .NET Framework assemblies were built to work as a matched set. Several interdependencies between these assemblies must remain consistent. Also, because mixing and matching these assemblies hasn’t been a priority yet, the amount of testing done by Microsoft to support these scenarios has been limited.

As a result of the complexities involved in loading multiple versions of the .NET Framework assemblies into a process or application domain, the default behavior of the CLR is to redirect all references to .NET Framework assemblies to the version of those assemblies that matches the CLR that is loaded into the process. The process of redirecting all references to this matched set is termed .NET Framework unification. The result of this unification is shown in Figure 7-11.

Figure 7-11. The CLR unifies all references to .NET Framework assemblies.

It’s important to remember that only references to the .NET Framework assemblies are unified. All other assembly references are resolved as is (subject to version policy, of course). For example, say you load two add-in assemblies that reference different versions of the same shared assembly called AcmeGridControl. Because AcmeGridControl is not a .NET Framework assembly, references to it will not be unified. Instead, both versions are loaded. The following is a list of those assemblies that are unified by the CLR:

If the unification of .NET Framework assembly references causes problems in your scenario, you can override the unification using version policy statements. You shouldn’t have to resort to this too often because the CLR’s backward compatibility has been pretty good so far. However, it’s not inconceivable for you to encounter a compatibility issue that will cause you to want to load a different version of a .NET Framework assembly than the one the CLR selects by default. The best way to override unification is by issuing version policy statements in the configuration file for a particular application domain. This approach is preferable to using machine-wide policy because it affects only your application domain(s), not every process on the machine (also, it’s often the case that the machine configuration file is secured, so you can’t write to it anyway unless you’re an administrator).

To see how this works, consider an example in which a particular add-in that you must load has a strict dependency on the version of System.XML that shipped with version 1.1 of the .NET Framework, but you are running .NET Framework 2.0 in your process. To redirect the reference to System.XML from .NET Framework 2.0 back down to .NET Framework 1.1, you’d author a configuration file that looks like this:

<?xml version="1.0"?>
<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="System.Xml"
           publicKeyToken="b77a5c561934e089" />
        <bindingRedirect oldVersion="0.0.0.0-2.0.3600"
           newVersion="1.1.5000" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

This configuration file causes version 1.1.5000 of System.XML (the version that shipped in .NET Framework 1.1) to be loaded regardless of which version is referenced. Given this configuration file, you have the choice of how widely you’d like to apply this redirection. It can be that you want 1.1.5000 to be the only version of System.XML that is loaded in your process. In this case, you’d assign your configuration file to every application domain you create using the ConfigurationFile property of AppDomainSetup as described in Chapter 6. You might also choose to load System.XML version 1.1.5000 only into the application domain in which the add-in that requires it is running. If so, add-ins in other application domains that reference System.XML will get the unified version (the version that ships with .NET Framework 2.0).

Note that it is also possible to use version policy statements to cause all references to the .NET Framework assemblies to be redirected for a particular application domain. If you start by redirecting one reference, you might find inconsistencies that cause you to want to redirect the entire set of references to .NET Framework assemblies. In this way, you can cause two parallel stacks of .NET Framework assemblies to be loaded into the same process, yet be isolated from each other using application domain boundaries as shown in Figure 7-12.

Figure 7-12. Using a configuration file to override .NET Framework unification

Note

Even though mscorlib is in the set of unified assemblies, you cannot use a bindingRedirect statement (or any other mechanism) to override the unification of mscorlib. The version of mscorlib to load is chosen by the CLR when the process starts and cannot be changed.