Redirecionar versões de montagem

2025-03-06

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.

Você pode redirecionar referências de vinculação em tempo de compilação para assemblies do .NET Framework, assemblies de terceiros ou assemblies do seu próprio aplicativo. Você pode redirecionar seu aplicativo para usar uma versão diferente de um assembly de várias maneiras: por meio da política do editor, de um arquivo de configuração do aplicativo ou do arquivo de configuração da máquina. Este artigo descreve como a associação de assembly funciona no .NET Framework e como você pode configurá-la.

Dica

Este artigo é específico para aplicativos .NET Framework. Para obter informações sobre o carregamento de assembly no .NET 5+ (e no .NET Core), consulte carregamento de dependência no .NET.

Unificação de assemblagem e vinculação padrão

Às vezes, as ligações para assemblies do .NET Framework são redirecionadas através de um processo chamado Unificação de Assembly . O .NET Framework consiste em uma versão do Common Language Runtime e cerca de duas dúzias de assemblies do .NET Framework que compõem a biblioteca de tipos. Esses assemblies do .NET Framework são tratados pelo tempo de execução como uma única unidade. Por padrão, quando um aplicativo é iniciado, todas as referências a tipos de código executados pelo tempo de execução são direcionadas para assemblies do .NET Framework que têm o mesmo número de versão do tempo de execução carregado em um processo. Os redirecionamentos que ocorrem com esse modelo são o comportamento padrão para o tempo de execução.

Por exemplo, se seu aplicativo faz referência a tipos no namespace System.XML e foi criado usando o .NET Framework 4.5, ele contém referências estáticas ao assembly System.XML fornecido com a versão 4.5 do tempo de execução. Se quiser redirecionar a referência de vinculação para apontar para o assembly System.XML fornecido com o .NET Framework 4, você pode colocar informações de redirecionamento no arquivo de configuração do aplicativo. Um redireccionamento de associação num ficheiro de configuração para um assembly unificado do .NET Framework interrompe a unificação desse assembly.

Além disso, talvez você queira redirecionar manualmente a vinculação de assembly para assemblies de terceiros se houver várias versões disponíveis.

Dica

Se você atualizar um pacote NuGet ao qual seu aplicativo faz referência indiretamente e começar a ver novos erros, como FileLoadException, MissingMethodException, TypeLoadExceptionou FileNotFoundException, talvez seja necessário habilitar redirecionamentos de vinculação automática ou adicionar manualmente um redirecionamento de vinculação. Isso é normal ao atualizar pacotes NuGet e é resultado de alguns pacotes serem criados em relação a uma versão mais antiga de uma dependência. O seguinte trecho do ficheiro de configuração da aplicação adiciona um redirecionamento de vinculação para o pacote System.Memory:

<dependentAssembly>
   <assemblyIdentity name="System.Memory" publicKeyToken="cc7b13ffcd2ddd51" culture="neutral" />
   <bindingRedirect oldVersion="0.0.0.0-4.0.2.0" newVersion="4.0.2.0" />
</dependentAssembly>

Redirecionar versões usando a política do editor

Os fornecedores de componentes podem direcionar os aplicativos para uma versão mais recente de um componente incluindo um ficheiro de política do editor com o novo componente. O ficheiro de política do editor, que está localizado no cache global de montagem, contém configurações de redirecionamento de montagem.

Cada versão principal.versão secundária de um assembly tem o seu próprio arquivo de política do editor. Por exemplo, redirecionamentos da versão 2.0.2.222 para 2.0.3.000 e da versão 2.0.2.321 para a versão 2.0.3.000 vão para o mesmo arquivo, porque estão associados à versão 2.0. No entanto, um redirecionamento da versão 3.0.0.999 para a versão 4.0.0.000 é inserido no arquivo da versão 3.0.0.999. Cada versão principal do .NET Framework tem seu próprio arquivo de política de editor.

Caso exista um ficheiro de política do publicador para um assembly, o tempo de execução verificará esse ficheiro depois de verificar o manifesto do assembly e o ficheiro de configuração da aplicação. Os fornecedores devem usar arquivos de política do editor somente quando o novo assembly for retrocompatível com o assembly que está sendo redirecionado.

Você pode ignorar a política do editor para seu aplicativo especificando as configurações no arquivo de configuração do aplicativo, conforme discutido na seção Ignorar política do editor.

Redirecionar versões no nível do aplicativo

Existem algumas técnicas diferentes para alterar o comportamento de associação para seu aplicativo por meio do arquivo de configuração do aplicativo: você pode editar manualmente o arquivo, pode confiar no redirecionamento de vinculação automáticoou pode especificar o comportamento de vinculação ignorando de política do editor.

Editar manualmente o arquivo de configuração do aplicativo

