CorBindToRuntimeEx (Función)CorBindToRuntimeEx Function

Permite a los hosts no administrados cargar Common Language Runtime (CLR) en un proceso.Enables unmanaged hosts to load the common language runtime (CLR) into a process. Las funciones CorBindToRuntime y CorBindToRuntimeEx realizan la misma operación, pero la función CorBindToRuntimeEx permite establecer marcas para especificar el comportamiento de CLR.The CorBindToRuntime and CorBindToRuntimeEx functions perform the same operation, but the CorBindToRuntimeEx function allows you to set flags to specify the behavior of the CLR.

Esta función está en desuso en el .NET Framework 4.This function has been deprecated in the .NET Framework 4.

Esta función adopta una serie de parámetros que permiten a un host hacer lo siguiente:This function takes a set of parameters that allow a host to do the following:

  • Especificar la versión del runtime que se cargará.Specify the version of the runtime that will be loaded.

  • Indicar si se debe cargar la compilación para servidor o para estación de trabajo.Indicate whether the server or workstation build should be loaded.

  • Controlar si se realiza una recolección de elementos no utilizados simultánea o no simultánea.Control whether concurrent garbage collection or non-concurrent garbage collection is done.

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).Concurrent garbage collection is not supported in applications running the WOW64 x86 emulator on 64-bit systems that implement the Intel Itanium architecture (formerly called IA-64). Para obtener más información sobre el uso de WOW64 en sistemas Windows de 64 bits, vea ejecutar aplicaciones de 32 bits.For more information about using WOW64 on 64-bit Windows systems, see Running 32-bit Applications.

  • Determinar si se cargan los ensamblados como neutrales con respecto al dominio.Control whether assemblies are loaded as domain-neutral.

  • Obtener un puntero de interfaz a ICorRuntimeHost que se puede utilizar para establecer opciones adicionales para configurar una instancia de CLR antes de que se inicie.Obtain an interface pointer to an ICorRuntimeHost that can be used to set additional options for configuring an instance of the CLR before it is started.

SintaxisSyntax

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

ParámetrosParameters

pwszVersion
[in] Cadena que describe la versión de CLR que se desea cargar.[in] A string describing the version of the CLR you want to load.

Un número de versión en el .NET Framework consta de cuatro partes separadas por puntos: Major. minor. Build. revision.A version number in the .NET Framework consists of four parts separated by periods: 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").The string passed as pwszVersion must start with the character "v" followed by the first three parts of the version number (for example, "v1.0.1529").

Algunas versiones de CLR se instalan con una instrucción de directiva que especifica la compatibilidad con versiones anteriores de CLR.Some versions of the CLR are installed with a policy statement that specifies compatibility with previous versions of the 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.By default, the startup shim evaluates pwszVersion against policy statements and loads the latest version of the runtime that is compatible with the version being requested. 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.A host can force the shim to skip policy evaluation and load the exact version specified in pwszVersion by passing a value of STARTUP_LOADER_SAFEMODE for the startupFlags parameter, as described below.

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.If the caller specifies null for pwszVersion, CorBindToRuntimeEx identifies the set of installed runtimes whose version numbers are lower than the .NET Framework 4 runtime, and loads the latest version of the runtime from that set. No cargará .NET Framework 4 ni versiones posteriores, y producirá un error si no hay ninguna versión anterior instalada.It won't load the .NET Framework 4 or later, and fails if no earlier version is installed. Tenga en cuenta que pasar NULL impide al host controlar la versión del runtime que se carga.Note that passing null gives the host no control over which version of the runtime is loaded. Aunque este planteamiento puede ser apropiado en algunos escenarios, se recomienda encarecidamente que el host proponga cargar una versión específica.Although this approach may be appropriate in some scenarios, it is strongly recommended that the host supply a specific version to load.

pwszBuildFlavor
[in] Cadena que especifica si se debe cargar la compilación de CLR para servidor o para estación de trabajo.[in] A string that specifies whether to load the server or the workstation build of the CLR. Los valores válidos son svr y wks.Valid values are svr and 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.The server build is optimized to take advantage of multiple processors for garbage collections, and the workstation build is optimized for client applications running on a single-processor machine.

Si pwszBuildFlavor se establece en null, se carga la compilación de la estación de trabajo.If pwszBuildFlavor is set to null, the workstation build is loaded. Cuando se ejecuta en un equipo de un solo procesador, se carga siempre la compilación de la estación de trabajo, incluso si pwszBuildFlavor está establecido en svr.When running on a single-processor machine, the workstation build is always loaded, even if pwszBuildFlavor is set to svr. Sin embargo, si se establece pwszBuildFlavor 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 del servidor.However, if pwszBuildFlavor is set to svr and concurrent garbage collection is specified (see the description of the startupFlags parameter), the server build is loaded.

