Redireccionamiento de versiones de ensamblado

Puede redirigir las referencias de enlace en tiempo de compilación hacia ensamblados del .NET Framework, ensamblados de terceros o ensamblados de su propia aplicación. Puede redirigir la aplicación para que use una versión diferente de un ensamblado de varias maneras: a través de la directiva de publicador, a través de un archivo de configuración de aplicaciones o a través del archivo de configuración de la máquina. En este artículo se describe cómo funciona el enlace de ensamblados en .NET Framework y cómo puede configurarlo.

Unificación de ensamblados y enlace predeterminado

A veces, los enlaces a ensamblados de .NET Framework se redirigen a través de un proceso denominado assembly unification. .NET Framework consta de una versión de Common Language Runtime y aproximadamente dos docenas de ensamblados de .NET Framework que componen la biblioteca de tipos. Estos ensamblados de .NET Framework se tratan en tiempo de ejecución como una sola unidad. De forma predeterminada, cuando se inicia una aplicación, todas las referencias a los tipos en el código ejecutado por el entorno de ejecución se dirigen a los ensamblados del Framework .NET que tienen el mismo número de versión que el entorno de ejecución cargado en un proceso. Las redirecciones que se producen con este modelo son el comportamiento predeterminado para el tiempo de ejecución.

Por ejemplo, si la aplicación hace referencia a tipos en el espacio de nombres System.XML y se creó mediante .NET Framework 4.5, contiene referencias estáticas al ensamblado de System.XML que se incluye con la versión 4.5 del entorno de ejecución. Si desea redirigir la referencia de enlace para que apunte al ensamblado de System.XML que se incluye con .NET Framework 4, puede colocar información de redirección en el archivo de configuración de la aplicación. Un redireccionamiento de enlace en un archivo de configuración para un ensamblado unificado de .NET Framework cancela la unificación de ese ensamblado.

Además, puede que quiera redirigir manualmente el enlace de ensamblados para ensamblados de terceros si hay varias versiones disponibles.

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

Redirección de versiones mediante la directiva de edición

Los proveedores de ensamblados pueden dirigir las aplicaciones a una versión más reciente de un ensamblado mediante la inclusión de un archivo de directiva de publicador con el nuevo ensamblado. El archivo de directivas de edición, que se encuentra en la caché global de ensamblados, contiene valores de redirección de ensamblados.

Cada versión mayor.menor de un ensamblado tiene su propio archivo de política del publicador. Por ejemplo, los redireccionamientos de la versión 2.0.2.222 a 2.0.3.000 y de la versión 2.0.2.321 a la versión 2.0.3.000 entran en el mismo archivo, ya que están asociados a la versión 2.0. Sin embargo, una redirección de la versión 3.0.0.999 a la versión 4.0.0.000 va en el archivo de la versión 3.0.999. Cada versión principal de .NET Framework tiene su propio archivo de directiva de publicador.

Si existe un archivo de directiva de publicador para un ensamblado, el runtime comprueba este archivo después de comprobar el manifiesto del ensamblado y el archivo de configuración de la aplicación. Los proveedores deben usar los archivos de directiva de edición cuando el nuevo ensamblado sea compatible con la versión anterior del ensamblado que se redirige.

Puede omitir la directiva de publicador de la aplicación especificando la configuración en el archivo de configuración de la aplicación, como se describe en la sección Omitir directiva de publicador .

Redirigir versiones en el nivel de aplicación

Hay algunas técnicas diferentes para cambiar el comportamiento de enlace de la aplicación a través del archivo de configuración de la aplicación: puedes editar manualmente el archivo, puedes confiar en el redireccionamiento automático de enlaces, o puedes especificar el comportamiento de enlace pasando la directiva de editor.

Editar manualmente el archivo de configuración de la aplicación

Puede editar manualmente el archivo de configuración de la aplicación para resolver problemas de ensamblado. Por ejemplo, si un proveedor publica una versión más reciente de un ensamblado que usa la aplicación sin proporcionar una directiva de publicador (porque no garantizan la compatibilidad con versiones anteriores), puede dirigir a la aplicación para que use la versión más reciente del ensamblado colocando información de enlace de ensamblado en el archivo de configuración de la aplicación de la siguiente manera.

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

Confiar en una redirección de enlace automática

