Partilhar via

Como o tempo de execução localiza assemblies

Observação

Este artigo é específico do .NET Framework. Ele não se aplica a implementações mais recentes do .NET, incluindo o .NET 6 e versões posteriores.

Para implantar com êxito seu aplicativo .NET Framework, você deve entender como o common language runtime localiza e se liga aos assemblies que compõem seu aplicativo. Por padrão, o tempo de execução tenta se vincular à versão exata de um conjunto com o qual o aplicativo foi compilado. Esse comportamento padrão pode ser substituído pelas definições do arquivo de configuração.

O common language runtime executa várias etapas ao tentar localizar um assembly e resolver uma referência de assembly. Cada etapa é explicada nas seções a seguir. O termo sondagem é frequentemente usado ao descrever como o runtime localiza assemblies; refere-se ao conjunto de heurísticas usado para localizar assemblies com base no seu nome e cultura.

Observação

Você pode exibir informações de vinculação no arquivo de log usando o Assembly Binding Log Viewer (Fuslogvw.exe), que está incluído no SDK do Windows.

Iniciando a ligação

O processo de localização e vinculação a um assembly começa quando o tempo de execução tenta resolver uma referência a outro assembly. Esta referência pode ser estática ou dinâmica. O compilador regista referências estáticas nos metadados do manifeste do assembly no momento da compilação. Referências dinâmicas são construídas em tempo real como resultado da chamada de vários métodos, como Assembly.Load.

A maneira preferida de fazer referência a um assembly é usar uma referência completa, incluindo o nome do assembly, versão, cultura e token de chave pública (se existir). O runtime utiliza estas informações para localizar o assembly, seguindo os passos descritos adiante nesta seção. O tempo de execução usa o mesmo processo de resolução, independentemente de a referência ser para um assembly estático ou dinâmico.

Você também pode fazer uma referência dinâmica a um assembly fornecendo ao método de chamada apenas informações parciais sobre o assembly, como especificar apenas o nome do assembly. Nesse caso, apenas o diretório do aplicativo é pesquisado para o assembly e nenhuma outra verificação ocorre. Você faz uma referência parcial usando qualquer um dos vários métodos para carregar assemblies, como Assembly.Load ou AppDomain.Load.

Finalmente, você pode fazer uma referência dinâmica usando um método como Assembly.Load e fornecer apenas informações parciais, em seguida, qualificar a referência usando o <elemento qualifyAssembly> no arquivo de configuração do aplicativo. Esse elemento permite que você forneça as informações de referência completas (nome, versão, cultura e, se aplicável, o token de chave pública) no arquivo de configuração do aplicativo em vez de no código. Você usaria essa técnica se quisesse qualificar totalmente uma referência a um assembly fora do diretório do aplicativo ou se quisesse fazer referência a um assembly no cache de assembly global, mas quisesse a conveniência de especificar a referência completa no arquivo de configuração em vez de no código.

Observação

Esse tipo de referência parcial não deve ser usado com conjuntos que são partilhados entre várias aplicações. Como as definições de configuração são aplicadas por aplicativo e não por assembly, um assembly compartilhado usando esse tipo de referência parcial exigiria que cada aplicativo usando o assembly compartilhado tivesse as informações de qualificação em seu arquivo de configuração.

O tempo de execução usa as seguintes etapas para resolver uma referência de assemblagem:

  1. Determina a versão correta do assembly examinando os arquivos de configuração aplicáveis, incluindo o arquivo de configuração do aplicativo, o arquivo de política do editor e o arquivo de configuração da máquina. Se o ficheiro de configuração estiver localizado numa máquina remota, o tempo de execução deverá localizar e baixar o ficheiro de configuração da aplicação primeiro.

  2. Verifica se o nome do assembly foi vinculado antes e, em caso afirmativo, usa o assembly carregado anteriormente. Se uma solicitação anterior para carregar o assembly falhar, a solicitação é imediatamente rejeitada sem que se tente carregar o assembly.

    Observação

    O caché de falhas na associação de assembly é uma novidade no .NET Framework versão 2.0.

  3. Verifica o cache global de assemblies. Se o assembly for encontrado lá, o tempo de execução usará esse assembly.

  4. Sondas para a montagem usando as seguintes etapas:

    1. Se a configuração e a política do editor não afetarem a referência original e se a solicitação de associação tiver sido criada usando o método Assembly.LoadFrom, o tempo de execução verificará as dicas de localização.

    2. Se uma base de código for encontrada nos arquivos de configuração, o tempo de execução verificará apenas esse local. Se esse teste falhar, o tempo de execução determinará que a solicitação de associação falhou e nenhuma outra sondagem ocorre.

    3. Sondas para a montagem usando a heurística descrita na seção de sondagem. Se o assembly não for encontrado após a sondagem, o runtime solicitará ao Windows Installer que forneça o assembly. Isso funciona como um recurso de instalação sob demanda.

      Observação

      Não há verificação de versão para assemblies sem nomes fortes, nem ocorre uma verificação no cache global de assembly para assemblies sem nomes fortes.

