Partial Assembly References

A full assembly reference includes the assembly's text name, version, culture, and public key token (if the assembly has a strong name). A full assembly reference is required if you reference any assembly that is part of the common language runtime or any assembly located in the global assembly cache. You can also dynamically reference an assembly by providing only partial information, such as specifying only the assembly name.

The use of partial assembly references is not recommended, because it can lead to a number of versioning problems:

• Versions of the assembly might not be backward compatible. For example, your code might work with version 1.6 of the assembly, but because of the partial assembly reference you might get a later version that has an incompatible change.

• Versions of the assembly might not be forward compatible. For example, your code might work with version 1.6 of the assembly, but because of the partial assembly reference you might get an earlier version that lacks necessary code.

• An application that installs a new version of an assembly can break applications that use partial assembly references to load the assembly, if the new version is not compatible.

Because the potential for versioning problems is so great, the LoadWithPartialName method is marked as obsolete in the .NET Framework version 2.0.

Making Partial Assembly References

You can make partial references to an assembly in your code one of the following ways:

• Use a method such as System.Reflection.Assembly.Load and specify only a partial reference. The runtime checks for the assembly in the application directory.

• Use the System.Reflection.Assembly.LoadWithPartialName method and specify only a partial reference. The runtime checks for the assembly in the application directory and in the global assembly cache.

  Note

  The LoadWithPartialName method is obsolete in .NET Framework version 2.0.

  Using the LoadWithPartialName method can introduce variability into the binding process. For example, if you request a bind to an assembly with a strong name but do not include the public key in your reference, you have no assurance that the assembly you bind to came from the expected publisher. Additionally, references that do not include the public key token are not subject to version policy, so the application and machine configuration files are never checked. Partial references using the LoadWithPartialName method work best in scenarios when you want to pick up the latest version of an assembly.

• Use a method such as System.Reflection.Assembly.Load and provide only a partial reference; then provide the full reference information in the application configuration file.

Partial References Using the LoadWithPartialName Method

A call to the LoadWithPartialName method must include at least the assembly's text name, but can also include the public key token, version, or culture. Because you are using a method that expects only a partial reference, you do not have to include full reference information (name, version, culture and, if applicable, the public key token).

When you partially reference an assembly using the LoadWithPartialName method, the runtime uses specific rules to locate the referenced assembly. These rules include:

1. The runtime checks the application configuration file for qualifying information for the reference in the <qualifyAssembly> element. If a valid entry is found, binding proceeds as it would for any full reference.

2. The runtime then searches the application directory for an assembly that matches the specified assembly text name. If a match is found, the runtime uses that assembly.

3. If no match is found in the application directory, the runtime checks the global assembly cache for the assembly. If the public key token, version, or culture is specified in the partial reference, the runtime attempts to match that value exactly. If no version is specified, the runtime attempts to locate the assembly with the highest version number that matches the other criteria specified. If the culture or the public key token is not specified, the runtime's behavior is undefined.

   For example, suppose the call Assembly.LoadWithPartialName("math, Version 5.0.0.0") is made and the contents of the global assembly cache are as follows:

   math,version=5.0.0.0,publicKeyToken=11111111,culture=de
   math,version=5.0.0.0,publicKeyToken=22222222,culture=en
   

   The result of the call is undefined. The runtime selects the first assembly it encounters.

   As another example, suppose the call Assembly.LoadWithPartialName("math") is made and the contents of the global assembly cache are as follows:

   math,version=5.0.0.0,publicKeyToken=11111111,culture=neutral
   math,version=6.0.0.0,publicKeyToken=22222222,culture=neutral
   

   The result of the call is a bind to the math assembly, version 6.0.0.0.

   As a final example, suppose the call Assembly.LoadWithPartialName("math,publicKeyToken=11111111") is made and the contents of the global assembly cache are as follows:

   math,version=5.0.0.0,publicKeyToken=11111111,culture=neutral
   math,version=6.0.0.0,publicKeyToken=22222222,culture=neutral
   

   The result of the call is a bind to the math assembly, version 5.0.0.0.

Partial References with Qualifying Information

You can also make a dynamic reference using a method such as System.Reflection.Assembly.Load and provide only a partial reference, but you then qualify the reference using the <qualifyAssembly> element in the application configuration file. This element allows you to provide the full reference information (name, version, culture and, if applicable, the public key token) in your application configuration file instead of in your code.

See Also

Concepts

How the Runtime Locates Assemblies

Step 1: Examining the Configuration Files

Step 2: Checking for Previously Referenced Assemblies

Step 3: Checking the Global Assembly Cache

Step 4: Locating the Assembly through Codebases or Probing