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.
Higher-level APIs may abstract the low-level API.
The .NET Core resource fallback process involves the following steps:
activeinstance loads a satellite assembly for the requested culture in the following priority order:
Check its cache.
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,
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.
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.
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.
For the InvariantCulture, we don't return to steps 2 & 3, but rather continue with step 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.
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.