Etapa 1: Examinando os arquivos de configuração

O comportamento de vinculação de assembly pode ser configurado em diferentes níveis com base em três arquivos XML:

  • Arquivo de configuração do aplicativo.

  • Arquivo de política do editor.

  • Arquivo de configuração da máquina.

Esses arquivos seguem a mesma sintaxe e fornecem informações como redirecionamentos de ligação, o local do código e modos de ligação para assemblies específicos. Cada arquivo de configuração pode conter um <elemento assemblyBinding> que redireciona o processo de vinculação. Os elementos filho do <elemento assemblyBinding> incluem o <elemento dependentAssembly>. Os filhos do <elemento dependentAssembly> incluem o <elemento assemblyIdentity>, o <elemento bindingRedirect> e o <elemento codeBase>.

Observação

As informações de configuração podem ser encontradas nos três arquivos de configuração; Nem todos os elementos são válidos em todos os arquivos de configuração. Por exemplo, o modo de vinculação e as informações de caminho privado só podem estar no arquivo de configuração do aplicativo. Para obter uma lista completa das informações contidas em cada arquivo, consulte Configurando aplicativos usando arquivos de configuração.

Ficheiro de Configuração da Aplicação

Primeiro, o Common Language Runtime verifica o ficheiro de configuração do aplicativo em busca de informações que substituam as informações de versão armazenadas no manifesto do assembly chamador. O arquivo de configuração do aplicativo pode ser implantado com um aplicativo, mas não é necessário para a execução do aplicativo. Normalmente, a recuperação desse arquivo é quase instantânea, mas em situações em que a base do aplicativo está em um computador remoto, como em um cenário baseado na Web, o arquivo de configuração deve ser baixado.

Para executáveis cliente, o arquivo de configuração do aplicativo reside no mesmo diretório que o executável do aplicativo e tem o mesmo nome base que o executável com uma extensão .config. Por exemplo, o arquivo de configuração para C:\Program Files\Myapp\Myapp.exe é C:\Program Files\Myapp\Myapp.exe.config. Em um cenário baseado em navegador, o arquivo HTML deve usar o <elemento link> para apontar explicitamente para o arquivo de configuração.

O código a seguir fornece um exemplo simples de um arquivo de configuração do aplicativo. Este exemplo adiciona um TextWriterTraceListener à coleção Listeners para habilitar a gravação de informações de depuração em um arquivo.

<configuration>
   <system.diagnostics>
      <trace useGlobalLock="false" autoflush="true" indentsize="0">
         <listeners>
            <add name="myListener" type="System.Diagnostics.TextWriterTraceListener, system version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="c:\myListener.log" />
         </listeners>
      </trace>
   </system.diagnostics>
</configuration>

Arquivo de política do Publisher

Em segundo lugar, o tempo de execução examina o ficheiro de política do editor, se existir. Os arquivos de política do Publisher são distribuídos por um editor de componentes como uma correção ou atualização para um componente compartilhado. Esses arquivos contêm informações de compatibilidade emitidas pelo editor do componente compartilhado que direciona uma referência de assembly para uma nova versão. Ao contrário dos ficheiros de configuração de aplicações e de máquinas, os ficheiros de política do publicador estão contidos na sua própria assembly que deve ser instalada na cache de assembly global.

Segue-se um exemplo de um ficheiro de configuração da Política do Publisher:

