CorBindToRuntimeEx 函数

更新:2007 年 11 月

使非托管宿主可以将公共语言运行时 (CLR) 加载到进程中。CorBindToRuntimeCorBindToRuntimeEx 函数执行相同的操作,但 CorBindToRuntimeEx 函数允许通过设置标志来指定 CLR 的行为。

有关使用 CorBindToRuntimeEx 的方案的完整描述,请参见承载公共语言运行库

此函数使用一组参数,这些参数允许宿主执行下列操作:

  • 指定要加载的运行时的版本。

  • 指示应加载服务器版本还是工作站版本。

  • 控制是执行并发垃圾回收还是非并发垃圾回收。

说明:

如果应用程序在实现 Intel Itanium 体系结构的 64 位系统(以前称为 IA-64)上运行 WOW64 x86 仿真程序,则在这些应用程序中不支持并发垃圾回收。有关在 64 位 Windows 系统上使用 WOW64 的更多信息,请参见 Running 32-bit Applications(运行 32 位应用程序)。

  • 控制程序集是否以非特定于域的形式进行加载。

  • 获取一个接口指针,该指针指向可用于在启动 CLR 的实例之前设置用于配置该实例的附加选项的 ICorRuntimeHost

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

参数

  • pwszVersion
    [in] 一个字符串,描述要加载的 CLR 的版本。

    .NET Framework 中的版本号由句点分隔的四个部分组成:主版本.次版本.内部版本.修订版。作为 pwszVersion 传递的字符串必须以字符“v”开头,后面跟上版本号的前三个部分(例如“v1.0.1529”)。

    某些版本的 CLR 在安装时带有策略声明,用于指定与 CLR 早期版本的兼容性。默认情况下,启动程序 (startup shim) 根据策略声明评估 pwszVersion,并加载与当前所需版本兼容的最新运行时版本。如下所述,通过为 startupFlags 参数传递 STARTUP_LOADER_SAFEMODE 值,宿主可以强制启动程序跳过策略评估并加载 pwszVersion 中指定的确切版本。

    如果调用方将 pwszVersion 指定为 null,则将加载运行时的最新版本。如果传递 null,则主机对加载的运行时的版本没有控制。虽然在某些情况下此方法可能是适用的,但强烈建议主机提供一个要加载的特定版本。

  • pwszBuildFlavor
    [in] 一个字符串,指定是加载 CLR 的服务器版本还是工作站版本。有效值为:svr 和 wks。服务器版本已经过优化,可以利用多个处理器进行垃圾回收,而工作站版本则针对单处理器计算机上运行的客户端应用程序进行了优化。

    如果 pwszBuildFlavor设置为 null,则将加载工作站版本。在单处理器计算机上运行时,即使 pwszBuildFlavor 设置为 svr,也将始终加载工作站版本。但是,如果将 pwszBuildFlavor设置为 svr,并且指定了并发垃圾回收(请参见有关 startupFlags 参数的说明),则将加载服务器版本。

  • startupFlags
    [in] STARTUP_FLAGS 枚举值的组合。这些标志控制并发垃圾回收、非特定于域的代码以及 pwszVersion 参数的行为。如果未设置标志,则默认值为一个域。以下为有效值:

    • 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

    有关这些标志的说明,请参见 STARTUP_FLAGS 枚举。

  • rclsid
    [in] 实现 ICorRuntimeHost 接口的 coclass 的 CLSID。支持的值为 CLSID_CorRuntimeHost或 CLSID_CLRRuntimeHost。

  • riid
    [in] 请求自 rclsid 接口的 IID。支持的值为 IID_ICorRuntimeHost 或 IID_ICLRRuntimeHost。

  • ppv
    [out] 返回的指向 riid 的接口指针。

备注

如果 pwszVersion 指定一个不存在的运行时版本,则 CorBindToRuntimeEx 返回 HRESULT 值 CLR_E_SHIM_RUNTIMELOAD。

Windows 标识的执行上下文和 Windows 标识的流动

在 CLR 的版本 1 中,WindowsIdentity 对象不流过异步点,如新线程、线程池或计时器回调。在 CLR 的 2.0 版中,ExecutionContext 对象对有关当前执行线程的某些信息进行包装,然后使包装后的信息流过任何异步点,但不流过应用程序域边界。同样,WindowsIdentity 对象也会流过任何异步点。因此,线程中的当前模拟(如果有)也会流动。

可以通过以下两种方式更改流:

  1. 修改 ExecutionContext 设置,从而逐线程取消流动(请参见 SuppressFlowSuppressFlowSuppressFlowWindowsIdentity 方法)。

  2. 通过将进程默认模式更改为版本 1 兼容模式,在该模式中无论当前线程上的 ExecutionContext 设置如何,WindowsIdentity 对象都不会流过任何异步点。更改默认模式的方法取决于是使用托管可执行文件还是非托管宿主接口来加载 CLR:

    1. 对于托管可执行文件,必须将 <legacyImpersonationPolicy> 元素的 enabled 属性设置为 true。

    2. 对于非托管宿主接口,请在调用 CorBindToRuntimeEx 函数时在 startupFlags 参数中设置 STARTUP_LEGACY_IMPERSONATION 标志。

    版本 1 兼容模式适用于整个进程以及该进程中的所有应用程序域。

要求

**平台:**请参见 .NET Framework 系统要求

**头文件:**MSCorEE.idl

**库:**MSCorEE.dll

**.NET Framework 版本:**3.5 SP1、3.5、3.0 SP1、3.0、2.0 SP1、2.0、1.1、1.0

请参见

参考

CorBindToCurrentRuntime 函数

CorBindToRuntime 函数

CorBindToRuntimeByCfg 函数

CorBindToRuntimeHost 函数

ICorRuntimeHost

其他资源

宿主全局静态函数