The Assembly Manifest

The assembly manifest serves two purposes:

• It describes the assembly to the managed hosting environment.

• It acts as a directory to the modules, types, and resources in the assembly.

Assemblies are thus self-describing. A consumer can discover all of an assembly’s data, types, and functions—without needing additional files.

Here’s a summary of the functionally significant data stored in the manifest:

• The simple name of the assembly

• A version number (AssemblyVersion)

• A public key and signed hash of the assembly, if strongly named

• A list of referenced assemblies, including their version and public key

• A list of types defined in the assembly

• The culture it targets, if a satellite assembly (AssemblyCulture)

The manifest can also store the following informational data:

• A full title and description (AssemblyTitle and AssemblyDescription)

• Company and copyright information (AssemblyCompany and Assembly​Copyright)

• A display version (AssemblyInformationalVersion)

• Additional attributes for custom data

Some of this data is derived from arguments given to the compiler, such as the list of referenced assemblies or the public key with which to sign the assembly. The rest comes from assembly attributes, indicated in parentheses.

using System.Runtime.CompilerServices;

[assembly:InternalsVisibleTo("MyUnitTestProject")]

The Application Manifest (Windows)

An application manifest is an XML file that communicates information about the assembly to the OS. An application manifest is embedded into the startup executable as a Win32 resource during the build process. If present, the manifest is read and processed before the CLR loads the assembly—and can influence how Windows launches the application’s process.

A .NET application manifest has a root element called assembly in the XML namespace urn:schemas-microsoft-com:asm.v1:

<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
  <!-- contents of manifest -->
</assembly>

The following manifest instructs the OS to request administrative elevation:

<?xml version="1.0" encoding="utf-8"?>
<assembly manifestVersion="1.0" xmlns="urn:schemas-microsoft-com:asm.v1">
  <trustInfo xmlns="urn:schemas-microsoft-com:asm.v2">
    <security>
      <requestedPrivileges>
        <requestedExecutionLevel level="requireAdministrator" />
      </requestedPrivileges>
    </security>
  </trustInfo>
</assembly>

We describe the consequences of requesting administrative elevation in Chapter 21.

UWP applications have a far more elaborate manifest, described in the Package.appxmanifest file. This includes a declaration of the program’s capabilities, which determine permissions granted by the OS. The easiest way to edit this file is with Visual Studio, which displays a dialog when you double-click the manifest file.

Modules

The contents of an assembly are actually packaged within an intermediate container, called a module. A module corresponds to a file containing the contents of an assembly. The reason for this extra layer of containership is to allow an assembly to span multiple files, a feature present in .NET Framework but absent in .NET Core. Figure 18-1 illustrates the relationship.

Figure 18-1. Single-file assembly

Although .NET Core does not support multifile assemblies, at times you need to be aware of the extra level of containership that modules impose. The main scenario is with reflection (see “Reflecting Assemblies” and “Emitting Assemblies and Types” in Chapter 19).

The Assembly Class

The Assembly class in System.Reflection is a gateway to accessing assembly metadata at runtime. There are a number of ways to obtain an assembly object: the simplest is via a Type’s Assembly property:

Assembly a = typeof (Program).Assembly;

You can also obtain an Assembly object by calling one of Assembly’s static methods:

GetExecutingAssembly

Returns the assembly of the type that defines the currently executing function

GetCallingAssembly

Does the same as GetExecutingAssembly but for the function that called the currently executing function

GetEntryAssembly

Returns the assembly defining the application’s original entry method

After you have an Assembly object, you can use its properties and methods to query the assembly’s metadata and reflect upon its types. Table 18-1 shows a summary of these functions.

How to Strongly Name an Assembly

To give an assembly a strong name, first generate a public/private key pair with the sn.exe utility:

sn.exe -k MyKeyPair.snk

This manufactures a new key pair and stores it to a file called MyKeyPair.snk. If you subsequently lose this file, you will permanently lose the ability to recompile your assembly with the same identity.

You can sign an assembly with this file by updating your project file. From Visual Studio, go to the Project Properties window, and then, on the Signing tab, select the “Sign the assembly” checkbox and select your .snk file.

The same key pair can sign multiple assemblies—they’ll still have distinct identities if their simple names differ.

Fully Qualified Names

A fully qualified assembly name is a string that includes all four identifying components, in this format:

simple-name, Version=version, Culture=culture, PublicKeyToken=public-key

For example, the fully qualified name of System.Private.CoreLib.dll is System.Private.CoreLib, Version=4.0.0.0, Culture=neutral, PublicKeyToken=7cec85d7bea7798e.

