Satellite assembly loading algorithm

Satellite assemblies are used to store localized resources customized for language and culture.

Satellite assemblies use a different loading algorithm than general managed assemblies.

When are satellite assemblies loaded?

Satellite assemblies are loaded when loading a localized resource.

The basic API to load localized resources is the System.Resources.ResourceManager class. Ultimately the ResourceManager class will call the GetSatelliteAssembly method for each CultureInfo.Name.

Higher-level APIs may abstract the low-level API.

Algorithm

The .NET Core resource fallback process involves the following steps:

1. Determine the active AssemblyLoadContext instance. In all cases, the active instance is the executing assembly's AssemblyLoadContext.

2. The active instance loads a satellite assembly for the requested culture in the following priority order:

   • Check its cache.

   • If active is the AssemblyLoadContext.Default instance, run the default satellite (resource) assembly probing logic.

   • Call the AssemblyLoadContext.Load function.

   • If the managed assembly corresponding to the satellite assembly was loaded from a file, check the directory of the managed assembly for a subdirectory that matches the requested CultureInfo.Name (for example, es-MX).

     Note

     On Linux and macOS, the subdirectory is case-sensitive and must either:

     • Exactly match case.
     • Be in lower case.

   • Raise the AssemblyLoadContext.Resolving event.

   • Raise the AppDomain.AssemblyResolve event.

3. If a satellite assembly is loaded:

   • The AppDomain.AssemblyLoad event is raised.
   • The assembly is searched for the requested resource. If the runtime finds the resource in the assembly, it uses it. If it doesn't find the resource, it continues the search.

   Note

   To find a resource within the satellite assembly, the runtime searches for the resource file requested by the ResourceManager for the current CultureInfo.Name. Within the resource file, it searches for the requested resource name. If either is not found, the resource is treated as not found.

4. The ResourceManager next searches the parent culture assemblies through many potential levels, each time repeating steps 2 & 3.

   Each culture has only one parent, which is defined by the CultureInfo.Parent property.

   The search for parent cultures stops when a culture's Parent property is CultureInfo.InvariantCulture.

   For the InvariantCulture, we don't return to steps 2 & 3, but rather continue with step 5.

5. If the resource is still not found, the ResourceManager uses the resource for the default (fallback) culture.

   Typically, the resources for the default culture are included in the main application assembly. However, you can specify UltimateResourceFallbackLocation.Satellite for the NeutralResourcesLanguageAttribute.Location property. This value indicates that the ultimate fallback location for resources is a satellite assembly rather than the main assembly.

   Note

   The default culture is the ultimate fallback. Therefore, we recommend that you always include an exhaustive set of resources in the default resource file. This helps prevent exceptions from being thrown. By having an exhaustive set, you provide a fallback for all resources and ensure that at least one resource is always present for the user, even if it is not culturally specific.

6. Finally,

   • If the runtime doesn't find a resource file for a default (fallback) culture, a MissingManifestResourceException or MissingSatelliteAssemblyException exception is thrown.
   • If the resource file is found but the requested resource isn't present, the request returns null.