Compartir a través de

Cómo el motor en tiempo de ejecución ubica ensamblados

Nota:

Este artículo es específico de .NET Framework. No se aplica a implementaciones más recientes de .NET, incluidas .NET 6 y versiones posteriores.

Para implementar correctamente la aplicación de .NET Framework, debe comprender cómo Common Language Runtime localiza y enlaza a los ensamblados que componen la aplicación. De forma predeterminada, el tiempo de ejecución intenta enlazar con la versión exacta de un ensamblado con el que se creó la aplicación. Este comportamiento predeterminado se puede invalidar mediante la configuración del archivo de configuración.

Common Language Runtime realiza una serie de pasos al intentar localizar un ensamblado y resolver una referencia de ensamblado. Cada paso se explica en las secciones siguientes. El término sondeo se usa a menudo al describir cómo el tiempo de ejecución localiza ensamblados; hace referencia al conjunto de heurísticas que se usa para localizar el ensamblado en función de su nombre y cultura.

Nota:

Puede ver la información de enlace en el archivo de registro mediante el Assembly Binding Log Viewer (Fuslogvw.exe), que se incluye en el SDK de Windows.

Iniciar el enlace

El proceso de localización y enlace a un ensamblado comienza cuando el tiempo de ejecución intenta resolver una referencia a otro ensamblado. Esta referencia puede ser estática o dinámica. El compilador registra referencias estáticas en los metadatos del manifiesto de ensamblado en tiempo de compilación. Las referencias dinámicas se construyen sobre la marcha como resultado de llamar a varios métodos, como Assembly.Load.

La manera preferida de hacer referencia a un ensamblado es usar una referencia completa, incluido el nombre del ensamblado, la versión, la referencia cultural y el token de clave pública (si existe alguno). El tiempo de ejecución usa esta información para localizar el ensamblado, siguiendo los pasos descritos más adelante en esta sección. El tiempo de ejecución usa el mismo proceso de resolución, independientemente de si la referencia es para un ensamblado estático o dinámico.

También puede hacer una referencia dinámica a un ensamblado proporcionando al método de llamada solo información parcial sobre el ensamblado, como especificar solo el nombre del ensamblado. En este caso, solo se busca el directorio de la aplicación para el ensamblado y no se produce ninguna otra comprobación. Se hace una referencia parcial mediante cualquiera de los diversos métodos para cargar ensamblados, como Assembly.Load o AppDomain.Load.

Por último, puede hacer una referencia dinámica mediante un método como Assembly.Load y proporcionar solo información parcial; a continuación, calificará la referencia mediante el <elemento qualifyAssembly> en el archivo de configuración de la aplicación. Este elemento permite proporcionar la información de referencia completa (nombre, versión, referencia cultural y, si procede, el token de clave pública) en el archivo de configuración de la aplicación en lugar de en el código. Usaría esta técnica si quisiera calificar por completo una referencia a un ensamblado fuera del directorio de la aplicación, o si quisiera hacer referencia a un ensamblado en la caché global de ensamblados, pero quería la comodidad de especificar la referencia completa en el archivo de configuración en lugar de en el código.

Nota:

Este tipo de referencia parcial no debe usarse con ensamblados que se comparten entre varias aplicaciones. Dado que las opciones de configuración se aplican por aplicación y no por ensamblado, un ensamblado compartido que use este tipo de referencia parcial requeriría que cada aplicación que use el ensamblado compartido tenga la información apta en su archivo de configuración.

El tiempo de ejecución usa los pasos siguientes para resolver una referencia de ensamblado:

  1. Determina la versión correcta del ensamblado mediante el examen de los archivos de configuración aplicables, incluido el archivo de configuración de la aplicación, el archivo de directiva de publicador y el archivo de configuración de la máquina. Si el archivo de configuración se encuentra en una máquina remota, el entorno de ejecución debe localizar y descargar primero el archivo de configuración de la aplicación.

  2. Comprueba si el nombre del ensamblado se ha enlazado antes y, si es así, utiliza el ensamblado cargado previamente. Si se produjo un error en una solicitud anterior para cargar el ensamblado, la solicitud no se pudo realizar inmediatamente sin intentar cargar el ensamblado.

    Nota:

    El almacenamiento en caché de errores de enlace de ensamblado es nuevo en .NET Framework versión 2.0.

  3. Comprueba la caché global de ensamblados. Si el ensamblado se encuentra allí, el tiempo de ejecución usa este ensamblado.

  4. Sondea el ensamblado mediante los pasos siguientes:

    1. Si la directiva de configuración y edición no afecta a la referencia original y si la solicitud de enlace se creó usando el método Assembly.LoadFrom , el tiempo de ejecución comprueba las sugerencias de ubicación.

    2. Si se encuentra un código base en los archivos de configuración, el tiempo de ejecución solo comprueba esta ubicación. Si se produce un error en este sondeo, el tiempo de ejecución determina que se produjo un error en la solicitud de enlace y no se produce ningún otro sondeo.

    3. Sondea el ensamblado mediante la heurística descrita en la sección de sondeo. Si el ensamblado no se encuentra después de realizar la búsqueda, el entorno de ejecución solicita a Windows Installer que proporcione el ensamblado. Esto actúa como una característica de instalación a petición.

      Nota:

      No se produce ninguna comprobación de versión en busca de ensamblados sin nombres seguros, y el tiempo de ejecución no protege la caché global de ensamblados para los ensamblados sin nombres seguros.

