CorBindToRuntimeEx (Función)

Artículo
05/10/2023

Permite a los hosts no administrados cargar Common Language Runtime (CLR) en un proceso. Las funciones CorBindToRuntime y CorBindToRuntimeEx realizan la misma operación, pero la función CorBindToRuntimeEx permite establecer marcas para especificar el comportamiento de CLR.

Esta función está en desuso en .NET Framework 4.

Esta función adopta una serie de parámetros que permiten a un host hacer lo siguiente:

Especificar la versión del runtime que se cargará.
Indicar si se debe cargar la compilación para servidor o para estación de trabajo.
Controlar si se realiza una recolección de elementos no utilizados simultánea o no simultánea.

Nota

No se admite la recolección de elementos no utilizados simultánea en aplicaciones en las que se ejecuta el emulador WOW64 x86 en sistemas de 64 bits y que implementan la arquitectura Intel Itanium (denominada anteriormente IA-64). Para obtener más información sobre el uso de WOW64 en sistemas Windows de 64 bits, vea la página de ejecución de aplicaciones de 32 bits.

Determinar si se cargan los ensamblados como neutrales con respecto al dominio.
Obtener un puntero de interfaz a ICorRuntimeHost que se puede usar para establecer opciones adicionales en la configuración de una instancia de CLR antes de que se inicie.

Sintaxis

HRESULT CorBindToRuntimeEx (  
    [in]  LPCWSTR      pwszVersion,
    [in]  LPCWSTR      pwszBuildFlavor,
    [in]  DWORD        startupFlags,
    [in]  REFCLSID     rclsid,
    [in]  REFIID       riid,
    [out] LPVOID FAR  *ppv  
);

Parámetros

pwszVersion
[in] Cadena que describe la versión de CLR que se desea cargar.

En .NET Framework, un número de versión consta de cuatro partes separadas por puntos: major.minor.build.revision. La cadena que se pasó como pwszVersion debe comenzar con el carácter "v" seguido de las primeras tres partes del número de versión (por ejemplo, "v1.0.1529").

Algunas versiones de CLR se instalan con una instrucción de directiva que especifica la compatibilidad con versiones anteriores de CLR. De forma predeterminada, el proceso intermedio ("shim") de inicio evalúa pwszVersion con las instrucciones de directiva y carga la versión más reciente del runtime compatible con la versión solicitada. Un host puede hacer que el proceso intermedio ("shim") omita la evaluación de directivas y cargue exactamente la versión especificada en pwszVersion, pasando el valor STARTUP_LOADER_SAFEMODE para el parámetro startupFlags, como se describe a continuación.

Si el llamador especifica null como valor de pwszVersion, CorBindToRuntimeEx identifica el conjunto de runtime instalados cuyos números de versión son inferiores al del runtime de .NET Framework 4, y carga la versión más reciente del runtime desde dicho conjunto. No cargará .NET Framework 4 ni versiones posteriores, y producirá un error si no hay ninguna versión anterior instalada. Tenga en cuenta que pasar NULL impide al host controlar la versión del runtime que se carga. Aunque este planteamiento puede ser apropiado en algunos escenarios, se recomienda encarecidamente que el host proponga cargar una versión específica.

pwszBuildFlavor
[in] Cadena que especifica si se debe cargar la compilación de CLR para servidor o para estación de trabajo. Los valores válidos son svr y wks. La compilación para servidor está optimizada para aprovechar las ventajas que aportan varios procesadores al realizar recolecciones de elementos no utilizados, mientras que la compilación para estación de trabajo está optimizada para aplicaciones cliente que se ejecutan en equipos con un solo procesador.

Si pwszBuildFlavor se establece en null, se cargará la compilación para la estación de trabajo. Cuando la ejecución se lleva a cabo en una máquina con un solo procesador, se carga siempre la compilación para la estación de trabajo, incluso aunque pwszBuildFlavor esté establecido en svr. Pero si pwszBuildFlavor se establece en svr y se especifica la recolección de elementos no utilizados simultánea (vea la descripción del parámetro startupFlags), se cargará la compilación para el servidor.

startupFlags
[in] Combinación de valores de la enumeración STARTUP_FLAGS. Estos marcadores controlan la recolección de elementos no utilizados simultánea, el código neutral respecto al dominio y el comportamiento del parámetro pwszVersion. Si no se establece ninguna marca, el valor predeterminado es un dominio único. Valores válidos son:

STARTUP_CONCURRENT_GC
STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN
STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN
STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST
STARTUP_LOADER_SAFEMODE
STARTUP_LOADER_SETPREFERENCE
STARTUP_SERVER_GC
STARTUP_HOARD_GC_VM
STARTUP_SINGLE_VERSION_HOSTING_INTERFACE
STARTUP_LEGACY_IMPERSONATION
STARTUP_DISABLE_COMMITTHREADSTACK
STARTUP_ALWAYSFLOW_IMPERSONATION

Para obtener una descripción de estas marcas, vea la enumeración STARTUP_FLAGS.

rclsid
[in] Elemento CLSID de la coclase que implementa la interfaz ICorRuntimeHost o ICLRRuntimeHost. Los valores admitidos son CLSID_CorRuntimeHost o CLSID_CLRRuntimeHost.

riid
[in] IID de la interfaz solicitada de rclsid. Los valores admitidos son IID_ICorRuntimeHost o IID_ICLRRuntimeHost.

ppv
[out] Puntero de interfaz devuelto a riid.

Comentarios

Si pwszVersion especifica una versión del runtime que no existe, CorBindToRuntimeEx devuelve un valor HRESULT de CLR_E_SHIM_RUNTIMELOAD.

Flujo y contexto de ejecución de la identidad de Windows

En la versión 1 de CLR, el objeto WindowsIdentity no fluye por puntos asincrónicos, como nuevos subprocesos, grupos de subprocesos o devoluciones de llamada de temporizador. En la versión 2.0 de CLR, el objeto ExecutionContext ajusta cierta información sobre el subproceso en ejecución y hace que fluya por cualquier punto asincrónico, pero no por los límites del dominio de aplicación. De igual forma, el objeto WindowsIdentity también fluye por cualquier punto asincrónico. Por consiguiente, también fluye la suplantación actual en el subproceso, si la hubiera.

El flujo puede modificarse de dos maneras:

Si se modifica la configuración de ExecutionContext para suprimir el flujo por subproceso (vea los métodos SuppressFlow, SuppressFlow y SuppressFlowWindowsIdentity).
Si se cambia el modo predeterminado del proceso al modo de compatibilidad de la versión 1, donde el objeto WindowsIdentity no fluye por ningún punto asincrónico, independientemente de los valores de ExecutionContext en el subproceso actual. La manera de cambiar el modo predeterminado depende de si se usa un archivo ejecutable administrado o una interfaz de hospedaje no administrada para cargar CLR:
1. Para los archivos ejecutables administrados, se debe establecer el atributo enabled del elemento <legacyImpersonationPolicy> en true.
2. Para las interfaces de hospedaje no administradas, se establece la marca STARTUP_LEGACY_IMPERSONATION en el parámetro startupFlags al llamar a la función CorBindToRuntimeEx.
El modo de compatibilidad de la versión 1 se aplica a todo el proceso y a todos los dominios de aplicación del proceso.

Requisitos

Plataformas: Vea Requisitos de sistema.

Encabezado: MSCorEE.h

Biblioteca: MSCorEE.dll

Versiones de .NET Framework: está disponible desde la versión 1.0

Compartir a través de