Investigação padrão

A instância AssemblyLoadContext.Default é responsável por localizar as dependências de um assembly. Este artigo descreve a lógica de investigação da instância AssemblyLoadContext.Default.

Propriedades de investigação configuradas pelo host

Quando o runtime é iniciado, o host de runtime fornece um conjunto de propriedades de investigação nomeadas que configuram caminhos de investigação AssemblyLoadContext.Default.

Cada propriedade de investigação é opcional. Se presente, cada propriedade é um valor de cadeia de caracteres que contém uma lista delimitada de caminhos absolutos. O delimitador é o caractere ";" no Windows e ":" em todas as outras plataformas.

Nome da propriedade	Descrição
TRUSTED_PLATFORM_ASSEMBLIES	Lista de caminhos de arquivo de assembly para plataforma e aplicativo.
PLATFORM_RESOURCE_ROOTS	Lista de caminhos de diretório para procurar assemblies de recursos satélites.
NATIVE_DLL_SEARCH_DIRECTORIES	Lista de caminhos de diretório para pesquisar bibliotecas não gerenciadas (nativas).
APP_PATHS	Lista de caminhos de diretório para pesquisar assemblies gerenciados.

Como as propriedades são preenchidas?

Há dois cenários principais para preencher as propriedades, dependendo se o arquivo <myapp>.deps.json existe.

• Quando o arquivo *.deps.json está presente, ele é analisado para preencher as propriedades de investigação.
• Quando o arquivo *.deps.json não está presente, supõe-se que o diretório do aplicativo contenha todas as dependências. O conteúdo do diretório é usado para preencher as propriedades de investigação.

Além disso, os arquivos *.deps.json de quaisquer estruturas referenciadas são analisados da mesma forma.

A variável de ambiente DOTNET_ADDITIONAL_DEPS pode ser usada para adicionar mais dependências. dotnet.exe também contém um parâmetro opcional --additional-deps para definir esse valor na inicialização do aplicativo.

A propriedade APP_PATHS não é preenchida por padrão e é omitida para a maioria dos aplicativos.

A lista de todos os arquivos *.deps.json usados pelo aplicativo pode ser acessada por meio de System.AppContext.GetData("APP_CONTEXT_DEPS_FILES").

Como fazer para ver as propriedades de investigação por meio do código gerenciado?

Cada propriedade está disponível chamando a função AppContext.GetData(String) com o nome da propriedade listado na tabela acima.

Como fazer para depurar a construção das propriedades de investigação?

O host de runtime do .NET Core produzirá mensagens de rastreamento úteis quando determinadas variáveis de ambiente estiverem habilitadas:

Variável de ambiente	Descrição
COREHOST_TRACE=1	Habilita o rastreamento.
COREHOST_TRACEFILE=<path>	Rastreia um caminho de arquivo em vez do padrão stderr.
COREHOST_TRACE_VERBOSITY	Define o detalhamento de 1 (mais baixo) até 4 (mais alto).

Investigação padrão do assembly gerenciado

Ao investigar para localizar um assembly gerenciado, a ordem de AssemblyLoadContext.Default é a seguinte:

• Arquivos correspondentes a AssemblyName.Name em TRUSTED_PLATFORM_ASSEMBLIES (após remover extensões de arquivo).
• Arquivos do assembly em APP_PATHS com extensões de arquivo comuns.

Investigação de assembly (recurso) satélite

Para encontrar um assembly satélite de uma cultura específica, construa um conjunto de caminhos de arquivo.

Para cada caminho em PLATFORM_RESOURCE_ROOTS e depois em APP_PATHS, acrescente a cadeia de caracteres CultureInfo.Name, um separador de diretório, a cadeia de caracteres AssemblyName.Name e a extensão ".dll".

Se houver algum arquivo correspondente, tente carregá-lo e devolvê-lo.

Investigação de biblioteca não gerenciada (nativa)

O algoritmo de investigação de biblioteca não gerenciada do runtime é idêntico em todas as plataformas. No entanto, como a carga real da biblioteca não gerenciada é executada pela plataforma subjacente, o comportamento observado pode ser ligeiramente diferente.

1. Verifique se o nome da biblioteca fornecida representa um caminho absoluto ou relativo.

2. Se o nome representar um caminho absoluto, use o nome diretamente para todas as operações subsequentes. Caso contrário, use o nome e crie combinações definidas pela plataforma para serem consideradas. As combinações consistem em prefixos (por exemplo, lib) e/ou sufixos (por exemplo, .dll, .dylib e .so) específicos da plataforma. Essa não é uma lista completa e não representa os esforços exatos feitos em cada plataforma. É apenas um exemplo do que é considerado. Para obter mais informações, consulte o carregamento da biblioteca nativa.

3. O nome (e, se o caminho for relativo, cada combinação) será usado nas etapas a seguir. A primeira tentativa de carregamento bem-sucedida retorna imediatamente o identificador para a biblioteca carregada.

   • Acrescente-o a cada caminho fornecido na propriedade NATIVE_DLL_SEARCH_DIRECTORIES e tente carregar.

   • Se DefaultDllImportSearchPathsAttribute não estiver definido no assembly de chamada ou p/invoke ou estiver definido e incluir DllImportSearchPath.AssemblyDirectory, acrescente o nome ou a combinação ao diretório do assembly de chamada e tente carregar.

   • Use-o diretamente para carregar a biblioteca.

4. Indique que a biblioteca falhou ao carregar.