Como redirecionar versões de assembly

Artigo
05/10/2023

Você pode redirecionar referências de associação de tempo de compilação para assemblies do .NET Framework, assemblies de terceiros ou assemblies do seu 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, por meio de um arquivo de configuração de aplicativos; ou por meio do arquivo de configuração de máquina. Este artigo discute como a associação de assembly funciona no .NET Framework e como ela pode ser configurada.

Dica

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

Unificação de assembly e associação padrão

As associações para assemblies do .NET Framework às vezes são redirecionadas por meio 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 runtime como uma só unidade. Por padrão, quando um aplicativo é iniciado, todas as referências a tipos em código executados pelo runtime são direcionadas para assemblies do .NET Framework que têm o mesmo número de versão que o runtime carregado em um processo. Os redirecionamentos que ocorrem com esse modelo são o comportamento padrão para o runtime.

Por exemplo, se o aplicativo referenciar tipos no namespace System.XML e tiver sido criado usando .NET Framework 4.5, ele conterá referências estáticas ao assembly System.XML fornecido com a versão 4.5 do runtime. Se você quiser redirecionar a referência de associação para apontar para o assembly System.XML fornecido com .NET Framework 4, poderá colocar informações de redirecionamento no arquivo de configuração de aplicativos. Um redirecionamento de associação em um arquivo de configuração para um assembly do .NET Framework unificado cancela a unificação desse assembly.

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

Redirecionar versões usando a política do editor

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

Cada versão major.minor de um assembly tem o próprio arquivo de política de 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 entram no mesmo arquivo, pois 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 entra no arquivo para a versão 3.0.999. Cada versão principal do .NET Framework tem um arquivo de política de editor próprio.

Se houver um arquivo de política de editor para um assembly, o runtime verificará esse arquivo depois de verificar o manifesto do assembly e o arquivo de configuração de aplicativos. Os fornecedores devem usar arquivos de política do editor somente quando o novo assembly for compatível com versões anteriores 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 de aplicativos, conforme discutido na seção Ignorar política do editor.

Redirecionar versões no nível do aplicativo

Há algumas técnicas diferentes para alterar o comportamento de associação para seu aplicativo por meio do arquivo de configuração de aplicativos: você pode editar manualmente o arquivo, pode contar com o redirecionamento automático de associação ou pode especificar o comportamento de associação ignorando a política do editor.

Editar manualmente o arquivo de configuração do aplicativo

Você pode editar manualmente o arquivo de configuração de aplicativos para resolver problemas de assembly. Por exemplo, se um fornecedor pode lançar uma versão mais recente de um assembly que seu aplicativo usa sem fornecer uma política de editor, porque ele não garante compatibilidade com versões anteriores, você pode direcionar seu aplicativo para usar a versão mais recente do assembly colocando informações de associação de assembly no arquivo de configuração do aplicativo maneira a seguir.

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

Contar com o redirecionamento automático de associação

Quando você cria um aplicativo da área de trabalho no Visual Studio que tem como destino o .NET Framework 4.5.1 ou uma versão posterior, o aplicativo usa o redirecionamento automático de associação. Isso significa que, se dois componentes fizerem referência a versões diferentes do mesmo assembly de nome forte, o runtime adicionará automaticamente um redirecionamento de associação à versão mais recente do assembly no arquivo de configuração de aplicativos de saída (app.config). Esse redirecionamento substitui a unificação do assembly que, de outra forma, poderia ocorrer. O arquivo de origem app.config não é modificado. Por exemplo, digamos que seu aplicativo faça referência direta a um componente do .NET Framework fora de banda, mas use uma biblioteca de terceiros que tem como destino uma versão mais antiga do mesmo componente. Quando você compila o aplicativo, o arquivo de configuração de aplicativos de saída é modificado para conter um redirecionamento de associação para a versão mais recente do componente. Se você criar um aplicativo Web, receberá um aviso de build sobre o conflito de associação, o que, por sua vez, oferece a opção de adicionar o redirecionamento de associação necessário ao arquivo de configuração da Web de origem.

Se você adicionar redirecionamentos de associação manualmente ao arquivo app.config de origem, no tempo de compilação, o Visual Studio tentará unificar os assemblies com base nos redirecionamentos de associação adicionados. Por exemplo, digamos que você insira o seguinte redirecionamento de associaçã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 de associação automática adicionará a seguinte entrada ao arquivo de saída app.config para que o aplicativo seja unificado na versão 2.0.0.0 deste assembly:

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

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

Ignorar a política do editor

Você pode substituir a política do editor no arquivo de configuração de aplicativos, se necessário. Por exemplo, novas versões de assemblies que afirmam ser compatíveis com versões anteriores ainda podem interromper um aplicativo. Se você quiser ignorar a política do editor, adicione um elemento <publisherPolicy> ao elemento <dependentAssembly> no arquivo de configuração de aplicativos e defina o atributo apply como não, o que substitui as configurações sim anteriores.

<publisherPolicy apply="no" />

Ignore a política do editor para manter seu aplicativo em execução para seus usuários, mas não deixe de relatar o problema ao fornecedor do assembly. Se um assembly tiver um arquivo de política de editor, o fornecedor deverá verificar se o assembly é compatível com versões anteriores e se os clientes podem usar a nova versão o máximo possível.

Redirecionar versões no nível do computador

Pode haver casos raros em que um administrador de computador 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 do computador, chamado machine.config, todos os aplicativos no computador que usam a versão antiga serão direcionados para usar a nova versão. O arquivo de configuração de máquina substitui o arquivo de configuração de aplicativos e o arquivo de política do editor. Esse arquivo machine.config está localizado em %windir%\Microsoft.NET\Framework[versão]\config\machine.config para computadores de 32 bits ou %windir%\Microsoft.NET\Framework64[versão]\config\machine.config para computadores de 64 bits.

Especificar associação de assembly em arquivos de configuração

Você usa o mesmo formato XML para especificar redirecionamentos de associação, seja no arquivo de configuração de aplicativos, no arquivo de configuração de máquina ou no arquivo de política do editor. Para redirecionar uma versão do assembly para outra, use o elemento <bindingRedirect>. O atributo oldVersion pode especificar uma só versão do assembly ou um intervalo de versões. O atributo newVersion deve especificar uma só 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 do assembly entre 1.1.0.0 e 1.2.0.0.

O exemplo de código a seguir demonstra uma variedade de cenários de redirecionamento de associação. O exemplo especifica um redirecionamento para um intervalo de versões para myAssembly e um só redirecionamento de associação para mySecondAssembly. O exemplo também especifica que o arquivo de política do editor não substituirá os redirecionamentos de associação para myThirdAssembly.

Para associar um assembly, você deve especificar a cadeia de caracteres "urn:schemas-microsoft-com:asm.v1" com o atributo xmlns na marca <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 aplicativos para redirecionar referências de associaçã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 aplica a todas as versões do .NET Framework.

Por exemplo, para redirecionar a associação de assembly para um assembly do .NET Framework 3.5, inclua código XML a seguir no seu arquivo de configuração de aplicativos.

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

Insira informações de redirecionamento na ordem de versão. Por exemplo, insira informações de redirecionamento de associação de assembly para assemblies do .NET Framework 3.5 seguidos por assemblies do .NET Framework 4.5. Por fim, insira as informações de redirecionamento de associação de assembly para qualquer redirecionamento de assembly do .NET Framework que não use o atributo appliesTo e, portanto, se aplica a todas as versões do .NET Framework. Se houver um conflito de 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>