<configuration>
    <runtime>
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">

            <dependentAssembly>
                <assemblyIdentity name="asm6" publicKeyToken="c0305c36380ba429" />
                <bindingRedirect oldVersion="3.0.0.0" newVersion="2.0.0.0"/>
            </dependentAssembly>

        </assemblyBinding>
    </runtime>
</configuration>

Para criar um assembly, você pode usar a ferramenta Al.exe (Assembly Linker) com um comando como o seguinte:

Al.exe /link:asm6.exe.config /out:policy.3.0.asm6.dll /keyfile: compatkey.dat /v:3.0.0.0

compatkey.dat é um arquivo de chave de nome forte. Este comando cria uma assemblagem de nome forte que pode-se introduzir na cache de assemblagem global.

Observação

A política do Publisher afeta todos os aplicativos que usam um componente compartilhado.

O arquivo de configuração de política do editor substitui as informações de versão provenientes do aplicativo (ou seja, do manifesto do assembly ou do arquivo de configuração do aplicativo). Se não houver nenhuma instrução no arquivo de configuração do aplicativo para redirecionar a versão especificada no manifesto do assembly, o arquivo de política do editor substituirá a versão especificada no manifesto do assembly. No entanto, se houver uma instrução de redirecionamento no arquivo de configuração do aplicativo, a política do editor substituirá essa versão em vez da especificada no manifesto.

Um arquivo de política do editor é usado quando um componente compartilhado é atualizado e a nova versão do componente compartilhado deve ser coletada por todos os aplicativos que usam esse componente. As configurações no arquivo de política do editor substituem as configurações no arquivo de configuração do aplicativo, a menos que o arquivo de configuração do aplicativo imponha o modo de segurança.

Modo de Segurança

Os arquivos de política do Publisher geralmente são instalados explicitamente como parte de um service pack ou atualização de programa. Se houver algum problema com o componente partilhado atualizado, pode ignorar as sobrescrições no ficheiro de política do publicador usando o modo seguro. O modo de segurança é determinado pelo <elemento publisherPolicy apply="yes|no"/> , localizado apenas no arquivo de configuração do aplicativo. Ele especifica se as informações de configuração da política do editor devem ser removidas do processo de vinculação.

O modo de segurança pode ser configurado para toda a aplicação ou para conjuntos selecionados. Ou seja, pode desativar a política para todos os módulos que compõem a aplicação ou ativá-la para alguns módulos, mas não para outros. Para aplicar seletivamente a política de editor a assemblies que compõem um aplicativo, defina <publisherPolicy apply=no/> e especifique quais assemblies você deseja que sejam afetados usando o < elemento dependentAssembly>. Para aplicar a política de editor a todos os conjuntos que compõem a aplicação, defina <publisherPolicy apply=no/> sem incluir elementos de conjuntos dependentes. Para obter mais informações sobre configuração, consulte Configurando aplicativos usando arquivos de configuração.

Arquivo de configuração da máquina

Em terceiro lugar, o tempo de execução examina o arquivo de configuração da máquina. Esse arquivo, chamado Machine.config, reside no computador local no subdiretório Config do diretório raiz onde o tempo de execução está instalado. Esse arquivo pode ser usado por administradores para especificar restrições de vinculação de assembly que são locais para esse computador. As configurações no arquivo de configuração da máquina têm precedência sobre todas as outras definições de configuração; No entanto, isso não significa que todas as definições de configuração devam ser colocadas neste arquivo. A versão determinada pelo arquivo de política do administrador é final e não pode ser substituída. As substituições especificadas no arquivo Machine.config afetam todos os aplicativos. Para obter mais informações sobre arquivos de configuração, consulte Configurando aplicativos usando arquivos de configuração.

Etapa 2: Verificar Conjuntos Referenciados Anteriormente

Se o assembly solicitado também tiver sido solicitado em chamadas anteriores, o common language runtime usará o assembly que já está carregado. Isso pode ter ramificações ao nomear assemblies que compõem um aplicativo. Para obter mais informações sobre como nomear assemblies, consulte Nomes de assemblies.

Se uma solicitação anterior para o conjunto falhar, as solicitações subsequentes para o conjunto falham imediatamente sem tentar carregar o conjunto. A partir da versão 2.0 do .NET Framework, as falhas de vinculação de assembly são armazenadas em cache, e as informações em cache são usadas para determinar se deve-se tentar carregar o assembly.

