Redirecionando versões de assemblyRedirecting Assembly Versions

Você pode redirecionar referências de associação de tempo de compilação para .NET Framework assemblies, assemblies de terceiros ou assemblies de seu próprio aplicativo.You can redirect compile-time binding references to .NET Framework assemblies, third-party assemblies, or your own app's assemblies. Você pode redirecionar seu aplicativo para usar uma versão diferente de um assembly de várias maneiras: por meio da política de editor, por meio de um arquivo de configuração de aplicativo; ou por meio do arquivo de configuração do computador.You can redirect your app to use a different version of an assembly in a number of ways: through publisher policy, through an app configuration file; or through the machine configuration file. Este artigo discute como a associação de assembly funciona no .NET Framework e como ela pode ser configurada.This article discusses how assembly binding works in the .NET Framework and how it can be configured.

Unificação de assembly e associação padrãoAssembly unification and default binding

Associações a .NET Framework assemblies são, às vezes, redirecionadas por meio de um processo chamado Unificação de assembly.Bindings to .NET Framework assemblies are sometimes redirected through a process called assembly unification. O .NET Framework consiste em uma versão do Common Language Runtime e cerca de duas dúzias de .NET Framework assemblies que compõem a biblioteca de tipos.The .NET Framework consists of a version of the common language runtime and about two dozen .NET Framework assemblies that make up the type library. Esses .NET Framework assemblies são tratados pelo tempo de execução como uma única unidade.These .NET Framework assemblies are treated by the runtime as a single unit. Por padrão, quando um aplicativo é iniciado, todas as referências a tipos no código são executadas pelo tempo de execução são direcionadas para .NET Framework assemblies que têm o mesmo número de versão que o tempo de execução que é carregado em um processo.By default, when an app is launched, all references to types in code run by the runtime are directed to .NET Framework assemblies that have the same version number as the runtime that is loaded in a process. Os redirecionamentos que ocorrem com esse modelo são o comportamento padrão para o tempo de execução.The redirections that occur with this model are the default behavior for the runtime.

Por exemplo, se seu aplicativo referencia 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 que é fornecido com a versão de tempo de execução 4,5.For example, if your app references types in the System.XML namespace and was built by using the .NET Framework 4.5, it contains static references to the System.XML assembly that ships with runtime version 4.5. Se você quiser redirecionar a referência de associação para apontar para o System.XML assembly que acompanha o .NET Framework 4, você pode colocar as informações de redirecionamento no arquivo de configuração do aplicativo.If you want to redirect the binding reference to point to the System.XML assembly that ship with the .NET Framework 4, you can put redirect information in the app configuration file. Um redirecionamento de associação em um arquivo de configuração para um assembly de .NET Framework unificado cancela a unificação desse assembly.A binding redirection in a configuration file for a unified .NET Framework assembly cancels the unification for that 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.In addition, you may want to manually redirect assembly binding for third-party assemblies if there are multiple versions available.

Redirecionando versões de assembly usando a política do PublicadorRedirecting assembly versions by using publisher policy

Os fornecedores de assemblies podem direcionar aplicativos para uma versão mais recente de um assembly, incluindo um arquivo de política do Publicador com o novo assembly.Vendors of assemblies can direct apps to a newer version of an assembly by including a publisher policy file with the new assembly. O arquivo de política do Publicador, localizado no cache de assembly global, contém configurações de redirecionamento de assembly.The publisher policy file, which is located in the global assembly cache, contains assembly redirection settings.

Cada uma das principais. a versão secundária de um assembly tem seu próprio arquivo de política de editor.Each major.minor version of an assembly has its own publisher policy file. 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, pois eles estão associados à versão 2,0.For example, redirections from version 2.0.2.222 to 2.0.3.000 and from version 2.0.2.321 to version 2.0.3.000 both go into the same file, because they are associated with version 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.However, a redirection from version 3.0.0.999 to version 4.0.0.000 goes into the file for version 3.0.999. Cada versão principal do .NET Framework tem seu próprio arquivo de política de editor.Each major version of the .NET Framework has its own publisher policy file.

