About System.Runtime.Loader.AssemblyLoadContext

The AssemblyLoadContext class was introduced in .NET Core and is not available in .NET Framework. This article supplements the AssemblyLoadContext API documentation with conceptual information.

This article is relevant to developers implementing dynamic loading, especially dynamic-loading framework developers.

What is the AssemblyLoadContext?

Every .NET 5+ and .NET Core application implicitly uses AssemblyLoadContext. It's the runtime's provider for locating and loading dependencies. Whenever a dependency is loaded, an AssemblyLoadContext instance is invoked to locate it.

• AssemblyLoadContext provides a service of locating, loading, and caching managed assemblies and other dependencies.
• To support dynamic code loading and unloading, it creates an isolated context for loading code and its dependencies in their own AssemblyLoadContext instance.

Versioning rules

A single AssemblyLoadContext instance is limited to loading exactly one version of an Assembly per simple assembly name. When an assembly reference is resolved against an AssemblyLoadContext instance that already has an assembly of that name loaded, the requested version is compared to the loaded version. The resolution will succeed only if the loaded version is equal or higher to the requested version.

When do you need multiple AssemblyLoadContext instances?

The restriction that a single AssemblyLoadContext instance can load only one version of an assembly can become a problem when loading code modules dynamically. Each module is independently compiled, and the modules may depend on different versions of an Assembly. This is often a problem when different modules depend on different versions of a commonly used library.

To support dynamically loading code, the AssemblyLoadContext API provides for loading conflicting versions of an Assembly in the same application. Each AssemblyLoadContext instance provides a unique dictionary that maps each AssemblyName.Name to a specific Assembly instance.

It also provides a convenient mechanism for grouping dependencies related to a code module for later unload.

The AssemblyLoadContext.Default instance

The AssemblyLoadContext.Default instance is automatically populated by the runtime at startup. It uses default probing to locate and find all static dependencies.

It solves the most common dependency loading scenarios.

Dynamic dependencies

AssemblyLoadContext has various events and virtual functions that can be overridden.

The AssemblyLoadContext.Default instance only supports overriding the events.

The articles Managed assembly loading algorithm, Satellite assembly loading algorithm, and Unmanaged (native) library loading algorithm refer to all the available events and virtual functions. The articles show each event and function's relative position in the loading algorithms. This article doesn't reproduce that information.

This section covers the general principles for the relevant events and functions.

• Be repeatable. A query for a specific dependency must always result in the same response. The same loaded dependency instance must be returned. This requirement is fundamental for cache consistency. For managed assemblies in particular, we're creating an Assembly cache. The cache key is a simple assembly name, AssemblyName.Name.
• Typically don't throw. It's expected that these functions return null rather than throw when unable to find the requested dependency. Throwing will prematurely end the search and propagate an exception to the caller. Throwing should be restricted to unexpected errors like a corrupted assembly or an out of memory condition.
• Avoid recursion. Be aware that these functions and handlers implement the loading rules for locating dependencies. Your implementation shouldn't call APIs that trigger recursion. Your code should typically call AssemblyLoadContext load functions that require a specific path or memory reference argument.
• Load into the correct AssemblyLoadContext. The choice of where to load dependencies is application-specific. The choice is implemented by these events and functions. When your code calls AssemblyLoadContext load-by-path functions call them on the instance where you want the code loaded. Sometime returning null and letting the AssemblyLoadContext.Default handle the load may be the simplest option.
• Be aware of thread races. Loading can be triggered by multiple threads. The AssemblyLoadContext handles thread races by atomically adding assemblies to its cache. The race loser's instance is discarded. In your implementation logic, don't add extra logic that doesn't handle multiple threads properly.

How are dynamic dependencies isolated?

Each AssemblyLoadContext instance represents a unique scope for Assembly instances and Type definitions.

There's no binary isolation between these dependencies. They're only isolated by not finding each other by name.

In each AssemblyLoadContext:

• AssemblyName.Name may refer to a different Assembly instance.
• Type.GetType may return a different type instance for the same type name.

Shared dependencies

Dependencies can easily be shared between AssemblyLoadContext instances. The general model is for one AssemblyLoadContext to load a dependency. The other shares the dependency by using a reference to the loaded assembly.

This sharing is required of the runtime assemblies. These assemblies can only be loaded into the AssemblyLoadContext.Default. The same is required for frameworks like ASP.NET, WPF, or WinForms.

It's recommended that shared dependencies be loaded into AssemblyLoadContext.Default. This sharing is the common design pattern.

Sharing is implemented in the coding of the custom AssemblyLoadContext instance. AssemblyLoadContext has various events and virtual functions that can be overridden. When any of these functions return a reference to an Assembly instance that was loaded in another AssemblyLoadContext instance, the Assembly instance is shared. The standard load algorithm defers to AssemblyLoadContext.Default for loading to simplify the common sharing pattern. For more information, see Managed assembly loading algorithm.

Type-conversion issues

When two AssemblyLoadContext instances contain type definitions with the same name, they're not the same type. They're the same type if and only if they come from the same Assembly instance.

To complicate matters, exception messages about these mismatched types can be confusing. The types are referred to in the exception messages by their simple type names. The common exception message in this case is of the form:

Object of type 'IsolatedType' cannot be converted to type 'IsolatedType'.

Debug type-conversion issues

Given a pair of mismatched types, it's important to also know:

• Each type's Type.Assembly.
• Each type's AssemblyLoadContext, which can be obtained via the AssemblyLoadContext.GetLoadContext(Assembly) function.

Given two objects a and b, evaluating the following in the debugger will be helpful:

// In debugger look at each assembly's instance, Location, and FullName
a.GetType().Assembly
b.GetType().Assembly
// In debugger look at each AssemblyLoadContext's instance and name
System.Runtime.Loader.AssemblyLoadContext.GetLoadContext(a.GetType().Assembly)
System.Runtime.Loader.AssemblyLoadContext.GetLoadContext(b.GetType().Assembly)

Resolve type-conversion issues

There are two design patterns for solving these type conversion issues.

1. Use common shared types. This shared type can either be a primitive runtime type, or it can involve creating a new shared type in a shared assembly. Often the shared type is an interface defined in an application assembly. For more information, read about how dependencies are shared.

2. Use marshalling techniques to convert from one type to another.