startupFlags
de Combinación de valores de la enumeración STARTUP_FLAGS .[in] A combination of values of the STARTUP_FLAGS enumeration. 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.These flags control concurrent garbage collection, domain-neutral code, and the behavior of the pwszVersion parameter. Si no se establece ninguna marca, el valor predeterminado es un dominio único.The default is single domain if no flag is set. Valores válidos son:The following values are valid:

  • STARTUP_CONCURRENT_GC

  • STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN

  • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN

  • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST

  • STARTUP_LOADER_SAFEMODE

  • STARTUP_LEGACY_IMPERSONATION

  • 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 descripciones de estas marcas, vea la enumeración STARTUP_FLAGS .For descriptions of these flags, see the STARTUP_FLAGS enumeration.

rclsid
de CLSID de la coclase que implementa la interfaz ICorRuntimeHost o ICLRRuntimeHost .[in] The CLSID of the coclass that implements either the ICorRuntimeHost or the ICLRRuntimeHost interface. Los valores admitidos son CLSID_CorRuntimeHost o CLSID_CLRRuntimeHost.Supported values are CLSID_CorRuntimeHost or CLSID_CLRRuntimeHost.

riid
[in] IID de la interfaz solicitada de rclsid.[in] The IID of the requested interface from rclsid. Los valores admitidos son IID_ICorRuntimeHost o IID_ICLRRuntimeHost.Supported values are IID_ICorRuntimeHost or IID_ICLRRuntimeHost.

ppv
[out] Puntero de interfaz devuelto a riid.[out] The returned interface pointer to riid.

ComentariosRemarks

Si pwszVersion especifica una versión del runtime que no existe, CorBindToRuntimeEx devuelve un valor HRESULT de CLR_E_SHIM_RUNTIMELOAD.If pwszVersion specifies a runtime version that does not exist, CorBindToRuntimeEx returns an HRESULT value of CLR_E_SHIM_RUNTIMELOAD.

Flujo y contexto de ejecución de la identidad de WindowsExecution Context and Flow of Windows Identity

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.In version 1 of the CLR, the WindowsIdentity object does not flow across asynchronous points such as new threads, thread pools, or timer callbacks. 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.In version 2.0 of the CLR, an ExecutionContext object wraps some information about the currently executing thread and flows it across any asynchronous point, but not across application domain boundaries. De igual forma, el objeto WindowsIdentity también fluye por cualquier punto asincrónico.Similarly, the WindowsIdentity object also flows across any asynchronous point. Por consiguiente, también fluye la suplantación actual en el subproceso, si la hubiera.Therefore, the current impersonation on the thread, if any, flows too.

El flujo puede modificarse de dos maneras:You can alter the flow in two ways:

  1. Si se modifica la configuración de ExecutionContext para suprimir el flujo por subproceso (vea los métodos SuppressFlow, SuppressFlow y SuppressFlowWindowsIdentity).By modifying the ExecutionContext settings to suppress the flow on a per-thread basis (see the SuppressFlow, SuppressFlow, and SuppressFlowWindowsIdentity methods).

  2. 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.By changing the process default mode to the version 1 compatibility mode, where the WindowsIdentity object does not flow across any asynchronous point, regardless of the ExecutionContext settings on the current thread. 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:How you change the default mode depends on whether you use a managed executable or an unmanaged hosting interface to load the CLR:

    1. Para los ejecutables administrados, debe establecer el atributo enabled del elemento <legacyImpersonationPolicy > en true.For managed executables, you must set the enabled attribute of the <legacyImpersonationPolicy> element to 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.For unmanaged hosting interfaces, set the STARTUP_LEGACY_IMPERSONATION flag in the startupFlags parameter when calling the CorBindToRuntimeEx function.

    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.The version 1 compatibility mode applies to the entire process and to all the application domains in the process.

RequisitosRequirements

Plataformas: Vea Requisitos de sistema.Platforms: See System Requirements.

Encabezado: MSCorEE. hHeader: MSCorEE.h

Biblioteca: MSCorEE. dllLibrary: MSCorEE.dll

Versiones de .NET Framework: Disponible desde la versión 1.0Available since 1.0.NET Framework Versions: Disponible desde la versión 1.0Available since 1.0

Vea tambiénSee also