Se um arquivo de política do Publicador existir 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.If a publisher policy file exists for an assembly, the runtime checks this file after checking the assembly's manifest and app configuration file. Os fornecedores devem usar arquivos de política do Publicador somente quando o novo assembly for compatível com versões anteriores com o assembly sendo redirecionado.Vendors should use publisher policy files only when the new assembly is backward compatible with the assembly being redirected.

Você pode ignorar a política do Publicador 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.You can bypass publisher policy for your app by specifying settings in the app configuration file, as discussed in the Bypassing publisher policy section.

Redirecionando versões de assembly no nível do aplicativoRedirecting assembly versions at the app level

Há algumas técnicas diferentes para alterar o comportamento de associação para seu aplicativo por meio do arquivo de configuração de aplicativo: você pode editar o arquivo manualmente, você pode contar com o redirecionamento de associação automática ou pode especificar o comportamento de associação ignorando a política do Publicador.There are a few different techniques for changing the binding behavior for your app through the app configuration file: you can manually edit the file, you can rely on automatic binding redirection, or you can specify binding behavior by bypassing publisher policy.

Editando manualmente o arquivo de configuração do aplicativoManually editing the app config file

Você pode editar manualmente o arquivo de configuração de aplicativo para resolver problemas de assembly.You can manually edit the app configuration file to resolve assembly issues. Por exemplo, se um fornecedor puder liberar uma versão mais recente de um assembly que seu aplicativo usa sem fornecer uma política de Publicador, porque eles não garantem a 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 da seguinte maneira.For example, if a vendor might release a newer version of an assembly that your app uses without supplying a publisher policy, because they do not guarantee backward compatibility, you can direct your app to use the newer version of the assembly by putting assembly binding information in your app's configuration file as follows.

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

Contando com o redirecionamento de associação automáticaRelying on automatic binding redirection

Quando você cria um aplicativo de área de trabalho no Visual Studio que tem como alvo o .NET Framework 4.5.1 ou uma versão posterior, o aplicativo usa o redirecionamento de associação automática.When you create a desktop app in Visual Studio that targets the .NET Framework 4.5.1 or a later version, the app uses automatic binding redirection. 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 associação à versão mais recente do assembly no arquivo de configuração do aplicativo de saída (app.config).This means that if two components reference different versions of the same strong-named assembly, the runtime automatically adds a binding redirection to the newer version of the assembly in the output app configuration (app.config) file. Esse redirecionamento substitui a Unificação de assembly que, de outra forma, poderia ocorrer.This redirection overrides the assembly unification that might otherwise take place. O arquivo de origem app.config não é modificado.The source app.config file is not modified. Por exemplo, digamos que seu aplicativo faça referência diretamente a um componente de .NET Framework fora de banda, mas usa uma biblioteca de terceiros que se destina a uma versão mais antiga do mesmo componente.For example, let's say that your app directly references an out-of-band .NET Framework component but uses a third-party library that targets an older version of the same component. Quando você compila o aplicativo, o arquivo de configuração do aplicativo de saída é modificado para conter um redirecionamento de associação para a versão mais recente do componente.When you compile the app, the output app configuration file is modified to contain a binding redirection to the newer version of the component. Se você criar um aplicativo Web, receberá um aviso de compilação sobre o conflito de associação que, por sua vez, oferecerá a opção de adicionar o redirecionamento de associação necessário ao arquivo de configuração da Web de origem.If you create a web app, you receive a build warning regarding the binding conflict, which in turn, gives you the option to add the necessary binding redirect to the source web configuration file.