Observação

Para reverter para o comportamento das versões 1.0 e 1.1 do .NET Framework, que não armazenavam falhas de vinculação em cache, inclua o elemento <disableCachingBindingFailures> no arquivo de configuração.

Etapa 3: Verificação do Cache de Assembly Global

Para assemblies com nomes fortes, o processo de ligação continua examinando o cache de assembly global. O cache global de assembly armazena assemblies que podem ser usados por várias aplicações em um computador. Todos os assemblies na cache de assembly global devem ter nomes robustos.

Etapa 4: Localizando o assembly através de bases de código ou sondagem

Depois que a versão correta do assembly tiver sido determinada usando as informações na referência do assembly de chamada e nos arquivos de configuração, e após a verificação no cache global de assemblies (somente para assemblies de nome forte), o tempo de execução da linguagem comum tentará localizar o assembly. O processo de localização de um assembly envolve os seguintes passos:

  1. Se for encontrado um <elemento codeBase> no ficheiro de configuração da aplicação, o tempo de execução verificará o local especificado. Se uma correspondência for encontrada, esse assembly será usado e nenhum teste será realizado. Se o assembly não for encontrado lá, a solicitação de vinculação falha.

  2. Em seguida, o tempo de execução investiga o assembly referenciado usando as regras especificadas posteriormente nesta seção.

Observação

Caso tenha várias versões de um assembly num diretório e queira fazer referência a uma versão específica desse assembly, deverá usar o elemento <codeBase> em vez do atributo do elemento privatePath. Se você usar o <elemento probing> , o tempo de execução para de sondar na primeira vez que encontrar um assembly que corresponda ao nome de assembly simples referenciado, seja ele uma correspondência correta ou não. Se for uma correspondência correta, essa assemblagem é usada. Se não for uma correspondência correta, a sondagem é interrompida e a ligação falha.

Localizando o assembly através de bases de código

As informações da base de código podem ser fornecidas usando um <elemento codeBase> em um arquivo de configuração. Essa base de código é sempre verificada antes que o ambiente de execução tente explorar o assembly referenciado. Se um arquivo de política do editor contendo o redirecionamento da versão final também contiver um <elemento codeBase> , esse <elemento codeBase> será o usado. Por exemplo, se o arquivo de configuração do aplicativo especificar um <elemento codeBase> e um arquivo de política do editor que está substituindo as informações do aplicativo também especificar um <elemento codeBase> , o <elemento codeBase> no arquivo de política do editor será usado.

Se nenhuma correspondência for encontrada no local especificado pelo <elemento codeBase> , a solicitação de associação falhará e nenhuma outra etapa será executada. Se o tempo de execução determinar que um assembly corresponde aos critérios do assembly chamador, ele usará esse assembly. Quando o arquivo especificado pelo elemento codeBase< fornecido> é carregado, o runtime verifica se o nome, a versão, a cultura e a chave pública correspondem à referência do assembly chamador.

Observação

Os assemblies referenciados fora do diretório raiz do aplicativo devem ter nomes fortes e devem ser instalados no cache de assembly global ou especificados usando o <elemento codeBase> .

Localizando a montagem através de sondagem

Se não houver nenhum <elemento codeBase> no ficheiro de configuração da aplicação, o tempo de execução explora a assembly usando quatro critérios:

  • Base do aplicativo, que é o local raiz onde o aplicativo está sendo executado.

  • Cultura, que é o atributo cultural da montagem que está sendo referenciada.

  • Nome, que é o nome do conjunto referenciado.

  • O atributo privatePath do elemento <probing>, que é a lista de subdiretórios definida pelo utilizador no local raiz. Este local pode ser especificado no ficheiro de configuração da aplicação e no código gerido, usando a propriedade AppDomainSetup.PrivateBinPath para um domínio de aplicação. Quando especificado no código gerenciado, o código privatePath gerenciado é investigado primeiro, seguido pelo caminho especificado no arquivo de configuração do aplicativo.

Examinando a base de aplicativos e os diretórios de cultura