Paso 1: Examinar los archivos de configuración

El comportamiento del enlace de ensamblados se puede configurar en distintos niveles en función de tres archivos XML.

  • Archivo de configuración de la aplicación.

  • Archivo de directiva de edición.

  • Archivo de configuración de la máquina.

Estos archivos siguen la misma sintaxis y proporcionan información como redireccionamientos de enlace, la ubicación del código y los modos de enlace para ensamblados concretos. Cada archivo de configuración puede contener un <elemento assemblyBinding> que redirige el proceso de enlace. Los elementos secundarios del elemento <assemblyBinding> incluyen el elemento <dependentAssembly>. Los elementos secundarios del elemento <dependentAssembly> incluyen el elemento <assemblyIdentity>, el elemento <bindingRedirect> y el elemento <codeBase>.

Nota:

La información de configuración se puede encontrar en los tres archivos de configuración; no todos los elementos son válidos en todos los archivos de configuración. Por ejemplo, el modo de enlace y la información de la ruta de acceso privada solo pueden estar en el archivo de configuración de la aplicación. Para obtener una lista completa de la información contenida en cada archivo, vea Configurar aplicaciones mediante archivos de configuración.

Archivo de configuración de aplicación

En primer lugar, Common Language Runtime comprueba el archivo de configuración de la aplicación en busca de información que reemplace la información de versión almacenada en el manifiesto del ensamblado que realiza la llamada. El archivo de configuración de la aplicación se puede implementar con una aplicación, pero no es necesario para la ejecución de la aplicación. Normalmente, la recuperación de este archivo es casi instantánea, pero en situaciones en las que la base de la aplicación se encuentra en un equipo remoto, como en un escenario basado en web, se debe descargar el archivo de configuración.

En el caso de los ejecutables cliente, el archivo de configuración de la aplicación reside en el mismo directorio que el ejecutable de la aplicación y tiene el mismo nombre base que el ejecutable con una extensión .config. Por ejemplo, el archivo de configuración de C:\Program Files\Myapp\Myapp.exe es C:\Program Files\Myapp\Myapp.exe.config. En un escenario basado en explorador, el archivo HTML debe usar el <elemento link> para apuntar explícitamente al archivo de configuración.

El código siguiente proporciona un ejemplo sencillo de un archivo de configuración de aplicación. En este ejemplo se agrega un TextWriterTraceListener a la colección Listeners para habilitar la grabación de información de depuración en un archivo.

<configuration>
   <system.diagnostics>
      <trace useGlobalLock="false" autoflush="true" indentsize="0">
         <listeners>
            <add name="myListener" type="System.Diagnostics.TextWriterTraceListener, system version=1.0.3300.0, Culture=neutral, PublicKeyToken=b77a5c561934e089" initializeData="c:\myListener.log" />
         </listeners>
      </trace>
   </system.diagnostics>
</configuration>

Archivo de directiva de edición

En segundo lugar, el tiempo de ejecución examina el archivo de directivas del publicador, si existe uno. Los archivos de directiva de edición se distribuyen mediante un editor de componentes como una corrección o actualización de un componente compartido. Estos archivos contienen información de compatibilidad emitida por el publicador del componente compartido que dirige una referencia de ensamblado a una nueva versión. A diferencia de los archivos de configuración de la aplicación y del equipo, los archivos de directiva de edición están contenidos en su propio ensamblado, que debe instalarse en la caché global de ensamblados.

A continuación se muestra un ejemplo de un archivo de configuración de directiva de publicador:

