CorBindToRuntimeEx 函数

项目
05/09/2023

使非托管主机能够将公共语言运行时 (CLR) 加载到进程中。 CorBindToRuntimeEx 和 CorBindToRuntimeEx 函数执行相同的操作，但 CorBindToRuntimeEx 函数支持设置标志来指定 CLR 的行为。

.NET Framework 4 中已弃用此函数。

此函数采用一组参数，可支持主机执行以下操作：

指定要加载的运行时的版本。
指示应加载服务器还是工作站内部版本。
控制是执行并发垃圾回收还是非并发垃圾回收。

备注

在实现 Intel Itanium 体系结构（以前称为 IA-64）的 64 位系统上运行 WOW64 x86 仿真器的应用程序不支持并发垃圾回收。有关在 64 位 Windows 系统上使用 WOW64 的详细信息，请参阅运行 32 位应用程序。

控制程序集是否加载为非特定于域的程序集。
获取指向 ICorRuntimeHost 的接口指针，该指针可用于设置用于在启动 CLR 实例之前配置该实例的其他选项。

语法

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

参数

pwszVersion
[in] 一个字符串，用于描述要加载的 CLR 版本。

.NET Framework 中的版本号由句点分隔的四个部分组成：major.minor.build.revision。作为 pwszVersion 传递的字符串必须以字符“v”开头，后接版本号的前三个部分（例如“v1.0.1529”）。

某些版本的 CLR 装有一个策略语句，该声明指定与以前版本的 CLR 的兼容性。默认情况下，启动 shim 根据策略语句评估 pwszVersion，并加载与所请求版本兼容的最新版运行时。主机可以通过为 startupFlags 参数传递 STARTUP_LOADER_SAFEMODE 值来强制 shim 跳过策略评估并加载 pwszVersion 中指定的确切版本，如下所述。

如果调用方为 pwszVersion 指定 null，则 CorBindToRuntimeEx 会标识版本号低于 .NET Framework 4 运行时的已安装的运行时集，并从此集中加载最新版本的运行时。它不会加载 .NET Framework 4 或更高版本，且如果没有安装的早期版本，则加载会失败。注意，传递 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_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 或 ICLRRuntimeHost 接口的组件类的 CLSID。支持的值为 CLSID_CorRuntimeHost 或 CLSID_CLRRuntimeHost。

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

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

备注

如果 pwszVersion 指定了不存在的运行时版本，则 CorBindToRuntimeEx 将返回 HRESULT 值 CLR_E_SHIM_RUNTIMELOAD。

Windows 标识的执行上下文和流

在 CLR 版本 1 中，WindowsIdentity 对象不会流经新线程、线程池或计时器回调等异步点。在 CLR 版本 2.0 中，ExecutionContext 对象包装有关当前正在执行的线程的某些信息，并使其流经任何异步点，但不会跨越应用程序域边界。同样，WindowsIdentity 对象也流经任何异步点。因此，线程上的当前模拟（如果有）也会流动。

可通过两种方式更改流：

通过修改 ExecutionContext 设置来按线程抑制流动（请参阅 SuppressFlow、SuppressFlow 和 SuppressFlowWindowsIdentity 方法）。
将进程默认模式更改为版本 1 兼容性模式，在此模式下，不管当前线程上的 ExecutionContext 设置如何，WindowsIdentity 对象都不会流经任何异步点。如何更改默认模式取决于是使用托管可执行文件还是非托管主机接口来加载 CLR：
1. 如果使用托管可执行文件，则必须将 <legacyImpersonationPolicy> 元素的 enabled 属性设置为 true。
2. 如果使用非托管主机接口，请在调用 CorBindToRuntimeEx 函数时在 startupFlags 参数中设置 STARTUP_LEGACY_IMPERSONATION 标志。
版本 1 兼容性模式适用于整个进程以及进程中的所有应用程序域。

要求

平台：请参阅系统要求。

标头：MSCorEE.h

库：MSCorEE.dll

.NET Framework 版本：自 1.0 起可用

通过

CorBindToRuntimeEx 函数

语法

参数

备注

Windows 标识的执行上下文和流

要求

另请参阅

其他资源