[API Proposal]: Support non-locking assembly loading with preserved Assembly.Location

[cdmazom]

Background and motivation

We’re running into an issue with assembly loading in the Unity Editor, and we ended up customizing our fork of the runtime to solve it. Since we've seen other users hit similar roadblocks, we wanted to see if an upstream solution makes sense.

When we load an assembly from a path via AssemblyLoadContext.LoadFromAssemblyPath, the runtime maps the file into memory. On Windows, particularly, this creates an OS-level lock. This interferes with standard Unity Editor workflows as it prevents us (or our users) from performing common operations on those files while the editor is running, like recompiling the assembly, renaming the file, moving it, or deleting it.

The obvious workaround is to read the file into a stream and load it from memory instead. However, this breaks third-party libraries that rely on Assembly.Location (e.g., to find adjacent assets or native dependencies), because loading from a stream leaves the location empty.

Previous Discussions and Related Issues

This is a long-standing challenge within the ecosystem, with several issues highlighting the same friction around file locks and metadata preservation:

• Issue #31958 - Add support for loading application assemblies in memory: Directly discusses adding an "eager loading" mode to AssemblyLoadContext that reads files into memory and releases the file locks on disk immediately.
• Issue #12822 - Add AssemblyLoadContext.LoadFromStream overload to populate Location and CodeBase: Highlights the community demand for avoiding file locks via streams, while pointing out that without a populated Location property, libraries break.
• Discussion #124797 - How to not locking an assembly file while it's loaded, while assembly directory is considered as a dllimport search path on Linux: A recent discussion showing that the Godot Engine ecosystem faces this exact issue. Because Godot loads assemblies from memory to avoid locking files, the resulting empty Assembly.Location causes plugins like Steamworks.NET to fail when resolving native dependencies (libsteam_api.so).

API Proposal

We propose adding a static callback to AssemblyLoadContext that allows an application to override the value returned by Assembly.Location. To ensure predictability, this callback should only be settable once for the whole application.

namespace System.Runtime.Loader
{
    public partial class AssemblyLoadContext
    {
        /// <summary>
        /// Sets a global callback to override the value returned by Assembly.Location.
        /// This method can only be called once per application.
        /// </summary>
        /// <param name="locationOverride">
        /// A function that takes the Assembly and its original location (if any), 
        /// and returns the overriding location string.
        /// </param>
        public static void SetAssemblyLocationOverride(Func<Assembly, string, string> locationOverride);
    }
}

API Usage

// 1. Set the callback once during application startup
AssemblyLoadContext.SetAssemblyLocationOverride((assembly, originalLocation) =>
{
    // Consult a custom mapping dictionary (or ALC context) to find the fake location
    if (CustomLoader.TryGetMappedPath(assembly, out string mappedPath))
    {
        return mappedPath;
    }
    
    return originalLocation;
});

// 2. Load the assembly from memory to avoid file locks
var alc = new AssemblyLoadContext("ExampleContext");
var assembly = alc.LoadFromStream(exampleLibStream);

// 3. Register the mapping so the callback returns the expected physical path
CustomLoader.RegisterMapping(assembly, "third-party-lib/example_lib.dll");

// Third-party code can now successfully resolve assembly location
var location = Path.GetDirectoryName(assembly.Location);

Alternative Designs

• Virtual method on ALC: We also considered allowing AssemblyLoadContext to override it internally via a protected virtual method, e.g., protected internal virtual string ResolveAssemblyLocation(Assembly assembly, string originalLocation). This would scope the override to specific contexts rather than relying on a global static hook and wouldn't work for the default ALC.
• Dedicated In-Memory Load Method: LoadFromAssemblyPathWithoutLocking(string assemblyPath). This was our original proposal. We discarded it as discussed in this thread to keep the runtime out of the business of managing file-locking trade-offs.

Risks

• Global State Conflicts: Because the callback is a static, set-once delegate, there is a risk of conflict if multiple independent frameworks or complex hosting scenarios within the same process attempt to claim it.

Changelog

• Updated: Replaced the LoadFromAssemblyPathWithoutLocking API proposal with a static callback (SetAssemblyLocationOverride) to override assembly resolution, based on feedback regarding runtime responsibilities.

[jkotas]

Reading the content of the file into memory is just one of the possible strategies used to deal with the file locking problem. Alternative includes copying or linking the file to some other path and loading it from there to allow original location to be mutated. (This technique was called "shadow copy" in .NET Framework - https://learn.microsoft.com/en-us/dotnet/framework/app-domains/shadow-copy-assemblies.) Each of these options come with different tradeoffs. It would be best for the runtime to stay away from choosing the tradeoff.

The runtime does not need to be in the business of enforcing that the value returned by the Location property makes sense. I think the simplest and most flexible way to address your issue is to allow location property to be set to an arbitrary path after the assembly is loaded - introduce an API like static void AssemblyLoadContext.SetAssemblyLocation(Assembly assembly, string location).

We allow similar arbitrary overriding of AppDomain.BaseDirectory and Assembly.GetEntryAssembly with similar reasoning.

[cdmazom]

I think the simplest and most flexible way to address your issue is to allow location property to be set to an arbitrary path after the assembly is loaded - introduce an API like static void AssemblyLoadContext.SetAssemblyLocation(Assembly assembly, string location).

I agree on the simplicity and flexibility, I'm very open to this direction. But would you expect any restrictions or guards on that API? (e.g. making it "set-once" or potentially a protected method?)

Part of the motivation of my initial proposal was to limit the scope of the assignment to the load phase to ensure immutability at the API level. Is that window between the load and the setter call something we should be concerned about?

[jkotas]

How about a static callback that cannot be set more than once for the whole app: static void AssemblyLoadContext.SetAssemblyLocationOverride(Func<Assembly, string, string> locationOverride);? Assembly.Location would call this callback to allow overriding the returned value.

Assembly.Location is not compatible with single file and native AOT (it returns empty string there). Modern .NET libraries should not be depending on Assembly.Location in the first place. I think about the proposed API as a compat quirk to allow the existing libraries that depends on Assembly.Location to work with custom assembly loaders. It is best effort that is not trying to be 100% reliable. For example, the 3rd party library can lock other the files in the original Assembly.Location path and you are back to square one.

[dotnet-policy-service]

Tagging subscribers to this area: @agocke, @elinor-fung
See info in area-owners.md if you want to be subscribed.

[cdmazom]

Wondering if it'd make more sense to allow the AssemblyLoadContext to override it...

public partial class AssemblyLoadContext
{
    protected internal virtual string ResolveAssemblyLocation(Assembly, string originalLocation)
    {
        return originalLocation;
    }
}

[jkotas]

It would not work for the default assembly load context.

[cdmazom]

The static callback seems to be working properly for us, I've updated the proposal.