If the assembly has no AssemblyVersion attribute, the version appears as 0.0.0.0. If it is unsigned, its public key token appears as null.

An Assembly object’s FullName property returns its fully qualified name. The compiler always uses fully qualified names when recording assembly references in the manifest.

The AssemblyName Class

AssemblyName is a class with a typed property for each of the four components of a fully qualified assembly name. AssemblyName has two purposes:

• It parses or builds a fully qualified assembly name.

• It stores some extra data to assist in resolving (finding) the assembly.

You can obtain an AssemblyName object in any of the following ways:

• Instantiate an AssemblyName, providing a fully qualified name

• Call GetName on an existing Assembly

• Call AssemblyName.GetAssemblyName, providing the path to an assembly file on disk

You can also instantiate an AssemblyName object without any arguments and then set each of its properties to build a fully qualified name. An AssemblyName is mutable when constructed in this manner.

Here are its essential properties and methods:

string      FullName    { get; }            // Fully qualified name
string      Name        { get; set; }       // Simple name
Version     Version     { get; set; }       // Assembly version
CultureInfo CultureInfo { get; set; }       // For satellite assemblies
string      CodeBase    { get; set; }       // Location

byte[]      GetPublicKey();                 // 160 bytes
void        SetPublicKey (byte[] key);
byte[]      GetPublicKeyToken();            // 8-byte version
void        SetPublicKeyToken (byte[] publicKeyToken);

Version is itself a strongly typed representation, with properties for Major, Minor, Build, and Revision numbers. GetPublicKey returns the full cryptographic public key; GetPublicKeyToken returns the last eight bytes used in establishing identity.

To use AssemblyName to obtain the simple name of an assembly:

Console.WriteLine (typeof (string).Assembly.GetName().Name);
// System.Private.CoreLib

To get an assembly version:

string v = myAssembly.GetName().Version.ToString();

We examine the CodeBase property in “Loading, Resolving, and Isolating Assemblies”.

Assembly Informational and File Versions

Two further assembly attributes are available for expressing version-related information. Unlike AssemblyVersion, the following two attributes do not affect an assembly’s identity and so have no effect on what happens at compile-time or at runtime:

AssemblyInformationalVersion

The version as displayed to the end user. This is visible in the Windows File Properties dialog box as Product Version. Any string can go here, such as “5.1 Beta 2.” Typically, all of the assemblies in an application would be assigned the same informational version number.

AssemblyFileVersion

This is intended to refer to the build number for that assembly. This is visible in the Windows File Properties dialog box as File Version. As with Assembly​Version, it must contain a string consisting of up to four numbers separated by periods.

How to Sign with Authenticode

signtool sign /n "Joseph Albahari" /fd sha256 LINQPad.exe

 ... /d LINQPad /du http://www.linqpad.net

 ... /tr http://timestamp.comodoca.com/authenticode /td SHA256

Directly Embedding Resources

To directly embed a resource using Visual Studio:

• Add the file to your project.

• Set its build action to Embedded Resource.

Visual Studio always prefixes resource names with the project’s default namespace, plus the names of any subfolders in which the file is contained. So, if your project’s default namespace was Westwind.Reports and your file was called banner.jpg in the folder pictures, the resource name would be Westwind.Reports.pictures.banner.jpg.

To retrieve a resource, you call GetManifestResourceStream on the assembly containing the resource. This returns a stream, which you can then read as any other:

Assembly a = Assembly.GetEntryAssembly();

using (Stream s = a.GetManifestResourceStream ("TestProject.data.xml"))
using (XmlReader r = XmlReader.Create (s))
  ...

System.Drawing.Image image;
using (Stream s = a.GetManifestResourceStream ("TestProject.banner.jpg"))
  image = System.Drawing.Image.FromStream (s);

The stream returned is seekable, so you can also do this:

byte[] data;
using (Stream s = a.GetManifestResourceStream ("TestProject.banner.jpg"))
  data = new BinaryReader (s).ReadBytes ((int) s.Length);

If you’ve used Visual Studio to embed the resource, you must remember to include the namespace-based prefix. To help avoid error, you can specify the prefix in a separate argument, using a type. The type’s namespace is used as the prefix:

using (Stream s = a.GetManifestResourceStream (typeof (X), "data.xml"))

X can be any type with the desired namespace of your resource (typically, a type in the same project folder).

GetManifestResourceNames returns the names of all resources in the assembly.

.resources Files

