Managed assembly loading algorithm

Managed assemblies are located and loaded with an algorithm that has various stages.

All managed assemblies except satellite assemblies and WinRT assemblies use the same algorithm.

When are managed assemblies loaded?

The most common mechanism to trigger a managed assembly load is a static assembly reference. These references are inserted by the compiler whenever code uses a type defined in another assembly. These assemblies are loaded (load-by-name) as needed by the runtime. The exact timing of when the static assembly references are loaded is unspecified. It can vary between runtime versions and is influenced by optimizations like inlining.

The direct use of the following APIs will also trigger loads:

API	Description	Active AssemblyLoadContext
AssemblyLoadContext.LoadFromAssemblyName	Load-by-name	The this instance.
AssemblyLoadContext.LoadFromAssemblyPath AssemblyLoadContext.LoadFromNativeImagePath	Load from path.	The this instance.
AssemblyLoadContext.LoadFromStream	Load from object.	The this instance.
Assembly.LoadFile	Load from path in a new AssemblyLoadContext instance	The new AssemblyLoadContext instance.
Assembly.LoadFrom	Load from path in the AssemblyLoadContext.Default instance. Adds an AppDomain.AssemblyResolve handler. The handler will load the assembly's dependencies from its directory.	The AssemblyLoadContext.Default instance.
Assembly.Load(AssemblyName) Assembly.Load(String) Assembly.LoadWithPartialName	Load-by-name.	Inferred from caller. Prefer AssemblyLoadContext methods.
Assembly.Load(Byte[]) Assembly.Load(Byte[], Byte[])	Load from object in a new AssemblyLoadContext instance.	The new AssemblyLoadContext instance.
Type.GetType(String) Type.GetType(String, Boolean) Type.GetType(String, Boolean, Boolean)	Load-by-name.	Inferred from caller. Prefer Type.GetType methods with an assemblyResolver argument.
Assembly.GetType	If type name describes an assembly qualified generic type, trigger a Load-by-name.	Inferred from caller. Prefer Type.GetType when using assembly qualified type names.
Activator.CreateInstance(String, String) Activator.CreateInstance(String, String, Object[]) Activator.CreateInstance(String, String, Boolean, BindingFlags, Binder, Object[], CultureInfo, Object[])	Load-by-name.	Inferred from caller. Prefer Activator.CreateInstance methods taking a Type argument.

Important

Unlike .NET Framework, the assemblyFile parameter of Assembly.LoadFrom is treated as a file path in .NET, not a URI. In .NET Framework, you can pass a file URI (for example, file:///C:/path/to/assembly.dll)—such as one constructed from Assembly.CodeBase—and the assembly loads successfully. In .NET, the assemblyFile value is passed to Path.GetFullPath, which doesn't properly handle URIs, so the load fails. If you already have a file URI string, first create a Uri instance and use its LocalPath property to get the file path before calling Assembly.LoadFrom. To get the file path of an already-loaded assembly, use Assembly.Location instead of CodeBase.

Algorithm

The following algorithm describes how the runtime loads a managed assembly.

1. Determine the active AssemblyLoadContext.

   • For a static assembly reference, the active AssemblyLoadContext is the instance that loaded the referring assembly.
   • Preferred APIs make the active AssemblyLoadContext explicit.
   • Other APIs infer the active AssemblyLoadContext. For these APIs, the AssemblyLoadContext.CurrentContextualReflectionContext property is used. If its value is null, then the inferred AssemblyLoadContext instance is used.
   • See the table in the When are managed assemblies loaded? section.

2. For the Load-by-name methods, the active AssemblyLoadContext loads the assembly in the following priority order:

   • Check its cache-by-name.
   • Call the AssemblyLoadContext.Load function.
   • Check the AssemblyLoadContext.Default instance's cache and run managed assembly default probing logic. If an assembly is newly loaded, a reference is added to the AssemblyLoadContext.Default instance's cache-by-name.
   • Raise the AssemblyLoadContext.Resolving event for the active AssemblyLoadContext.
   • Raise the AppDomain.AssemblyResolve event.

3. For the other types of loads, the active AssemblyLoadContext loads the assembly in the following priority order:

   • Check its cache-by-name.
   • If the active AssemblyLoadContext is AssemblyLoadContext.Default, run the default probing logic for managed assemblies.
   • Load from the specified path or raw assembly object. If an assembly is newly loaded, a reference is added to the active AssemblyLoadContext instance's cache-by-name.

4. In either case, if an assembly is newly loaded, then the AppDomain.AssemblyLoad event is raised.