<configuration>
    <runtime>
        <assemblyBinding xmlns="urn:schemas-microsoft-com:asm.v1">

            <dependentAssembly>
                <assemblyIdentity name="asm6" publicKeyToken="c0305c36380ba429" />
                <bindingRedirect oldVersion="3.0.0.0" newVersion="2.0.0.0"/>
            </dependentAssembly>

        </assemblyBinding>
    </runtime>
</configuration>

Para crear un ensamblado, puede usar la herramienta Al.exe (Assembly Linker) con un comando como el siguiente:

Al.exe /link:asm6.exe.config /out:policy.3.0.asm6.dll /keyfile: compatkey.dat /v:3.0.0.0

compatkey.dat es un archivo de clave de nombre fuerte. Este comando crea un ensamblado con nombre seguro que se puede colocar en la caché global de ensamblados.

Nota:

La directiva de publicador afecta a todas las aplicaciones que usan un componente compartido.

El archivo de configuración de directiva de publicador invalida la información de versión que procede de la aplicación (es decir, del manifiesto del ensamblado o del archivo de configuración de la aplicación). Si no hay ninguna instrucción en el archivo de configuración de la aplicación para redirigir la versión especificada en el manifiesto de ensamblado, el archivo de directiva de publicador invalida la versión especificada en el manifiesto de ensamblado. Sin embargo, si hay una instrucción de redireccionamiento en el archivo de configuración de la aplicación, la directiva de publicador invalida esa versión en lugar de la especificada en el manifiesto.

Un archivo de directiva de publicador se usa cuando se actualiza un componente compartido y todas las aplicaciones que usan ese componente deben recoger la nueva versión del componente compartido. La configuración del archivo de directiva de publicador invalida la configuración del archivo de configuración de la aplicación, a menos que el archivo de configuración de la aplicación aplique el modo seguro.

Modo seguro

Normalmente, los archivos de directiva de publicador se instalan explícitamente como parte de una actualización de service pack o programa. Si hay algún problema con el componente compartido actualizado, puede omitir las sobrescrituras en el archivo de directiva del publicador mediante el modo seguro. El modo seguro viene determinado por el <elemento publisherPolicy apply="yes|no"/> , ubicado solo en el archivo de configuración de la aplicación. Especifica si la información de configuración de directiva de edición debe quitarse del proceso de enlace.

El modo seguro se puede establecer para toda la aplicación o para ensamblados seleccionados. Es decir, puede desactivar la directiva para todos los ensamblados que componen la aplicación o activarla para algunos ensamblados, pero no para otros. Para aplicar de forma selectiva la directiva de publicador a ensamblados que componen una aplicación, establezca <publisherPolicy apply=no/> y especifique qué ensamblados desea que se vean afectados mediante el < elemento dependentAssembly>. Para aplicar la directiva de publicador a todos los ensamblados que componen la aplicación, establezca <publisherPolicy apply=no/> sin elementos de ensamblado dependientes. Para obtener más información sobre la configuración, consulte Configuración de aplicaciones mediante archivos de configuración.

Archivo de configuración de la máquina

En tercer lugar, el tiempo de ejecución examina el archivo de configuración de la máquina. Este archivo, denominado Machine.config, reside en el equipo local en el subdirectorio Config del directorio raíz donde está instalado el entorno de ejecución. Los administradores pueden usar este archivo para especificar restricciones de enlace de ensamblado que son locales para ese equipo. La configuración del archivo de configuración de la máquina tiene prioridad sobre todas las demás opciones de configuración; sin embargo, esto no significa que todas las opciones de configuración se deben colocar en este archivo. La versión determinada por el archivo de directiva de administrador es final y no se puede invalidar. Las redefiniciones especificadas en el archivo Machine.config afectan a todas las aplicaciones. Para obtener más información sobre los archivos de configuración, consulte Configuración de aplicaciones mediante archivos de configuración.

Paso 2: Comprobación de los ensamblados a los que se ha hecho referencia previamente

Si el ensamblado solicitado también se ha solicitado en llamadas anteriores, Common Language Runtime usa el ensamblado que ya está cargado. Esto puede tener ramificaciones al asignar nombres a ensamblados que componen una aplicación. Para obtener más información sobre cómo asignar nombres a ensamblados, vea Nombres de ensamblado.

Si una solicitud anterior para el ensamblado produjo un error, las solicitudes posteriores para el ensamblado producen un error inmediatamente sin intentar cargar el ensamblado. A partir de .NET Framework versión 2.0, los errores de enlace de ensamblado se almacenan en caché y la información almacenada en caché se usa para determinar si se intenta cargar el ensamblado.

Nota:

Para revertir al comportamiento de las versiones 1.0 y 1.1 de .NET Framework, que no almacenaban en caché los errores de enlace, incluya el elemento disableCachingBindingFailures< en el> archivo de configuración.