.resources files are containers for potentially localizable content. A .resources file ends up as an embedded resource within an assembly—just like any other kind of file. The difference is that you must do the following:

• Package your content into the .resources file to begin with

• Access its content through a ResourceManager or pack URI rather than a Get​ManifestResourceStream

.resources files are structured in binary and so are not human-editable; therefore, you must rely on tools provided by the Framework and Visual Studio to work with them. The standard approach with strings or simple data types is to use the .resx format, which can be converted to a .resources file either by Visual Studio or the resgen tool. The .resx format is also suitable for images intended for a Windows Forms or ASP.NET application.

In a WPF application, you must use Visual Studio’s “Resource” build action for images or similar content needing to be referenced by URI. This applies whether localization is needed or not.

We describe how to do each of these in the following sections.

.resx Files

A .resx file is a design-time format for producing .resources files. A .resx file uses XML and is structured with name/value pairs as follows:

<root>
  <data name="Greeting">
    <value>hello</value>
  </data>
  <data name="DefaultFontSize" type="System.Int32, mscorlib">
    <value>10</value>
  </data>
</root>

To create a .resx file in Visual Studio, add a project item of type Resources File. The rest of the work is done automatically:

• The correct header is created.

• A designer is provided for adding strings, images, files, and other kinds of data.

• The .resx file is automatically converted to the .resources format and embedded into the assembly upon compilation.

• A class is written to help you access the data later on.

ResourceManager r = new ResourceManager ("welcome",
                                         Assembly.GetExecutingAssembly());

string greeting = r.GetString ("Greeting");
int fontSize = (int) r.GetObject ("DefaultFontSize");
Image image = (Image) r.GetObject ("flag.png");

ResourceManager r = new ResourceManager (...);
ResourceSet set = r.GetResourceSet (CultureInfo.CurrentUICulture,
                                    true, true);
foreach (System.Collections.DictionaryEntry entry in set)
  Console.WriteLine (entry.Key);

<Button>
  <Image Height="50" Source="flag.png"/>
</Button>

<Button>
  <Image Height="50" Source="UtilsAssembly;Component/flag.png"/>
</Button>

Uri u = new Uri ("flag.png", UriKind.Relative);
using (Stream s = Application.GetResourceStream (u).Stream)

Uri u = new Uri ("pack://application:,,,/flag.png");

Assembly a = Assembly.GetExecutingAssembly();
ResourceManager r = new ResourceManager (a.GetName().Name + ".g", a);
using (Stream s = r.GetStream ("flag.png"))
  ...

Satellite Assemblies

Data embedded in .resources is localizable.

Resource localization is relevant when your application runs on a version of Windows built to display everything in a different language. For consistency, your application should use that same language, too.

A typical setup is as follows:

• The main assembly contains .resources for the default or fallback language.

• Separate satellite assemblies contain localized .resources translated to different languages.

When your application runs, .NET Core examines the language of the current OS (from CultureInfo.CurrentUICulture). Whenever you request a resource using ResourceManager, the Framework looks for a localized satellite assembly. If one’s available—and it contains the resource key you requested—it’s used in place of the main assembly’s version.

This means that you can enhance language support simply by adding new satellites—without changing the main assembly.

Satellite assemblies are deployed in subdirectories of the assembly’s folder as follows:

programBaseFolderMyProgram.exe
                 MyLibrary.exe
                 XXMyProgram.resources.dll
                 XXMyLibrary.resources.dll

XX refers to the two-letter language code (such as “de” for German) or a language and region code (such as “en-GB” for English in Great Britain). This naming system allows the CLR to find and load the correct satellite assembly automatically.

<root>
  ...
  <data name="Greeting"
    <value>hello</value>
  </data>
</root>

ResourceManager r = new ResourceManager ("welcome",
                                         Assembly.GetExecutingAssembly());
Console.Write (r.GetString ("Greeting"));

<root>
  <data name="Greeting">
    <value>hallo<value>
  </data>
</root>

System.Threading.Thread.CurrentThread.CurrentUICulture
  = new System.Globalization.CultureInfo ("de");

Cultures and Subcultures

Cultures are split into cultures and subcultures. A culture represents a particular language; a subculture represents a regional variation of that language. The Framework follows the RFC1766 standard, which represents cultures and subcultures with two-letter codes. Here are the codes for English and German cultures:

En
de

Here are the codes for the Australian English and Austrian German subcultures:

en-AU
de-AT

A culture is represented in .NET with the System.Globalization.CultureInfo class. You can examine the current culture of your application as follows:

Console.WriteLine (System.Threading.Thread.CurrentThread.CurrentCulture);
Console.WriteLine (System.Threading.Thread.CurrentThread.CurrentUICulture);

Running this on a computer localized for Australia illustrates the difference between the two:

en-AU
en-US

CurrentCulture reflects the regional settings of the Windows Control Panel, whereas CurrentUICulture reflects the language of the OS.

Regional settings include such things as time zone and the formatting of currency and dates. CurrentCulture determines the default behavior of such functions as DateTime.Parse. Regional settings can be customized to the point where they no longer resemble any particular culture.

CurrentUICulture determines the language in which the computer communicates with the user. Australia doesn’t need a separate version of English for this purpose, so it just uses the US one. If I spent a couple of months working in Austria, I would go to the Control Panel and change my CurrentCulture to Austrian-German. However, given that I can’t speak German, my CurrentUICulture would remain US English.

ResourceManager, by default, uses the current thread’s CurrentUICulture property to determine the correct satellite assembly to load. ResourceManager uses a fallback mechanism when loading resources. If a subculture assembly is defined, that one is used; otherwise, it falls back to the generic culture. If the generic culture is not present, it falls back to the default culture in the main assembly.

Assembly Load Contexts

As we just discussed, the AssemblyLoadContext class is responsible for loading and resolving assemblies as well as providing a mechanism for isolation.

Every .NET Assembly object belongs to exactly one AssemblyLoadContext. You can obtain the ALC for an assembly as follows:

Assembly assem = Assembly.GetExecutingAssembly();
AssemblyLoadContext context = AssemblyLoadContext.GetLoadContext (assem);
Console.WriteLine (context.Name);

Conversely, you can think of an ALC as containing or owning assemblies, which you can obtain via its Assemblies property. Following on from the previous example:

foreach (Assembly a in context.Assemblies)
  Console.WriteLine (a.FullName);

The AssemblyLoadContext class also has a static All property that enumerates all ALCs.

You can create a new ALC just by instantiating AssemblyLoadContext and providing a name (the name is helpful when debugging), although more commonly, you’d first subclass AssemblyLoadContext so that you can implement logic to resolve dependencies; in other words, load an assembly from its name.

public Assembly LoadFromAssemblyPath (string assemblyPath);
public Assembly LoadFromStream (Stream assembly, Stream assemblySymbols);

var alc = new AssemblyLoadContext ("Test");
Assembly assem = alc.LoadFromAssemblyPath (@"c:	empfoo.dll");

var alc2 = new AssemblyLoadContext ("Test 2");
Assembly assem2 = alc2.LoadFromAssemblyPath (@"c:	empfoo.dll");

bytes[] bytes = File.ReadAllBytes (@"c:	empfoo.dll");
var ms = new MemoryStream (bytes);
var assem = alc.LoadFromStream (ms);

public Assembly LoadFromAssemblyName (AssemblyName assemblyName);

using System.IO;
using System.Runtime.Loader;

class FolderBasedALC : AssemblyLoadContext
{
  readonly string _folder;
  public FolderBasedALC (string folder) => _folder = folder;

  protected override Assembly Load (AssemblyName assemblyName)
  {
    // Attempt to find the assembly:
    string targetPath = Path.Combine (_folder, assemblyName.Name + ".dll");

    if (File.Exists (targetPath))
      return LoadFromAssemblyPath (targetPath);   // Load the assembly

    return null;    // We can't find it – it could be a framework assembly
  }
}

var alc = new FolderBasedALC (@"c:	emp");
Assembly foo = alc.LoadFromAssemblyPath (@"c:	empfoo.dll");
...

var alc = new FolderBasedALC (@"c:	emp");
Assembly foo = alc.LoadFromAssemblyName (new AssemblyName ("foo"));
...

var alc = new AssemblyLoadContext ("test");
alc.Resolving += (loadContext, assemblyName) =>
{
  string targetPath = Path.Combine (@"c:	emp", assemblyName.Name + ".dll");
  return alc.LoadFromAssemblyPath (targetPath);   // Load the assembly
};
Assembly foo = alc.LoadFromAssemblyName (new AssemblyName ("foo"));

The Default ALC

When an application starts, the CLR assigns a special ALC to the static AssemblyLoadContext.Default property. The default ALC is where your startup assembly loads, along with its statically referenced dependencies and the .NET Core Framework assemblies.

The default ALC looks first in the default probing paths to automatically resolve assemblies (see “Default probing”); this normally equates to the locations indicated in the application’s .deps.json and .runtimeconfig.json files.

