AssemblyLoadContext Class

Definition

Represents the runtime's concept of a scope for assembly loading.

public ref class AssemblyLoadContext
public ref class AssemblyLoadContext abstract
public class AssemblyLoadContext
public abstract class AssemblyLoadContext
type AssemblyLoadContext = class
Public Class AssemblyLoadContext
Public MustInherit Class AssemblyLoadContext
Inheritance
AssemblyLoadContext

Remarks

The AssemblyLoadContext represents a load context. Conceptually, a load context creates a scope for loading, resolving, and potentially unloading a set of assemblies.

The AssemblyLoadContext exists primarily to provide assembly loading isolation. It allows multiple versions of the same assembly to be loaded within a single process. It replaces the isolation mechanisms provided by multiple AppDomain instances in .NET Framework.

Note

Usage in the runtime

The runtime implements two assembly load contexts:

Application usage

An application can create its own AssemblyLoadContext to create a custom solution for advanced scenarios. The customization focuses on defining dependency resolution mechanisms.

The AssemblyLoadContext provides two extension points to implement managed assembly resolution:

  1. The AssemblyLoadContext.Load(AssemblyName) method provides the first chance for the AssemblyLoadContext to resolve, load, and return the assembly. If the AssemblyLoadContext.Load(AssemblyName) method returns null, the loader tries to load the assembly into the AssemblyLoadContext.Default.
  2. If the AssemblyLoadContext.Default is unable to resolve the assembly, the original AssemblyLoadContext gets a second chance to resolve the assembly. The runtime raises the Resolving event.

Additionally, the AssemblyLoadContext.LoadUnmanagedDll(String) virtual method allows customization of the default unmanaged assembly resolution. The default implementation returns null, which causes the runtime search to use its default search policy. The default search policy is sufficient for most scenarios.

Technical challenges

  • It is not possible to load multiple versions of the runtime in a single process.

    Caution

    Loading multiple copies or different versions of framework assemblies can lead to unexpected and hard-to-diagnose behavior.

    Tip

    Use process boundaries with remoting or interprocess communication to solve this isolation problem.

  • The timing of assembly loading can make testing and debugging difficult. Assemblies are typically loaded without their dependencies immediately being resolved. The dependencies are loaded as they are needed:

    • When code branches into a dependent assembly.
    • When code loads resources.
    • When code explicitly loads assemblies.
  • The implementation of AssemblyLoadContext.Load(AssemblyName) can add new dependencies that may need to be isolated to allow different versions to exist. The most natural implementation would place these dependencies in the default context. Careful design can isolate the new dependencies.

  • The same assembly is loaded multiple times into different contexts.

    • This can lead to confusing error messages, for example "Unable to cast object of type 'Sample.Plugin' to type 'Sample.Plugin'".
    • Marshaling across isolation boundaries is non-trivial. A typical solution is to use an interface defined in an assembly that's only loaded into the default load context.

Constructors

AssemblyLoadContext()

Initializes a new instance of the AssemblyLoadContext class.

AssemblyLoadContext(Boolean)

Initializes a new instance of the AssemblyLoadContext class with a value that indicates whether unloading is enabled.

AssemblyLoadContext(String, Boolean)

Initializes a new instance of the AssemblyLoadContext class with a name and a value that indicates whether unloading is enabled.

Properties

All

Returns a collection of all AssemblyLoadContext instances.

Assemblies

Returns a collection of the Assembly instances loaded in the AssemblyLoadContext.

CurrentContextualReflectionContext

Gets the AssemblyLoadContext set by the most recent call to EnterContextualReflection().

Default

Gets the default AssemblyLoadContext. The default context contains the main application assembly and its static dependencies.

IsCollectible

Gets a value that indicates whether this AssemblyLoadContext is collectible.

Name

Get the name of the AssemblyLoadContext.

Methods

EnterContextualReflection()

Sets CurrentContextualReflectionContext to thisAssemblyLoadContext.

EnterContextualReflection(Assembly)

Sets CurrentContextualReflectionContext to the AssemblyLoadContext which loaded the assembly.

Equals(Object)

Determines whether the specified object is equal to the current object.

(Inherited from Object)
Finalize()

Allows the object to try to free resources and perform other cleanup operations before it's reclaimed by garbage collection.

GetAssemblyName(String)

Gets an AssemblyName for an assembly path.

GetHashCode()

Serves as the default hash function.

(Inherited from Object)
GetLoadContext(Assembly)

Gets the AssemblyLoadContext containing the specified Assembly.

GetType()

Gets the Type of the current instance.

(Inherited from Object)
Load(AssemblyName)

When overridden in a derived class, allows an assembly to be resolved based on its AssemblyName.

LoadFromAssemblyName(AssemblyName)

Resolves and loads an assembly given its AssemblyName.

LoadFromAssemblyPath(String)

Loads the contents of an assembly file on the specified path.

LoadFromNativeImagePath(String, String)

Loads the contents of the native image of a managed assembly file on the specified path.

LoadFromStream(Stream)

Loads the assembly with a common object file format (COFF)-based image containing a managed assembly.

LoadFromStream(Stream, Stream)

Loads the assembly with a common object file format (COFF)-based image containing a managed assembly, optionally including symbols for the assembly.

LoadUnmanagedDll(String)

Allows derived class to load an unmanaged library by name.

LoadUnmanagedDllFromPath(String)

Loads an unmanaged library from the specified path.

MemberwiseClone()

Creates a shallow copy of the current Object.

(Inherited from Object)
SetProfileOptimizationRoot(String)

Sets the root path where the optimization profiles for this load context are stored.

StartProfileOptimization(String)

Starts the profile optimization for the specified profile.

ToString()

Returns the string representation of this load context.

ToString()

Returns a string that represents the current object.

(Inherited from Object)
Unload()

Initiates an unload of this AssemblyLoadContext.

Events

Resolving

Occurs when the resolution of an assembly fails when attempting to load into this assembly load context.

ResolvingUnmanagedDll

Occurs when the resolution of a native library fails.

Unloading

Occurs when the AssemblyLoadContext is unloaded.

Applies to

See also