Paso 3: Comprobación de la Global Assembly Cache

Para los ensamblados con nombre seguro, el proceso de enlace continúa con la búsqueda en la caché global de ensamblados. La caché global de ensamblados almacena ensamblados que pueden usar varias aplicaciones en un equipo. Todos los ensamblados de la caché global de ensamblados deben tener nombres seguros.

Paso 4: Buscar el ensamblado a través de codebases o sondeos

Una vez determinada la versión correcta del ensamblado usando la información contenida en la referencia del ensamblado que realiza la llamada y en los archivos de configuración, y una vez protegida la caché global de ensamblados (solo para ensamblados con nombre seguro), Common Language Runtime intenta buscar el ensamblado. El proceso de localización de un ensamblado implica los pasos siguientes:

  1. Si se encuentra un <elemento codeBase> en el archivo de configuración de la aplicación, el tiempo de ejecución comprueba la ubicación especificada. Si se encuentra una coincidencia, ese ensamblaje se usa y no se realiza sondeo alguno. Si no se encuentra allí el ensamblaje, se produce un error en la solicitud de enlace.

  2. A continuación, el entorno de ejecución sondea el ensamblado al que se hace referencia mediante las reglas especificadas más adelante en esta sección.

Nota:

Si tiene varias versiones de un ensamblado en un directorio y desea hacer referencia a una versión determinada de ese ensamblado, debe usar el <elemento codeBase> en lugar del privatePath atributo del <elemento de sondeo> . Si usa el <elemento de sondeo> , el tiempo de ejecución deja de sondear la primera vez que encuentra un ensamblado que coincide con el nombre de ensamblado simple al que se hace referencia, tanto si es una coincidencia correcta como si no. Si es una coincidencia correcta, se usa dicho ensamblado. Si no es una coincidencia correcta, el sondeo se detiene y la vinculación falla.

Ubicar el ensamblado a través de bases de código

La información de código base se puede proporcionar mediante un <elemento codeBase> en un archivo de configuración. Este código base siempre se comprueba antes de que el tiempo de ejecución intente sondear el ensamblado al que se hace referencia. Si un archivo de directiva de publicador que contiene el redireccionamiento de versión final también contiene un <elemento codeBase> , ese <elemento codeBase> es el que se usa. Por ejemplo, si el archivo de configuración de la aplicación especifica un <elemento codeBase> y un archivo de directiva de publicador que reemplaza la información de la aplicación también especifica un <elemento codeBase, se usa el elemento codeBase><en el archivo de directiva de publicador.>

Si no se encuentra ninguna coincidencia en la ubicación especificada por el <elemento codeBase> , se produce un error en la solicitud de enlace y no se realizan pasos adicionales. Si el tiempo de ejecución determina que un ensamblado coincide con los criterios del ensamblado que realiza la llamada, usa ese ensamblado. Cuando se carga el archivo especificado por el elemento codeBase< especificado>, el entorno de ejecución comprueba que el nombre, la versión, la referencia cultural y la clave pública coincidan con la referencia del ensamblado que realiza la llamada.

Nota:

Los ensamblados a los que se hace referencia fuera del directorio raíz de la aplicación deben tener nombres seguros y deben instalarse en la caché global de ensamblados o especificarse mediante el <elemento codeBase> .

Ubicar el ensamblado a través del sondeo

Si no hay ningún <elemento codeBase> en el archivo de configuración de la aplicación, el entorno de ejecución sondea el ensamblado con cuatro criterios:

  • Base de la aplicación, que es la ubicación raíz donde se ejecuta la aplicación.

  • Cultura, que es el atributo de cultura del ensamblado al que se hace referencia.

  • Nombre, que es el nombre del ensamblado al que se hace referencia.

  • El atributo privatePath del <elemento de sondeo>, que es la lista de subdirectorios definida por el usuario en la ubicación raíz. Esta ubicación se puede especificar en el archivo de configuración de la aplicación y en código administrado mediante la AppDomainSetup.PrivateBinPath propiedad para un dominio de aplicación. Cuando se especifica en código administrado, primero se consulta el código privatePath administrado, seguido de la ruta de acceso especificada en el archivo de configuración de la aplicación.

Sondeo de las bases de aplicaciones y los directorios de referencia cultural

