Algorithme de chargement d’assembly satellite

Les assemblies satellites sont utilisés pour stocker des ressources localisées adaptées à 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 assemblages satellites sont-ils chargés ?

Les assemblies satellites sont chargées 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.

Algorithme

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

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

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

   • Vérifiez son cache.

   • Si est l’instance , exécutez la logique de recherche de l’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 soit :

     • 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é.
   • Pour la ressource demandée, l'assemblage est fouillé. Si le runtime trouve la ressource dans l’assembly, il l’utilise. S’il ne trouve pas la ressource, il continue la recherche.

   Remarque

   Pour trouver une ressource dans l’assembly satellite, l'environnement d'exécution recherche le fichier de ressources demandé par ResourceManager pour le contexte actuel 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 assemblies de culture parente à travers de nombreux 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 assemblage satellite plutôt que l'assemblage principal.

   Remarque

   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. Cela aide à empêcher 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 l'environnement d'exécution 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.