Redirecionamento de versões de montagem

Artigo
03/05/2024

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, por meio de um arquivo de configuração do aplicativo; ou através do arquivo de configuração da máquina. Este artigo descreve como a vinculação de assembly funciona no .NET Framework e como ela pode ser configurada.

Gorjeta

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

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

Ligaçõ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 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 redirecionamento de vinculação em um arquivo de configuração para um assembly unificado do .NET Framework cancela a unificação desse assembly.

Além disso, convém redirecionar manualmente a vinculaçã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 do 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 major.A versão secundária de um assembly tem 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 vai para o arquivo para a versão 3.0.999. Cada versão principal do .NET Framework tem seu próprio arquivo de política de editor.

Se existir um arquivo de política do editor para um assembly, o tempo de execução verificará esse arquivo depois de verificar o manifesto do assembly e o arquivo de configuração do aplicativo. Os fornecedores devem usar arquivos de política do editor somente quando o novo assembly for compatível com versões anteriores do 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 Ignorando a política do editor.

Redirecionar versões no nível do aplicativo

Há algumas técnicas diferentes para alterar o comportamento de associação do seu aplicativo por meio do arquivo de configuração do aplicativo: você pode editar manualmente o arquivo, confiar no redirecionamento automático de vinculação ou especificar o comportamento de vinculaçã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 do aplicativo para resolver problemas de montagem. 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 eles não garantem compatibilidade com versões anteriores, você pode direcionar seu aplicativo para usar a versão mais recente do assembly colocando informações de vinculação de assembly no arquivo de configuração do aplicativo da seguinte maneira.

<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 você cria um aplicativo de área de trabalho no Visual Studio destinado ao .NET Framework 4.5.1 ou uma versão posterior, o aplicativo usa o redirecionamento de vinculação automática. 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 você adicionar manualmente redirecionamentos de vinculação ao arquivo app.config de origem, em 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 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 de vinculação automática adicionará a seguinte entrada ao arquivo 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 esse comportamento padrão fornecendo informações de redirecionamento de vinculação no arquivo app.config para qualquer assembly ou desativando o recurso de redirecionamento de vinculação. Para obter informações sobre como ativar ou desativar esse recurso, consulte Como habilitar e desabilitar 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 afirmam ser compatíveis com versões anteriores ainda podem quebrar um aplicativo. Se você quiser ignorar a política do editor, adicione um <elemento publisherPolicy> ao <elemento dependentAssembly> no arquivo de configuração do aplicativo e defina o atributo apply como no, que substitui todas as configurações anteriores yes.

<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 assembly tiver um arquivo de política do editor, o fornecedor deve certificar-se de que o assembly é compatível com versões anteriores e que os clientes podem usar a nova versão tanto quanto possível.

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. Este ficheiro 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 newVersion atributo 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 tempo de execução deve usar a versão 2.0.0.0 em vez das versões de 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 vinculação. O exemplo especifica um redirecionamento para um intervalo de versões para myAssembly, e um único redirecionamento de vinculação para mySecondAssembly. O exemplo também especifica que o arquivo de política do editor não substituirá os redirecionamentos de vinculação para myThirdAssembly.

Para vincular um assembly, você deve 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 ligações de montagem 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 arquivo de configuração do aplicativo.

<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 vinculação de assembly para assemblies do .NET Framework 3.5 seguidos por assemblies 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>