El tiempo de ejecución siempre comienza a sondear en la base de la aplicación, que puede ser una dirección URL o el directorio raíz de la aplicación en un equipo. Si el ensamblado al que se hace referencia no se encuentra en la base de la aplicación y no se proporciona información cultural, el tiempo de ejecución busca en cualquier subdirectorio con el nombre del ensamblado. Los directorios sondados incluyen:

  • [base de aplicación] / [nombre del ensamblado].dll

  • [base de la aplicación] / [nombre de ensamblado] / [nombre de ensamblado].dll

Si se especifica información cultural para el ensamblado referenciado, solo se analizan los siguientes directorios:

  • [base de la aplicación] / [referencia cultural] / [nombre de ensamblado].dll

  • [base de la aplicación] / [referencia cultural] / [nombre de ensamblado] / [nombre de ensamblado].dll

Sondeo con el atributo privatePath

Además de los subdirectorios de referencia cultural y los subdirectorios con el nombre del ensamblado al que se hace referencia, el tiempo de ejecución también sondea los directorios especificados mediante el atributo privatePath del elemento <probing>. Los directorios especificados mediante el privatePath atributo deben ser subdirectorios del directorio raíz de la aplicación. Los directorios sondeados varían en función de si se incluye información de referencia cultural en la solicitud del ensamblado al que se hace referencia.

El tiempo de ejecución deja de sondear la primera vez que encuentra un ensamblado que coincide con el nombre de ensamblado simple al que se hace referencia, ya sea una coincidencia correcta o no. Si es una coincidencia correcta, se usa dicho ensamblado. Si no es una coincidencia correcta, el sondeo se detiene y la vinculación falla.

Si se incluye la referencia cultural, se busca en los directorios siguientes:

  • [base de la aplicación] / [binpath] / [referencia cultural] / [nombre de ensamblado].dll

  • [base de la aplicación] / [binpath] / [referencia cultural] / [nombre de ensamblado] / [nombre de ensamblado].dll

Si no se incluye la información cultural, se exploran los directorios siguientes.

  • [base de la aplicación] / [binpath] / [nombre de ensamblado].dll

  • [base de la aplicación] / [binpath] / [nombre de ensamblado] / [nombre de ensamblado].dll

Ejemplos de sondeo

Dada la siguiente información:

  • Nombre del ensamblado al que se hace referencia: myAssembly

  • Directorio raíz de la aplicación: http://www.code.microsoft.com

  • El elemento <probing> del archivo de configuración especifica: bin

  • Referencia cultural: de

El entorno de ejecución sondea las siguientes direcciones URL:

  • http://www.code.microsoft.com/de/myAssembly.dll

  • http://www.code.microsoft.com/de/myAssembly/myAssembly.dll

  • http://www.code.microsoft.com/bin/de/myAssembly.dll

  • http://www.code.microsoft.com/bin/de/myAssembly/myAssembly.dll

Varios ensamblados con el mismo nombre

En el ejemplo siguiente se muestra cómo configurar varios ensamblados con el mismo nombre.

<dependentAssembly>
   <assemblyIdentity name="Server" publicKeyToken="c0305c36380ba429" />
   <codeBase version="1.0.0.0" href="v1/Server.dll" />
   <codeBase version="2.0.0.0" href="v2/Server.dll" />
</dependentAssembly>

Otras ubicaciones sondadas

La ubicación del ensamblado también se puede determinar mediante el contexto de enlace actual. Esto suele ocurrir cuando se usa el Assembly.LoadFrom método y en escenarios de interoperabilidad COM. Si un ensamblado usa el LoadFrom método para hacer referencia a otro ensamblado, la ubicación del ensamblado que realiza la llamada se considera una sugerencia sobre dónde encontrar el ensamblado al que se hace referencia. Si se encuentra una coincidencia, se carga dicho ensamblado. Si no se encuentra ninguna coincidencia, el tiempo de ejecución prosigue con la semántica de búsqueda y, a continuación, consulta a Windows Installer para proporcionar el ensamblado. Si no se proporciona ningún ensamblado que coincida con la solicitud de enlace, se produce una excepción. Esta excepción es un TypeLoadException en código administrado si se hizo referencia a un tipo, o un FileNotFoundException si no se encontró un ensamblado al intentar cargarlo.

Por ejemplo, si Assembly1 hace referencia a Assembly2 y Assembly1 se descargó de http://www.code.microsoft.com/utils, esa ubicación se considera una sugerencia sobre dónde encontrar Assembly2.dll. Después, el runtime busca el ensamblado en http://www.code.microsoft.com/utils/Assembly2.dll y http://www.code.microsoft.com/utils/Assembly2/Assembly2.dll. Si no se encuentra Assembly2 en ninguna de estas ubicaciones, el tiempo de ejecución consulta a Windows Installer.

Consulte también