Share via

Partial Assembly References

  • Article

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:

NoteNote

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.

Partial References Using the LoadWithPartialName Method

NoteNote

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

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.

NoteNote

This type of partial reference should not be used with assemblies that are shared among several applications. Because configuration settings are applied per application and not per assembly, a shared assembly using this type of partial reference would require each application using the shared assembly to have the qualifying information in its configuration file.

See Also

Concepts

How the Runtime Locates Assemblies
Deployment Scenarios for .NET Framework Applications
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