Information
The topic you requested is included in another documentation set. For convenience, it's displayed below. Choose Switch to see the topic in its original location.

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. When you specify a partial assembly reference, the runtime looks for the assembly only in the application directory.

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.

    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.

Note   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

How the Runtime Locates Assemblies | Deployment Scenarios | 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

Was this page helpful?
(1500 characters remaining)
Thank you for your feedback
Show:
© 2014 Microsoft