API: Native Library Resolve Event

[swaroop-sridhar]

This proposal adds a Native library resolving event, to be raised when the runtime cannot resolve a native library load.

Proposed API

namespace System.Runtime.Loader
{
    public abstract class AssemblyLoadContext
    {
        /// Event handler for resolving native libraries
        /// Inputs: Invoking assembly, and library name to resolve
        /// Returns: A handle to the loaded native library
        public event Func<Assembly, string, IntPtr> ResolvingUnmanagedDll;
    }
}

Rationale

In the case of Loading assemblies, the runtime provides the application to customize the load at various phases:

• Before running the default load logic via AssemblyLoadContext.Load() method overrides
• After running the default load logic via the AssemblyLoadContext.Resolving event handlers.

This proposal creates a matching facility for unmanaged libraries

• Before default DllImport logic: The existing AssemblyLoadContext.LoadUnmanagedDll() and separately proposed DllImportResolver callbacks
• After default DllImport logic: The new AssemblyLoadContext.ResolvingUnmanagedDll event.

In particular, the NativeLibraryResolve event is expected to provide flexibility for running custom native library resolution logic from plugins. Hence the motivation to have the event per AssemblyLoadContext, rather than globally.

DllImport sequence

DllImport load library works in the following order, stop at any step the library is successfully loaded.

• If the invoking-assembly has a DllImportResolver callback registered, invoke it.
• If the invoking-assembly is not in the default load context, call AssemblyLoadContext.LoadUnmanagedDll()
• Run the default load logic, try loading from:
  • AppDomain cache
  • NATIVE_DLL_SEARCH_DIRECTORIES
  • Invoking-assembly directory, System32, etc. based on DllImportSearchPaths
• Raise the ResolvingUnmanagedDll event

Discussion

Alternate notation

In this proposal ResolvingUnmanagedDll uses Func notation in order to be consistent with the
Loading/Unloading events in AssemblyLoadContext.

An alternative is to use EventHandler style recommended by these guidelines, and similar to certain other events in the same class.

namespace System
{
    public delegate IntPtr UnmanagedDllResolveEventHandler(object sender, ResolveEventArgs args);
}

namespace System.Runtime.Loader
{
    public abstract class AssemblyLoadContext
    {
        public event UnmanagedDllResolveEventHandler ResolvingUnmanagedDll;
    }
}

Related Topics

dotnet/corefx#32015 Native Library Loader API

[swaroop-sridhar]

CC: @vitek-karas @jeffschwMSFT @AaronRobinsonMSFT @jkotas

[jkotas]

ResolveEventHandler returns Assembly. This should have a different type.

[swaroop-sridhar]

Thanks @jkotas, I've fixed it now.

[jkotas]

The existing events on AssemblyLoadContext use Action/Func. Do we want to follow the same style?

[swaroop-sridhar]

In AssemblyLoadContext, the Loading/Unloading events use the Func notation, while others use EventHandler style.

I wrote in event in the EventHandler style following these guidelines.
I'm happy to write this event in the Func style, in fact, I'd prefer it for this case.

[vitek-karas]

I'm worried about naming consistency. On managed side we have Load/Resolving. On native we have LoadUnmanagedDll/NativeLibraryResolve. To be 100% consistent we should call it ResolvingUnmanagedDll.

[vitek-karas]

I think it's important to mention that there are 2 reasons to add this:

• Plugins - which don't want to register callbacks for every assembly in the plugin as that creates problems with multiple callbacks support.
• Anybody (Plugins included) - as this will be the only way (excluding callbacks) to provide custom resolution of native libraries in the Default context.

[vitek-karas]

I also think it would be a good idea to describe the proposed ordering of the various hooks. It starts with a call to a DllImport method - what are the high-level steps and where/when are the various hooks called.

[AaronRobinsonMSFT]

what are the high-level steps and where/when are the various hooks called.

Following on to @vitek-karas's comment, the official guidance for DllImport should be updated with these newdetails.

[swaroop-sridhar]

I've updated the naming, and added a section on DllImport order.

[swaroop-sridhar]

the official guidance for DllImport should be updated with these newdetails.

Sure, once the feature is checked in/released, we should update it.

[jeffschwMSFT]

Closed with dotnet/corefx#34668