Al crear una aplicación de escritorio en Visual Studio que tenga como destino .NET Framework 4.5.1 o una versión posterior, la aplicación usa el redireccionamiento automático de enlaces. Esto significa que si dos componentes hacen referencia a versiones diferentes del mismo ensamblado con nombre seguro, el runtime agrega automáticamente una redirección de enlace a la versión más reciente del ensamblado en el archivo de configuración de la aplicación de salida (app.config). Esta redirección invalida la unificación de ensamblados que, de lo contrario, puede tener lugar. El archivo app.config de origen no se modifica. Por ejemplo, supongamos que la aplicación hace referencia directamente a un componente fuera de banda .NET Framework, pero usa una biblioteca de terceros destinada a una versión anterior del mismo componente. Al compilar la aplicación, el archivo de configuración de la aplicación de salida se modifica para contener una redirección de enlace a la versión más reciente del componente.

Si crea una aplicación web, recibirá una advertencia de compilación sobre el conflicto de enlace, que, a su vez, le ofrece la opción de agregar la redirección de enlace necesaria al archivo de configuración web de origen.

Si agrega manualmente redirecciones de enlace al archivo de app.config de origen, en tiempo de compilación, Visual Studio intenta unificar los ensamblados en función de las redirecciones de enlace que agregó. Por ejemplo, supongamos que inserta la siguiente redirección de enlace para un ensamblado:

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

Si otro proyecto de la aplicación hace referencia a la versión 1.0.0.0 del mismo ensamblado, el redireccionamiento automático de enlaces agrega la siguiente entrada al archivo de salida app.config para que la aplicación esté unificada en la versión 2.0.0.0 de este ensamblado:

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

Puede habilitar el redireccionamiento automático de enlaces si la aplicación tiene como destino versiones anteriores de .NET Framework. Puede invalidar este comportamiento predeterminado proporcionando información de redirección de enlace en el archivo app.config para cualquier ensamblado o desactivando la característica de redirección de enlaces. Para obtener información sobre cómo activar o desactivar esta característica, vea Cómo: Habilitar y deshabilitar el redireccionamiento automático de enlaces.

Omitir directiva de publicador

Si es necesario, puede invalidar la directiva de publicador en el archivo de configuración de la aplicación. Por ejemplo, las nuevas versiones de ensamblajes que afirman ser compatibles con versiones anteriores aún pueden romper una aplicación. Si desea omitir la directiva de publicador, agregue un elemento publisherPolicy al elemento dependentAssembly en el archivo de configuración de la aplicación, y establezca el atributo en , lo que invalidará cualquier configuración anterior .

<publisherPolicy apply="no" />

Omita la directiva de edición para mantener la aplicación en ejecución para sus usuarios, pero asegúrese de que informa del problema al proveedor del ensamblado. Si un ensamblado tiene un archivo de directiva de publicador, el proveedor debe asegurarse de que el ensamblado es compatible con versiones anteriores y que los clientes pueden usar la nueva versión tanto como sea posible.

Redirección de versiones para pruebas, complementos o bibliotecas usadas por otro componente

Para las pruebas, debe generar un archivo .dll.config . La mayoría de los marcos de pruebas unitarias existentes respetan estos archivos al cargar pruebas.

Los complementos pueden respetar .dll.config archivos, sin embargo, también podrían no. El único mecanismo a prueba de errores para redireccionamientos es proporcionar cuando se crea .

Puede intentar resolver este problema con manejadores de eventos, pero eso no funciona, ya que únicamente se llama a esos manejadores en un error de carga. Si una carga de ensamblado se realiza correctamente, ya sea porque la cargó otro ensamblado o el host, o porque estaba presente en la GAC, no se llamará a un controlador de .

Generación de redirecciones de enlace para proyectos de prueba unitaria

Los proyectos de prueba unitaria se compilan en archivos DLL, no en ejecutables. La generación automática de redirección de enlaces solo se aplica a los tipos de salida ejecutables, por lo que los proyectos de prueba unitaria no reciben redireccionamientos de enlace de forma predeterminada. Cuando un proyecto de prueba unitaria hace referencia a ensamblados que tienen versiones en conflicto, las pruebas pueden producir errores en tiempo de ejecución con excepciones como .

Para generar un archivo de.dll.config con redirecciones de enlace para un proyecto de prueba unitaria, agregue y al archivo de proyecto:

<PropertyGroup>
  <AutoGenerateBindingRedirects>true</AutoGenerateBindingRedirects>
  <GenerateBindingRedirectsOutputType>true</GenerateBindingRedirectsOutputType>