O runtime sempre começa por testar na base da aplicação, que pode ser uma URL ou o diretório raiz num computador. Se o assembly referenciado não for encontrado na base do aplicativo e nenhuma informação de cultura for fornecida, o tempo de execução pesquisará quaisquer subdiretórios com o nome do assembly. Os diretórios investigados incluem:

  • [base de aplicação] / [nome da montagem].dll

  • [base da aplicação] / [nome do conjunto] / [nome do conjunto].dll

Se a informação cultural for especificada para o assembly referenciado, apenas os seguintes diretórios serão consultados:

  • [base de aplicação] / [cultura] / [nome da montagem].dll

  • [base do aplicativo] / [cultura] / [nome da assemblagem] / [nome da assemblagem].dll

Sondando com o atributo privatePath

Além dos subdiretórios de cultura e dos subdiretórios nomeados para o assembly referenciado, o runtime também investiga diretórios especificados usando o atributo privatePath do elemento <probing>. Os diretórios especificados usando o privatePath atributo devem ser subdiretórios do diretório raiz do aplicativo. Os diretórios analisados dependem de se as informações de cultura são incluídas na solicitação de assembly referenciada.

O tempo de execução para de sondar a primeira vez que encontra um assembly que corresponde ao nome de assembly simples referenciado, se é uma correspondência correta ou não. Se for uma correspondência correta, essa assemblagem é usada. Se não for uma correspondência correta, a sondagem é interrompida e a ligação falha.

Se a cultura estiver incluída, os seguintes diretórios serão investigados:

  • [base da aplicação] / [binpath] / [cultura] / [nome da assemblagem].dll

  • [base do aplicativo] / [binpath] / [cultura] / [nome do assembly] / [nome do assembly].dll

Se a informação cultural não for incluída, os seguintes diretórios serão analisados:

  • [base de aplicativos] / [binpath] / [nome do assembly].dll

  • [base do aplicativo] / [binpath] / [nome do assembly] / [nome do assembly].dll

Exemplos de sondagem

Dada a seguinte informação:

  • Nome do assembly referenciado: "myAssembly"

  • Diretório raiz do aplicativo: http://www.code.microsoft.com

  • <elemento de sondagem> no arquivo de configuração especifica: bin

  • Cultura: DE

O ambiente de execução investiga as seguintes URLs:

  • http://www.code.microsoft.com/de/myAssembly.dll

  • http://www.code.microsoft.com/de/myAssembly/myAssembly.dll

  • http://www.code.microsoft.com/bin/de/myAssembly.dll

  • http://www.code.microsoft.com/bin/de/myAssembly/myAssembly.dll

Vários assemblies com o mesmo nome

O exemplo a seguir mostra como configurar vários assemblies com o mesmo nome.

<dependentAssembly>
   <assemblyIdentity name="Server" publicKeyToken="c0305c36380ba429" />
   <codeBase version="1.0.0.0" href="v1/Server.dll" />
   <codeBase version="2.0.0.0" href="v2/Server.dll" />
</dependentAssembly>

Outros locais sondados

O local da montagem também pode ser determinado usando o contexto de vinculação atual. Isso ocorre com mais frequência quando o Assembly.LoadFrom método é usado e em cenários de interoperabilidade COM. Se um assembly usa o método LoadFrom para referenciar outro assembly, a localização do assembly que faz a chamada é considerada uma dica sobre onde encontrar o assembly referenciado. Se uma correspondência for encontrada, esse conjunto será carregado. Se não for encontrada nenhuma correspondência, o tempo de execução continuará com a sua semântica de pesquisa e, em seguida, consultará o Windows Installer para fornecer o conjunto. Se não for fornecido nenhum conjunto que corresponda à solicitação de vinculação, uma exceção é lançada. Essa exceção é um TypeLoadException código gerenciado se um tipo foi referenciado ou um FileNotFoundException se um assembly que está sendo carregado não foi encontrado.

Por exemplo, se Assembly1 fizer referência a Assembly2 e Assembly1 foi baixado do http://www.code.microsoft.com/utils, esse local será considerado uma dica sobre onde encontrar Assembly2.dll. Em seguida, o tempo de execução investiga o assembly em http://www.code.microsoft.com/utils/Assembly2.dll e http://www.code.microsoft.com/utils/Assembly2/Assembly2.dll. Se Assembly2 não for encontrado em nenhum desses locais, o runtime verificará o Windows Installer.

Ver também