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 consiste nas seguintes etapas:

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

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

   • Verifique o seu cache.

   • Se active é a instância AssemblyLoadContext.Default, execute a lógica de investigação do 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 é sensível a maiúsculas e minúsculas e deve ser:

     • Fazer a correspondência exata de maiúsculas e minúsculas.
     • Seja 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 foi acionado.
   • A montagem é procurada na busca pelo recurso solicitado. Se o tempo de execução encontrar o recurso na assemblagem, 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 ascendentes é 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 ResourceManager usará o recurso para a cultura padrão (substituta).

   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 definitivo de fallback para os recursos é um assembly satélite, em vez do assembly principal.

   Observação

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

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.