Se você adicionar manualmente os redirecionamentos de associação ao arquivo de app.config de origem, no momento da compilação, o Visual Studio tentará unificar os assemblies com base nos redirecionamentos de associação adicionados.If you manually add binding redirects to the source app.config file, at compile time, Visual Studio tries to unify the assemblies based on the binding redirects you added. Por exemplo, digamos que você insira o redirecionamento de associação a seguir para um assembly:For example, let's say you insert the following binding redirect for an 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 app.config de saída para que o aplicativo seja unificado na versão 2.0.0.0 deste assembly:If another project in your app references version 1.0.0.0 of the same assembly, automatic binding redirection adds the following entry to the output app.config file so that the app is unified on version 2.0.0.0 of this assembly:

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

Você pode habilitar o redirecionamento de associação automática se seu aplicativo for destinado a versões mais antigas do .NET Framework.You can enable automatic binding redirection if your app targets older versions of the .NET Framework. Você pode substituir esse comportamento padrão fornecendo informações de redirecionamento de associação no arquivo de app.config para qualquer assembly ou desativando o recurso de redirecionamento de associação.You can override this default behavior by providing binding redirection information in the app.config file for any assembly, or by turning off the binding redirection feature. Para obter informações sobre como ativar ou desativar esse recurso, consulte como habilitar e desabilitar o redirecionamento de associação automática.For information about how to turn this feature on or off, see How to: Enable and Disable Automatic Binding Redirection.

Ignorando a política do PublicadorBypassing publisher policy

Você pode substituir a política do Publicador no arquivo de configuração do aplicativo, se necessário.You can override publisher policy in the app configuration file if necessary. Por exemplo, novas versões de assemblies que alegam ser compatíveis com versões anteriores ainda podem interromper um aplicativo.For example, new versions of assemblies that claim to be backward compatible can still break an app. Se você quiser ignorar a política do Publicador, adicione um <publisherPolicy> elemento ao <dependentAssembly> elemento no arquivo de configuração do aplicativo e defina o atributo Apply como não, que substitui as configurações Sim anteriores.If you want to bypass publisher policy, add a <publisherPolicy> element to the <dependentAssembly> element in the app configuration file, and set the apply attribute to no, which overrides any previous yes settings.

<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 para o fornecedor do assembly.Bypass publisher policy to keep your app running for your users, but make sure you report the problem to the assembly vendor. Se um assembly tiver um arquivo de política do Publicador, o fornecedor deverá garantir que o assembly seja compatível com versões anteriores e que os clientes possam usar a nova versão o máximo possível.If an assembly has a publisher policy file, the vendor should make sure that the assembly is backward compatible and that clients can use the new version as much as possible.

Redirecionando versões de assembly no nível do computadorRedirecting assembly versions at the machine level

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.There might be rare cases when a machine administrator wants all apps on a computer to use a specific version of an assembly. Por exemplo, o administrador pode querer que todos os aplicativos usem uma versão de assembly específica, pois essa versão corrige uma brecha de segurança.For example, the administrator might want every app to use a particular assembly version, because that version fixes a security hole. Se um assembly for redirecionado no arquivo de configuração da máquina, todos os aplicativos nesse computador que usam a versão antiga serão direcionados para usar a nova versão.If an assembly is redirected in the machine's configuration file, all apps on that machine that use the old version will be directed to use the new version. O arquivo de configuração do computador substitui o arquivo de configuração do aplicativo e o arquivo de política do Publicador.The machine configuration file overrides the app configuration file and the publisher policy file. Esse arquivo está localizado no diretório %runtime install path%\Config.This file is located in the %runtime install path%\Config directory. Normalmente, o .NET Framework é instalado no diretório%drive%\Windows\Microsoft.NET\FrameworkTypically, the .NET Framework is installed in the %drive%\Windows\Microsoft.NET\Framework directory.

Especificando a associação de assembly em arquivos de configuraçãoSpecifying assembly binding in configuration files

