dotnet/runtime

MetadataLoadContext assembly binding behavior is documented incorrectly

Open

#113353 opened on Mar 11, 2025

View on GitHub
 (2 comments) (0 reactions) (0 assignees)C# (17,886 stars) (5,445 forks)batch import
area-System.Reflectiondocumentationhelp wanted

Description

When MetadataLoadContext is resolving an assembly and its MetadataAssemblyResolver returns null, it throws an exception with this message: https://github.com/dotnet/runtime/blob/a49ed697037bad503e32daa23f4339ebfb8962ea/src/libraries/System.Reflection.MetadataLoadContext/src/Resources/Strings.resx#L181 The message suggests that 'pre-loading' the assembly with LoadFromAssemblyPath will populate the MetadataLoadContext's assembly binding cache.

The API documentation for the LoadFrom methods also suggests this is the case:

MetadataLoadContext.LoadFromAssemblyPath Loads an assembly from a specific path on the disk and binds its assembly name to it in the MetadataLoadContext.

But these methods do not do this: https://github.com/dotnet/runtime/blob/a49ed697037bad503e32daa23f4339ebfb8962ea/src/libraries/System.Reflection.MetadataLoadContext/src/System/Reflection/MetadataLoadContext.Loading.cs#L47-L49

It looks like this behavior was changed, but the documentation and exception message was not updated: https://github.com/dotnet/runtime/commit/2ef74f6be9ac1a70902facdc4047c49682e75005#diff-7a38392b94b0c17ee62172e5b642b77f0b3a1bb8d79a6488d24f1729345c46fbL49

Contributor guide

Tech stack
csharp
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
1
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
under 1 hour
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
basic understanding of MetadataLoadContext
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
90
Research direction
The issue identifies that the exception message in Strings.resx (line 181) and the API documentation for LoadFromAssemblyPath incorrectly suggest that pre loading an assembly populates a binding cache. The actual behavior is shown in MetadataLoadContext.Loading.cs lines 47-49. The change in commit 2ef74f6be9ac1a70902facdc4047c49682e75005 removed that caching behavior. The fix involves updating the exception message in Strings.resx and the documentation comments for LoadFrom methods to reflect that they do not cache bindings.