Você pode editar manualmente o arquivo de configuração do aplicativo para resolver problemas de montagem. Por exemplo, se um fornecedor lançar uma versão mais recente de um *assembly* que a sua aplicação usa sem fornecer uma política do editor (porque eles não garantem compatibilidade com versões anteriores), poderá direcionar a sua aplicação para usar a versão mais recente do *assembly* inserindo as informações de vinculação do *assembly* no ficheiro de configuração da aplicação da seguinte forma.

<dependentAssembly>
  <assemblyIdentity name="someAssembly"
    publicKeyToken="32ab4ba45e0a69a1"
    culture="en-us" />
  <bindingRedirect oldVersion="7.0.0.0" newVersion="8.0.0.0" />
</dependentAssembly>

Confie no redirecionamento automático de vinculação

Quando o utilizador cria uma aplicação de ambiente de trabalho no Visual Studio destinada ao .NET Framework 4.5.1 ou a uma versão posterior, a aplicação utiliza o redirecionamento de vinculação deste automaticamente. Isso significa que, se dois componentes fizerem referência a versões diferentes do mesmo assembly de nome forte, o tempo de execução adicionará automaticamente um redirecionamento de vinculação à versão mais recente do assembly no arquivo de configuração do aplicativo de saída (app.config). Esse redirecionamento substitui a unificação da assembleia que, de outra forma, poderia ocorrer. O arquivo app.config de origem não é modificado. Por exemplo, digamos que seu aplicativo faça referência direta a um componente .NET Framework fora de banda, mas use uma biblioteca de terceiros destinada a uma versão mais antiga do mesmo componente. Quando você compila o aplicativo, o arquivo de configuração do aplicativo de saída é modificado para conter um redirecionamento de vinculação para a versão mais recente do componente.

Se você criar um aplicativo Web, receberá um aviso de compilação sobre o conflito de vinculação, que, por sua vez, lhe dará a opção de adicionar o redirecionamento de vinculação necessário ao arquivo de configuração da Web de origem.

Se adicionares manualmente redirecionamentos de associação ao ficheiro app.config de origem, em tempo de compilação, o Visual Studio tenta unificar os assemblies com base nos redirecionamentos de associação adicionados. Por exemplo, digamos que você insira o seguinte redirecionamento de vinculação para um assembly:

<bindingRedirect oldVersion="3.0.0.0" newVersion="2.0.0.0" />

Se outro projeto em seu aplicativo fizer referência à versão 1.0.0.0 do mesmo assembly, o redirecionamento automático de vinculação adicionará a seguinte entrada ao arquivo de app.config de saída para que o aplicativo seja unificado na versão 2.0.0.0 desse assembly:

<bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0" />

Você pode habilitar o redirecionamento de vinculação automática se seu aplicativo tiver como destino versões mais antigas do .NET Framework. Você pode substituir este comportamento predefinido fornecendo informações de redirecionamento de associação no arquivo app.config para qualquer assembly ou desligando o recurso de redirecionamento de associação. Para obter informações sobre como ativar ou desativar esse recurso, consulte Como ativar e desativar o redirecionamento automático de vinculação.

Ignorar a política do editor

Você pode substituir a política do editor no arquivo de configuração do aplicativo, se necessário. Por exemplo, novas versões de assemblies que alegam ser compatíveis com versões anteriores ainda podem causar falhas numa aplicação. Se quiseres ignorar a política do editor, adiciona um elemento <publisherPolicy> ao elemento <dependentAssembly> no ficheiro de configuração da aplicação e define o atributo apply como no, o que substitui todas as configurações de yes anteriores.

<publisherPolicy apply="no" />

Ignore a política do editor para manter seu aplicativo em execução para seus usuários, mas certifique-se de relatar o problema ao fornecedor do assembly. Se um conjunto tiver um ficheiro de política do editor, o fornecedor deve certificar-se de que o conjunto é compatível com versões anteriores e que os clientes possam usar ao máximo a nova versão.

Redirecionar versões para testes, plug-ins ou bibliotecas usadas por outro componente

Para testes, você deve gerar um arquivo .dll.config. A maioria das estruturas de teste de unidade existentes honram esses arquivos ao carregar testes.

Plugins podem suportar os arquivos .dll.config, no entanto, eles podem também não o fazer. O único mecanismo infalível para redirecionamentos é fornecendo bindingRedirects quando o AppDomain é criado.

Você pode tentar resolver esse problema com manipuladores de eventos AssemblyResolve, mas isso não funciona, pois esses manipuladores só são chamados em uma carga com falha. Se uma carga de assembly for bem-sucedida, seja porque foi carregada por outro assembly ou pelo host, ou porque estava presente no GAC, um manipulador de AssemblyResolve não será chamado.

Redirecionar versões no nível da máquina

