Algorithme de chargement d’assembly satellite

Les assemblys satellites sont utilisés pour stocker des ressources localisées personnalisées pour la langue et la culture.

Les assemblys satellites utilisent un algorithme de chargement différent de celui des assemblys managés généraux.

Quand les assemblys satellites sont-ils chargés ?

Les assemblys satellites sont chargés lors du chargement d’une ressource localisée.

L’API de base pour charger les ressources localisées est la classe System.Resources.ResourceManager. En fin de compte, la classe ResourceManager appelle la méthode GetSatelliteAssembly pour chaque CultureInfo.Name.

Les API de niveau supérieur peuvent faire abstraction de l’API de bas niveau.

Algorithm

Le processus de secours pour les ressources .NET Core comprend les étapes suivantes :

1. Déterminez l’instance AssemblyLoadContext active. Dans tous les cas, l’instance active est le AssemblyLoadContext de l’assembly en cours d’exécution.

2. L’instance active charge un assembly satellite pour la culture demandée dans l’ordre de priorité suivant :

   • Vérifiez son cache.

   • Si active est l’instance AssemblyLoadContext.Default, exécutez la logique de sondage d’assembly satellite (ressource) par défaut.

   • Appelez la fonction AssemblyLoadContext.Load.

   • Si l’assembly managé correspondant à l’assembly satellite a été chargé à partir d’un fichier, recherchez dans le répertoire de l’assembly managé un sous-répertoire qui correspond à l’assembly CultureInfo.Name demandé (par exemple, es-MX).

     Remarque

     Sur Linux et macOS, le sous-répertoire respecte la casse et doit :

     • correspondre exactement à la casse ;
     • être en minuscules.

   • Déclenchez l'événement AssemblyLoadContext.Resolving.

   • Déclenchez l'événement AppDomain.AssemblyResolve.

3. Si un assembly satellite est chargé :

   • L'événement AppDomain.AssemblyLoad est déclenché.
   • L’assembly est recherché pour la ressource demandée. Si le runtime trouve la ressource dans l’assembly, il l’utilise. S’il ne trouve pas la ressource, il continue la recherche.

   Notes

   Pour trouver une ressource dans l’assembly satellite, le runtime recherche le fichier de ressources demandé par ResourceManager pour CultureInfo.Name. Dans le fichier de ressources, il cherche le nom de la ressource demandée. En cas d’échec, la ressource est traitée comme introuvable.

4. Le ResourceManager parcourt ensuite les assemblys de culture parente à différents niveaux potentiels, en répétant à chaque fois les étapes 2 et 3.

   Chaque culture a un seul parent, qui est défini par la propriété CultureInfo.Parent.

   La recherche des cultures parentes s’arrête quand la propriété Parent d’une culture est CultureInfo.InvariantCulture.

   Pour InvariantCulture, nous ne revenons pas aux étapes 2 et 3, mais passons plutôt à l’étape 5.

5. Si la ressource est toujours introuvable, ResourceManager utilise la ressource de la culture par défaut (de secours).

   En règle générale, les ressources de la culture par défaut sont incluses dans l’assembly d’application principal. Toutefois, vous pouvez spécifier UltimateResourceFallbackLocation.Satellite pour la propriété NeutralResourcesLanguageAttribute.Location. Cette valeur indique que l’emplacement de secours ultime pour les ressources est un assembly satellite plutôt que l’assembly principal.

   Notes

   La culture par défaut constitue l’ultime recours. Par conséquent, nous vous recommandons de toujours inclure un ensemble exhaustif de ressources dans le fichier de ressources par défaut. Vous empêchez ainsi la levée d’exceptions. En disposant d’un ensemble exhaustif, vous fournissez une solution de secours pour toutes les ressources et garantissez qu’au moins une ressource est toujours présente pour l’utilisateur, même si elle n’est pas propre à une culture.

6. Enfin,

   • Si le runtime ne trouve pas de fichier de ressources pour une culture (de secours) par défaut, une exception MissingManifestResourceException ou MissingSatelliteAssemblyException est levée.
   • Si le fichier de ressources est trouvé, mais que la ressource demandée n’est pas présente, la demande retourne null.