If the ALC cannot find an assembly in its default probing paths, its Resolving event fires. Handling this event lets you load the assembly from other locations, which means that you can deploy an application’s dependencies to additional locations, such as subfolders, shared folders, or even as a binary resource inside the host assembly:

AssemblyLoadContext.Default.Resolving += (loadContext, assemblyName) =>
{
  // Try to locate assemblyName, returning an Assembly object or null.
  // Typically you'd call LoadFromAssemblyPath after finding the file.
  // ...
};

The Resolving event in the default ALC also fires when a custom ALC fails to resolve (in other words, when its Load method returns null), and the default ALC is unable to resolve the assembly.

You can also load assemblies into the default ALC from outside the Resolving event. Before proceeding, however, you should first determine whether you can solve the problem better by using a separate ALC or with the approaches we describe in the following section (which use the executing and contextual ALCs). Hardcoding to the default ALC makes your code brittle because it cannot as a whole be isolated (for instance, by unit testing frameworks, or by LINQPad).

If you still want to proceed, it’s preferable to call a resolution method (i.e., LoadFrom​AssemblyName) rather than a loading method (such as LoadFromAssemblyPath)—especially if your assembly is statically referenced. This is because it’s possible that the assembly might already be loaded, in which case LoadFromAssemblyName will return the already-loaded assembly, whereas LoadFromAssemblyPath will throw an exception.

(With LoadFromAssemblyPath, you can also run the risk of loading the assembly from a place that’s inconsistent with where the ALC’s default resolution mechanism would find it.)

If the assembly is in a place where the ALC won’t automatically find it, you can still follow this procedure and additionally handle the ALC’s Resolving event.

Note that when calling LoadFromAssemblyName, you don’t need to provide the full name; the simple name will do (and is valid even if the assembly is strongly named):

AssemblyLoadContext.Default.LoadFromAssemblyName ("System.Xml");

However, if you include the public key token in the name, it must match with what’s loaded.

The Current ALC

In the preceding section, we cautioned against explicitly loading assemblies into the default ALC. What you usually want, instead, is to load/resolve into the current ALC.

In most cases, the current ALC is the one containing the currently executing assembly:

var executingAssem = Assembly.GetExecutingAssembly();
var alc = AssemblyLoadContext.GetLoadContext (executingAssem);

Assembly assem = alc.LoadFromAssemblyName (...);  // to resolve by name
        // OR: = alc.LoadFromAssemblyPath (...);  // to load by path

Here’s a more flexible and explicit way to obtain the ALC:

var myAssem = typeof (SomeTypeInMyAssembly).Assembly;
var alc = AssemblyLoadContext.GetLoadContext (myAssem);
...

Sometimes, it’s impossible to infer the current ALC. For example, suppose that you were responsible for writing the .NET Core binary serializer that we covered in Chapter 17. A serializer such as this writes the full names of the types that it serializes (including their assembly names), which must be resolved during deserialization. The question is, which ALC should you use? The problem with relying on the executing assembly is that it will return whatever assembly contains the deserializer, not the assembly that’s calling the deserializer.

The best solution is not to guess, but to ask:

public object Deserialize (Stream stream, AssemblyLoadContext alc)
{
  ...
}

Being explicit maximizes flexibility and minimizes the chance of making mistakes. The caller can now decide what should count as the “current” ALC:

var assem = typeof (SomeTypeThatIWillBeDeserializing).Assembly;
var alc = AssemblyLoadContext.GetLoadContext (assem);
var object = Deserialize (someStream, alc);

Assembly.Load and Contextual ALCs

To help with the common case of loading an assembly into the currently executing ALC; that is:

var executingAssem = Assembly.GetExecutingAssembly();
var alc = AssemblyLoadContext.GetLoadContext (executingAssem);
Assembly assem = alc.LoadFromAssemblyName (...);

Microsoft has defined the following method in the Assembly class:

public static Assembly Load (string assemblyString);

as well as a functionally identical version that accepts an AssemblyName object:

public static Assembly Load (AssemblyName assemblyRef);

(Don’t confuse these methods with the legacy Load(byte[]) method, which behaves in a totally different manner—see “The Legacy Loading Methods”.)

As with LoadFromAssemblyName, you have a choice of specifying the assembly’s simple, partial, or full name:

Assembly a = Assembly.Load ("System.Private.Xml");

This loads the System.Private.Xml assembly into whatever ALC the executing code’s assembly is loaded in.

In this case, we specified a simple name. The following strings would also be valid, and all would have the same result in .NET Core 3:

"System.Private.Xml, PublicKeyToken=cc7b13ffcd2ddd51"
"System.Private.Xml, Version=4.0.1.0"
"System.Private.Xml, Version=4.0.1.0, PublicKeyToken=cc7b13ffcd2ddd51"

If you choose to specify a public key token, it must match with what’s loaded.

Both of these methods are strictly for resolution, so you cannot specify a file path. (If you populate the CodeBase property in the AssemblyName object, it will be ignored.)

Assembly a = typeof (System.Xml.Formatting).Assembly;

Assembly a = System.Xml.Formatting.Indented.GetType().Assembly;

If you were to write the Assembly.Load method yourself, it would (almost) look like this:

[MethodImpl(MethodImplOptions.NoInlining)]
Assembly Load (string name)
{
  Assembly callingAssembly = Assembly.GetCallingAssembly();
  var callingAlc = AssemblyLoadContext.GetLoadContext (callingAssembly);
  return callingAlc.LoadFromAssemblyName (new AssemblyName (name));
}

Method1();

var myALC = new AssemblyLoadContext ("test");
using (myALC.EnterContextualReflection())
{
   Console.WriteLine (
     AssemblyLoadContext.CurrentContextualReflectionContext.Name);  // test

   Method2();
}

// Once disposed, EnterContextualReflection() no longer has an effect.
Method3();

void Method1() => Assembly.Load ("...");    // Will use calling ALC
void Method2() => Assembly.Load ("...");    // Will use myALC
void Method3() => Assembly.Load ("...");    // Will use calling ALC

[MethodImpl(MethodImplOptions.NoInlining)]
Assembly Load (string name)
{
  var alc = AssemblyLoadContext.CurrentContextualReflectionContext
     ?? AssemblyLoadContext.GetLoadContext (Assembly.GetCallingAssembly());

  return alc.LoadFromAssemblyName (new AssemblyName (name));
}

Loading and Resolving Unmanaged Libraries

ALCs can also load and resolve native libraries. Native resolution is triggered when you call an external method that’s marked with the [DllImport] attribute:

[DllImport ("SomeNativeLibrary.dll")]
static extern int SomeNativeMethod (string text);

Because we didn’t specify a full path in the [DllImport] attribute, calling Some​NativeMethod triggers a resolution in whatever ALC contains the assembly in which SomeNativeMethod is defined.

The virtual resolving method in the ALC is called LoadUnmanagedDll, and the loading method is called LoadUnmanagedDllFromPath:

protected override IntPtr LoadUnmanagedDll (string unmanagedDllName)
{
  // Locate the full path of unmanagedDllName...
  string fullPath = ...
  return LoadUnmanagedDllFromPath (fullPath);    // Load the DLL
}

If you’re unable to locate the file, you can return IntPtr.Zero. The CLR will then fire the ALC’s ResolvingUnmanagedDll event.

Interestingly, the LoadUnmanagedDllFromPath method is protected, so you won’t usually be able to call it from a ResolvingUnmanagedDll event handler. However, you can achieve the same result by calling the static NativeLibrary.Load:

someALC.ResolvingUnmanagedDll += (requestingAssembly, unmanagedDllName) =>
{
  return NativeLibrary.Load ("(full path to unmanaged DLL)");
};

Although native libraries are typically resolved and loaded by ALCs, they don’t “belong” to an ALC. After it’s loaded, a native library stands on its own and takes responsibility for resolving any transitive dependencies that it might have. Furthermore, native libraries are global to the process, so it’s not possible to load two different versions of a native library, if they have the same filename.

AssemblyDependencyResolver

In “Default probing”, we said that the default ALC reads the .deps.json and .runtimeconfig.json files, if present, in determining where to look to resolve platform-specific and development-time NuGet dependencies.

If you want to load an assembly into a custom ALC that has platform-specific or NuGet dependencies, you’ll need to somehow reproduce this logic. You could accomplish this by parsing the configuration files and carefully following the rules on platform-specific monikers, but doing so is not only difficult, but the code that you write will break if the rules change in a later version of .NET Core.

The AssemblyDependencyResolver class solves this problem. To use it, you instantiate it with the path of the assembly whose dependencies you want to probe:

var resolver = new AssemblyDependencyResolver (@"c:	empfoo.dll");

Then, to find the path of a dependency, you call the ResolveAssemblyToPath method:

string path = resolver.ResolveAssemblyToPath (new AssemblyName ("bar"));

In the absence of a .deps.json file (or if the .deps.json doesn’t contain anything relevant to bar.dll), this will evaluate to c: empar.dll.