Pode haver casos raros em que um administrador de máquina deseja que todos os aplicativos em um computador usem uma versão específica de um assembly. Por exemplo, uma versão específica pode corrigir uma falha de segurança. Se um assembly for redirecionado no arquivo de configuração da máquina, chamado machine.config, todos os aplicativos nessa máquina que usam a versão antiga serão direcionados para usar a nova versão. O arquivo de configuração da máquina substitui o arquivo de configuração do aplicativo e o arquivo de política do editor. Esse arquivo machine.config está localizado em %windir%\Microsoft.NET\Framework[version]\config\machine.config para máquinas de 32 bits ou %windir%\Microsoft.NET\Framework64[version]\config\machine.config para máquinas de 64 bits.

Especificar a vinculação de assembly em arquivos de configuração

Você usa o mesmo formato XML para especificar redirecionamentos de vinculação, seja no arquivo de configuração do aplicativo, no arquivo de configuração da máquina ou no arquivo de política do editor. Para redirecionar uma versão de assembly para outra, use o elemento <bindingRedirect>. O atributo oldVersion pode especificar uma única versão de assembly ou um intervalo de versões. O atributo newVersion deve especificar uma única versão. Por exemplo, <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> especifica que o runtime deve usar a versão 2.0.0.0 em vez das versões de montagem entre 1.1.0.0 e 1.2.0.0.

O exemplo de código a seguir demonstra vários cenários de redirecionamento de associações. O exemplo especifica um redirecionamento para um intervalo de versões para myAssemblye um único redirecionamento de vinculação para mySecondAssembly. O exemplo também especifica que o ficheiro de política do editor não substituirá os redirecionamentos de associação para myThirdAssembly.

Para vincular um assembly, deves especificar a cadeia de caracteres "urn:schemas-microsoft-com:asm.v1" com o atributo xmlns na tag <assemblyBinding>.

<configuration>
  <runtime>
    <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">
      <dependentAssembly>
        <assemblyIdentity name="myAssembly"
          publicKeyToken="32ab4ba45e0a69a1"
          culture="en-us" />
        <!-- Assembly versions can be redirected in app,
          publisher policy, or machine configuration files. -->
        <bindingRedirect oldVersion="1.0.0.0-2.0.0.0" newVersion="3.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
        <assemblyIdentity name="mySecondAssembly"
          publicKeyToken="32ab4ba45e0a69a1"
          culture="en-us" />
             <bindingRedirect oldVersion="1.0.0.0" newVersion="2.0.0.0" />
      </dependentAssembly>
      <dependentAssembly>
      <assemblyIdentity name="myThirdAssembly"
        publicKeyToken="32ab4ba45e0a69a1"
        culture="en-us" />
        <!-- Publisher policy can be set only in the app
          configuration file. -->
        <publisherPolicy apply="no" />
      </dependentAssembly>
    </assemblyBinding>
  </runtime>
</configuration>

Limitar associações de assembly a uma versão específica

Você pode usar o atributo appliesTo no elemento <assemblyBinding> em um arquivo de configuração de aplicativo para redirecionar referências de vinculação de assembly para uma versão específica do .NET Framework. Esse atributo opcional usa um número de versão do .NET Framework para indicar a qual versão ele se aplica. Se nenhum atributo appliesTo for especificado, o elemento <assemblyBinding> se aplicará a todas as versões do .NET Framework.

Por exemplo, para redirecionar a vinculação de assembly para um assembly do .NET Framework 3.5, inclua o seguinte código XML no ficheiro de configuração da aplicação.

<runtime>
  <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1"
    appliesTo="v3.5">
    <dependentAssembly>
      <!-- assembly information goes here -->
    </dependentAssembly>
  </assemblyBinding>
</runtime>

Você deve inserir as informações de redirecionamento na ordem de versão. Por exemplo, insira informações de redirecionamento de ligação de assembly para componentes do .NET Framework 3.5 e depois para componentes do .NET Framework 4.5. Finalmente, insira informações de redirecionamento de vinculação de assembly para qualquer redirecionamento de assembly do .NET Framework que não use o atributo appliesTo e, portanto, se aplique a todas as versões do .NET Framework. Se houver um conflito no redirecionamento, a primeira instrução de redirecionamento correspondente no arquivo de configuração será usada.

Por exemplo, para redirecionar uma referência a um assembly do .NET Framework 3.5 e outra referência a um assembly do .NET Framework 4, use o padrão mostrado no pseudocódigo a seguir.

<assemblyBinding xmlns="..." appliesTo="v3.5 ">
  <!--.NET Framework version 3.5 redirects here -->
</assemblyBinding>

<assemblyBinding xmlns="..." appliesTo="v4.0.30319">
  <!--.NET Framework version 4.0 redirects here -->
</assemblyBinding>

<assemblyBinding xmlns="...">
  <!-- redirects meant for all versions of the runtime -->
</assemblyBinding>