</PropertyGroup>

La propiedad indica a MSBuild que genere un archivo .dll.config junto con la salida del ensamblado de prueba, aunque el tipo de salida sea una biblioteca de clases (DLL). La mayoría de los ejecutores de pruebas, incluido VSTest, cargan este archivo de configuración al ejecutar pruebas.

Después de agregar estas propiedades y volver a generar el proyecto, compruebe que aparece un archivo .dll.config en el directorio de salida de compilación junto al ensamblado de prueba. El archivo contiene las redirecciones de enlace necesarias para resolver conflictos de versión de ensamblaje en tiempo de ejecución de las pruebas.

Redirección de versiones en el nivel de máquina

Es posible que haya casos excepcionales cuando un administrador de máquinas quiere que todas las aplicaciones de un equipo usen una versión específica de un ensamblado. Por ejemplo, una versión específica podría corregir un agujero de seguridad. Si se redirige un ensamblado en el archivo de configuración del equipo, denominado machine.config, todas las aplicaciones de esa máquina que usan la versión anterior se dirigen para usar la nueva versión. El archivo de configuración de la máquina invalida el archivo de configuración de la aplicación y el archivo de directiva de publicador. Este archivo machine.config se encuentra en %windir%\Microsoft.NET\Framework[version]\config\machine.config para máquinas de 32 bits o %windir%\Microsoft.NET\Framework64[version]\config\machine.config para máquinas de 64 bits.

Especificación del enlace de ensamblados en archivos de configuración

Use el mismo formato XML para especificar redirecciones de enlace si se encuentra en el archivo de configuración de la aplicación, el archivo de configuración del equipo o el archivo de directiva de edición. Para redirigir una versión de ensamblado a otra, use el elemento bindingRedirect . El atributo puede especificar una sola versión de ensamblado o un intervalo de versiones. El atributo debe especificar una sola versión. Por ejemplo, especifica que el entorno de ejecución debe usar la versión 2.0.0.0 en lugar de las versiones del ensamblado entre 1.1.0.0 y 1.2.0.0.

En el ejemplo de código siguiente se muestra una variedad de escenarios de redirección de enlace. En el ejemplo se especifica un redireccionamiento para un intervalo de versiones para y un único redireccionamiento de enlace para . En el ejemplo también se especifica que dicho archivo de directiva de edición no invalidará las redirecciones de enlace para .

Para enlazar un ensamblado, debe especificar la cadena "urn:schemas-microsoft-com:asm.v1" en el atributo de la etiqueta 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 los enlaces de ensamblado a una versión específica

Puede usar el atributo appliesTo en el elemento <assemblyBinding> en un archivo de configuración de la aplicación para redirigir las referencias de enlace de ensamblado a una versión específica de .NET Framework. Este atributo opcional usa un número de versión de .NET Framework para indicar a qué versión se aplica. Si no se especifica ningún atributo appliesTo, el elemento <assemblyBinding> se aplica a todas las versiones de .NET Framework.

Por ejemplo, para redirigir el enlace de ensamblado para un ensamblado de .NET Framework 3.5, deberías incluir el siguiente código XML en el archivo de configuración de la aplicación.

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

Debe escribir la información de redireccionamiento en orden de versión. Por ejemplo, escriba la información de redirección de enlace de ensamblado para los ensamblados de .NET Framework 3.5 seguidos de los ensamblados de .NET Framework 4.5. Por último, escriba la información de redirección de ensamblaje para cualquier redirección del .NET Framework que no use el atributo appliesTo y, por tanto, se aplica a todas las versiones de .NET Framework. Si hay un conflicto en el redireccionamiento, se usa la primera instrucción de redirección coincidente en el archivo de configuración.

Por ejemplo, para redirigir una referencia a un ensamblado de .NET Framework 3.5 y otra referencia a un ensamblado de .NET Framework 4, use el patrón que se muestra en el pseudocódigo siguiente.

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

Consulte también

• Procedimiento: Habilitación y deshabilitación del redireccionamiento de enlaces automático
• Elemento
• Permiso de seguridad para el redireccionamiento de enlaces de ensamblados
• Assemblies en .NET
• Programación con ensamblados
• Cómo el entorno de ejecución localiza ensamblajes
• Configurar aplicaciones
• Esquema de configuración en tiempo de ejecución
• Esquema de Archivo de Configuración
• Cómo crear una política de publicador