Algoritmo de carregamento de assembly satélite

Os assemblies satélites são usados para armazenar recursos localizados personalizados para idioma e cultura.

Os assemblies satélites usam um algoritmo de carregamento diferente dos assemblies gerenciados em geral.

Quando os assemblies satélites são carregados?

Os assemblies satélites são carregados quando um recurso localizado é carregado.

A API básica para carregar recursos localizados é a classe System.Resources.ResourceManager. Em última análise, a classe ResourceManager chamará o método GetSatelliteAssembly para cada CultureInfo.Name.

APIs de nível superior podem abstrair a API de nível inferior.

Algoritmo

O processo de fallback de recurso do .NET CORE envolve as seguintes etapas:

1. Determine a instância active AssemblyLoadContext. Em todos os casos, a instância de active é o AssemblyLoadContext do assembly em execução.

2. A instância active carrega um assembly satélite para a cultura solicitada na seguinte ordem de prioridade:

   • Verifique o seu cache.

   • Se active for a instância AssemblyLoadContext.Default, execute a lógica de investigação de assembly satélite (recurso) padrão.

   • Chame a função AssemblyLoadContext.Load.

   • Se o assembly gerenciado correspondente ao assembly satélite tiver sido carregado de um arquivo, verifique o diretório do assembly gerenciado para obter um subdiretório que corresponda ao CultureInfo.Name solicitado (por exemplo, es-MX).

     Observação

     No Linux e no macOS, o subdiretório diferencia maiúsculas de minúsculas e precisa:

     • Fazer a correspondência exata de maiúsculas e minúsculas.
     • Estar em letras minúsculas.

   • Aciona o evento AssemblyLoadContext.Resolving.

   • Aciona o evento AppDomain.AssemblyResolve.

3. Se um assembly satélite for carregado:

   • O evento AppDomain.AssemblyLoad será gerado.
   • O assembly é procurado pelo recurso solicitado. Se o runtime encontrar o recurso no assembly, ele o usará. Se não encontrar o recurso, ele continua a pesquisa.

   Observação

   Para localizar um recurso dentro do assembly satélite, o runtime procura o arquivo de recurso solicitado pelo ResourceManager para o CultureInfo.Name atual. No arquivo de recurso, ele pesquisa o nome do recurso solicitado. Se nenhum for encontrado, o recurso será tratado como não encontrado.

4. Em seguida, ResourceManager pesquisa os assemblies de cultura pai em muitos níveis potenciais, cada vez repetindo as etapas 2 e 3.

   Cada cultura tem apenas um pai, que é definido pela propriedade CultureInfo.Parent.

   A procura de culturas pai é interrompida quando a propriedade Parent de uma cultura é CultureInfo.InvariantCulture.

   Para InvariantCulture, não retornamos às etapas 2 e 3, mas continuamos para a etapa 5.

5. Se o recurso ainda não for encontrado, o recurso ResourceManager será usado para a cultura padrão (fallback).

   Normalmente, os recursos para a cultura padrão são incluídos no assembly do aplicativo principal. No entanto, você pode especificar UltimateResourceFallbackLocation.Satellite para a propriedade NeutralResourcesLanguageAttribute.Location. Esse valor indica que o local de fallback final dos recursos é um assembly satélite em vez do assembly principal.

   Observação

   A cultura padrão é o fallback final. Portanto, recomendamos que você sempre inclua um conjunto finito de recursos no arquivo de recurso padrão. Isso ajuda a evitar que exceções sejam lançadas. Com a inclusão de um arquivo de recurso padrão você fornece um fallback para todos os recursos e garante que pelo menos um recurso esteja sempre presente para o usuário, mesmo que ele não seja específico de nenhuma cultura.

6. Enfim,

   • Se o runtime não encontrar um arquivo de recurso para uma cultura padrão (fallback), uma exceção MissingManifestResourceException ou MissingSatelliteAssemblyException será gerada.
   • Se o arquivo de recurso for encontrado, mas o recurso solicitado não estiver presente, a solicitação retornará null.