You can similarly resolve unmanaged dependencies by calling Resolve​UnmanagedDllToPath.

A great way to illustrate a more complex scenario is to create a new Console project called ClientApp and then add a NuGet reference to Microsoft.Data.SqlClient. Add the following class:

using Microsoft.Data.SqlClient;

namespace ClientApp
{
  public class Program
  {
    public static SqlConnection GetConnection() => new SqlConnection();
    static void Main() => GetConnection();   // Test that it resolves
  }
}

Now build the application and look in the output folder: you’ll see a file called Microsoft.Data.SqlClient.dll. However, this file never loads when run, and attempting to explicitly load it throws an exception. The assembly that actually loads is located in the runtimeswin (or runtimes/unix) subfolder; the default ALC knows to load it because it parses the ClientApp.deps.json file.

If you were to try to load the ClientApp.dll assembly from another application, you’d need to write an ALC that can resolve its dependency, Microsoft.Data.SqlClient.dll. In doing so, it would be insufficient to merely look in the folder where ClientApp.dll is located (as we did in “Resolving assemblies”). Instead, you’d need to use AssemblyDependencyResolver to determine where that file is located for the platform in use:

string path = @"C:sourceClientAppinDebug
etcoreapp3.0ClientApp.dll";
var resolver = new AssemblyDependencyResolver (path);
var sqlClient = new AssemblyName ("Microsoft.Data.SqlClient");
Console.WriteLine (resolver.ResolveAssemblyToPath (sqlClient));

On a Windows machine, this outputs the following:

C:sourceClientAppinDebug
etcoreapp3.0
untimeswinlib
etcoreapp2
Microsoft.Data.SqlClient.dll

We give a complete example in “Writing a Plug-In System”.

Unloading ALCs

In simple cases, it’s possible to unload a nondefault AssemblyLoadContext, freeing memory and releasing file locks on the assemblies it loaded. For this to work, the ALC must have been instantiated with the isCollectible parameter true:

var alc = new AssemblyLoadContext ("test", isCollectible:true);

You can then call the Unload method on the ALC to initiate the unload process.

The unload model is cooperative rather than preemptive. If any methods in any of the ALC’s assemblies are executing, the unload will be deferred until those methods finish.

The actual unload takes place during garbage collection; it will not take place if anything from outside the ALC has any (nonweak) reference to anything inside the ALC (including objects, types, and assemblies). It’s not uncommon for APIs (including those in the .NET Core Framework) to cache objects in static fields or dictionaries—or subscribe to events—and this makes it easy to create references that will prevent an unload, especially if code in the ALC uses APIs outside its ALC in a nontrivial way. Determining the cause of a failed unload is difficult and requires the use of tools such as WinDbg.

The Legacy Loading Methods

If you’re still using .NET Framework (or writing a library that targets .NET Standard, and want to support .NET Framework) you won’t be able to use the AssemblyLoadContext class. Loading is accomplished instead by using the following methods:

public static Assembly LoadFrom (string assemblyFile);
public static Assembly LoadFile (string path);
public static Assembly Load (byte[] rawAssembly);

LoadFile and Load(byte[]) provide isolation, whereas LoadFrom does not.

Resolution is accomplished by handling the application domain’s AssemblyResolve event, which works like the default ALC’s Resolving event.

The Assembly.Load(string) method is also available to trigger resolution and works in a similar way.

AppDomain.CurrentDomain.AssemblyResolve += (sender, args) =>
{
  string fullAssemblyName = args.Name;
  // return an Assembly object or null
  ...
};

AssemblyLoadContext.All.SelectMany (a => a.Assemblies)

Writing a Plug-In System

To fully demonstrate the concepts that we’ve covered in this section, let’s write a plug-in system that uses unloadable ALCs to isolate each plug-in.

Our demo system will initially comprise three .NET Core projects:

Plugin.Common (library)

Defines an interface that plug-ins will implement

Capitalizer (library)

A plug-in that capitalizes text

Plugin.Host (Console application)

Locates and invokes plug-ins

Let’s assume that the projects reside in the following directories:

c:sourcePluginDemoPlugin.Common
c:sourcePluginDemoCapitalizer
c:sourcePluginDemoPlugin.Host

All projects will reference the Plugin.Common library, and there will be no other interproject references.

namespace Plugin.Common
{
  public interface ITextPlugin
  {
    string TransformText (string input);
  }
}

public class CapitalizerPlugin : Plugin.Common.ITextPlugin
{
  public string TransformText (string input) => input.ToUpper();
}