Você usa o mesmo formato XML para especificar redirecionamentos de associação, seja no arquivo de configuração do aplicativo, no arquivo de configuração do computador ou no arquivo de política do Publicador.You use the same XML format to specify binding redirects whether it’s in the app configuration file, the machine configuration file, or the publisher policy file. Para redirecionar uma versão de assembly para outra, use o <bindingRedirect> elemento.To redirect one assembly version to another, use the <bindingRedirect> element. O atributo OldVersion pode especificar uma única versão de assembly ou um intervalo de versões.The oldVersion attribute can specify a single assembly version or a range of versions. O newVersion atributo deve especificar uma única versão.The newVersion attribute should specify a single version. 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.For example, <bindingRedirect oldVersion="1.1.0.0-1.2.0.0" newVersion="2.0.0.0"/> specifies that the runtime should use version 2.0.0.0 instead of the assembly versions between 1.1.0.0 and 1.2.0.0.

O exemplo de código a seguir demonstra uma variedade de cenários de redirecionamento de associação.The following code example demonstrates a variety of binding redirect scenarios. O exemplo especifica um redirecionamento para um intervalo de versões para myAssembly , e um único redirecionamento de associação para mySecondAssembly .The example specifies a redirect for a range of versions for myAssembly, and a single binding redirect for mySecondAssembly. O exemplo também especifica que o arquivo de política do Publicador não substituirá os redirecionamentos de associação para myThirdAssembly .The example also specifies that publisher policy file will not override the binding redirects for myThirdAssembly.

Para associar um assembly, você deve especificar a cadeia de caracteres "urn: schemas-microsoft-com: asm. v1" com o atributo xmlns na <assemblyBinding> marca.To bind an assembly, you must specify the string "urn:schemas-microsoft-com:asm.v1" with the xmlns attribute in the <assemblyBinding> tag.

<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>

Limitando associações de assembly a uma versão específicaLimiting assembly bindings to a specific version

Você pode usar o atributo AppliesTo no <assemblyBinding> elemento em um arquivo de configuração de aplicativo para redirecionar referências de associação de assembly para uma versão específica do .NET Framework.You can use the appliesTo attribute on the <assemblyBinding> element in an app configuration file to redirect assembly binding references to a specific version of the .NET Framework. Esse atributo opcional usa um número de versão .NET Framework para indicar a qual versão ele se aplica.This optional attribute uses a .NET Framework version number to indicate what version it applies to. Se nenhum atributo AppliesTo for especificado, o <assemblyBinding> elemento se aplicará a todas as versões do .NET Framework.If no appliesTo attribute is specified, the <assemblyBinding> element applies to all versions of the .NET Framework.

Por exemplo, para redirecionar a associação de assembly para um assembly .NET Framework 3,5, você incluiria o seguinte código XML em seu arquivo de configuração de aplicativo.For example, to redirect assembly binding for a .NET Framework 3.5 assembly, you would include the following XML code in your app configuration file.

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

Você deve inserir informações de redirecionamento na ordem de versão.You should enter redirection information in version order. Por exemplo, insira informações de redirecionamento de associação de assembly para assemblies .NET Framework 3,5 seguidos por assemblies de .NET Framework 4,5.For example, enter assembly binding redirection information for .NET Framework 3.5 assemblies followed by .NET Framework 4.5 assemblies. 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.Finally, enter assembly binding redirection information for any .NET Framework assembly redirection that does not use the appliesTo attribute and therefore applies to all versions of the .NET Framework. Se houver um conflito no redirecionamento, a primeira instrução de redirecionamento correspondente no arquivo de configuração será usada.If there is a conflict in redirection, the first matching redirection statement in the configuration file is used.

Por exemplo, para redirecionar uma referência a um assembly .NET Framework 3,5 e outra referência a um assembly .NET Framework 4, use o padrão mostrado no pseudocódigo a seguir.For example, to redirect one reference to a .NET Framework 3.5 assembly and another reference to a .NET Framework 4 assembly, use the pattern shown in the following pseudocode.

<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>

Confira tambémSee also