Capitalizer.dll      // Our plug-in assembly
Plugin.Common.dll    // Referenced assembly

class PluginLoadContext : AssemblyLoadContext
{
  AssemblyDependencyResolver _resolver;

  public PluginLoadContext (string pluginPath, bool collectible)
    // Give it a friendly name to help with debugging:
    : base (name: Path.GetFileName (pluginPath), collectible)
  {
    // Create a resolver to help us find dependencies.
    _resolver = new AssemblyDependencyResolver (pluginPath);
  }

  protected override Assembly Load (AssemblyName assemblyName)
  {
    // See below
    if (assemblyName.Name == typeof (ITextPlugin).Assembly.GetName().Name)
      return null;

    string target = _resolver.ResolveAssemblyToPath (assemblyName);

    if (target != null)
      return LoadFromAssemblyPath (target);

    // Could be a framework assembly. Allow the default context to resolve.
    return null;
  }

  protected override IntPtr LoadUnmanagedDll (string unmanagedDllName)
  {
    string path = _resolver.ResolveUnmanagedDllToPath (unmanagedDllName);

    return path == null
      ? IntPtr.Zero
      : LoadUnmanagedDllFromPath (path);
  }
}

    if (assemblyName.Name == typeof (ITextPlugin).Assembly.GetName().Name)
      return null;

class Program
{
  const bool UseCollectibleContexts = true;

  static void Main()
  {
    const string captializer = @"C:sourcePluginDemo"
      + @"CapitalizerinDebug
etcoreapp3.0Capitalizer.dll";

    Console.WriteLine (TransformText ("big apple", captializer));
  }

  static string TransformText (string text, string pluginPath)
  {
    var alc = new PluginLoadContext (pluginPath, UseCollectibleContexts);
    try
    {
      Assembly assem = alc.LoadFromAssemblyPath (pluginPath);

      // Locate the type in the assembly that implements ITextPlugin:
      Type pluginType = assem.ExportedTypes.Single (t =>
                        typeof (ITextPlugin).IsAssignableFrom (t));

      // Instantiate the ITextPlugin implementation:
      var plugin = (ITextPlugin)Activator.CreateInstance (pluginType);

      // Call the TransformText method:
      return plugin.TransformText (text);
    }
    finally
    {
      if (UseCollectibleContexts) alc.Unload();    // unload the ALC
    }
  }
}

BIG APPLE

  <ItemGroup>
    <PackageReference Include="Humanizer.Core" Version="2.6.2" />
  </ItemGroup>

using Humanizer;
namespace Capitalizer
{
  public class CapitalizerPlugin : Plugin.Common.ITextPlugin
  {
    public string TransformText (string input) => input.Pascalize();
  }
}

BigApple

  <ItemGroup>
    <PackageReference Include="Humanizer.Core" Version="2.7.9" />
  </ItemGroup>

using Humanizer;
namespace Pluralizer
{
  public class PluralizerPlugin : Plugin.Common.ITextPlugin
  {
    public string TransformText (string input) => input.Pluralize();
  }
}

  static void Main()
  {
    const string captializer = @"C:sourcePluginDemo"
      + @"CapitalizerinDebug
etcoreapp3.0Capitalizer.dll";

    Console.WriteLine (TransformText ("big apple", captializer));

    const string pluralizer = @"C:sourcePluginDemo"
      + @"PluralizerinDebug
etcoreapp3.0Pluralizer.dll";

    Console.WriteLine (TransformText ("big apple", pluralizer));
  }

BigApple
big apples

foreach (var context in AssemblyLoadContext.All)
{
  Console.WriteLine ($"Context: {context.GetType().Name} {context.Name}");

  foreach (var assembly in context.Assemblies)
      Console.WriteLine ($"  Assembly: {assembly.FullName}");
}

Context: PluginLoadContext Capitalizer.dll
  Assembly: Capitalizer, Version=1.0.0.0, Culture=neutral, PublicKeyToken=...
  Assembly: Humanizer, Version=2.6.0.0, Culture=neutral, PublicKeyToken=...
Context: PluginLoadContext Pluralizer.dll
  Assembly: Pluralizer, Version=1.0.0.0, Culture=neutral, PublicKeyToken=...
  Assembly: Humanizer, Version=2.7.0.0, Culture=neutral, PublicKeyToken=...
Context: DefaultAssemblyLoadContext Default
  Assembly: System.Private.CoreLib, Version=4.0.0.0, Culture=neutral,...
  Assembly: Host, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null
  ...