CorBindToRuntimeEx 函数CorBindToRuntimeEx Function

使非托管宿主能够将公共语言运行时(CLR)加载到进程中。Enables unmanaged hosts to load the common language runtime (CLR) into a process. CorBindToRuntimeCorBindToRuntimeEx 函数执行相同的操作,但 CorBindToRuntimeEx 函数允许您设置标志来指定 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.

此函数已在 .NET Framework 4 中弃用。This function has been deprecated in the .NET Framework 4.

此函数使用一组参数,这些参数允许主机执行以下操作:This function takes a set of parameters that allow a host to do the following:

  • 指定要加载的运行时版本。Specify the version of the runtime that will be loaded.

  • 指示是否应加载服务器或工作站生成。Indicate whether the server or workstation build should be loaded.

  • 控制并发垃圾回收或非并发垃圾回收是否已完成。Control whether concurrent garbage collection or non-concurrent garbage collection is done.

备注

在实现 Intel Itanium 体系结构(以前称为 IA-64)的64位系统上运行 WOW64 x86 模拟器的应用程序中不支持并发垃圾回收。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). 有关在64位 Windows 系统上使用 WOW64 的详细信息,请参阅运行32位应用程序For more information about using WOW64 on 64-bit Windows systems, see Running 32-bit Applications.

  • 控制是否以非特定于域的形式加载程序集。Control whether assemblies are loaded as domain-neutral.

  • 获取一个指向ICorRuntimeHost的接口指针,该指针可用于设置附加选项,以便在启动 CLR 实例之前对其进行配置。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.

语法Syntax

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

参数Parameters

pwszVersion
中一个字符串,描述要加载的 CLR 的版本。[in] A string describing the version of the CLR you want to load.

.NET Framework 中的版本号由以句点分隔的四个部分组成:版本. 次要版本. 内部版本号. 修订号。A version number in the .NET Framework consists of four parts separated by periods: major.minor.build.revision. 作为 pwszVersion 传递的字符串必须以字符 "v" 开头,后跟版本号的前三个部分(例如,"1.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").

某些版本的 CLR 随策略声明一起安装,后者指定与以前版本的 CLR 的兼容性。Some versions of the CLR are installed with a policy statement that specifies compatibility with previous versions of the CLR. 默认情况下,启动填充程序根据策略语句计算 pwszVersion,并加载与请求的版本兼容的运行时的最新版本。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. 主机可以通过为 startupFlags 参数传递值 STARTUP_LOADER_SAFEMODE 来强制填充程序跳过策略评估并加载 pwszVersion 中指定的确切版本,如下所述。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.

如果调用方为 pwszVersion指定 null,则 CorBindToRuntimeEx 会标识已安装的运行时集,其版本号低于 .NET Framework 4 运行时,并从该集中加载最新版本的运行时。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. 它不会加载 .NET Framework 4 或更高版本,如果未安装任何早期版本,则会失败。It won't load the .NET Framework 4 or later, and fails if no earlier version is installed. 请注意,传递 null 会使宿主无法控制加载的运行时版本。Note that passing null gives the host no control over which version of the runtime is loaded. 虽然这种方法可能适用于某些情况,但强烈建议主机提供要加载的特定版本。Although this approach may be appropriate in some scenarios, it is strongly recommended that the host supply a specific version to load.

pwszBuildFlavor
中一个字符串,指定是加载 CLR 的服务器还是工作站版本。[in] A string that specifies whether to load the server or the workstation build of the CLR. 有效值为 svrwksValid values are svr and wks. 服务器版本经过优化,可利用多个处理器进行垃圾回收,工作站构建针对单处理器计算机上运行的客户端应用程序进行了优化。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.

如果 pwszBuildFlavor 设置为 null,则会加载工作站构建。If pwszBuildFlavor is set to null, the workstation build is loaded. 在单处理器计算机上运行时,始终会加载工作站构建,即使 pwszBuildFlavor 设置为 svrWhen running on a single-processor machine, the workstation build is always loaded, even if pwszBuildFlavor is set to svr. 但是,如果 pwszBuildFlavor 设置为 svr 并指定了并发垃圾回收(请参阅 startupFlags 参数的说明),则将加载服务器生成。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
STARTUP_FLAGS枚举值的组合。[in] A combination of values of the STARTUP_FLAGS enumeration. 这些标志控制并发垃圾回收、非特定于域的代码和 pwszVersion 参数的行为。These flags control concurrent garbage collection, domain-neutral code, and the behavior of the pwszVersion parameter. 如果未设置任何标志,则默认值为单一域。The default is single domain if no flag is set. 以下为有效值: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

有关这些标志的说明,请参阅STARTUP_FLAGS枚举。For descriptions of these flags, see the STARTUP_FLAGS enumeration.

rclsid
中用于实现ICorRuntimeHostICLRRuntimeHost接口的 coclass 的 CLSID[in] The CLSID of the coclass that implements either the ICorRuntimeHost or the ICLRRuntimeHost interface. 支持的值为 CLSID_CorRuntimeHost 或 CLSID_CLRRuntimeHost。Supported values are CLSID_CorRuntimeHost or CLSID_CLRRuntimeHost.

riid
中从 rclsid请求的接口的 IID[in] The IID of the requested interface from rclsid. 支持的值为 IID_ICorRuntimeHost 或 IID_ICLRRuntimeHost。Supported values are IID_ICorRuntimeHost or IID_ICLRRuntimeHost.

ppv
弄返回 riid的接口指针。[out] The returned interface pointer to riid.

备注Remarks

如果 pwszVersion 指定不存在的运行时版本,则 CorBindToRuntimeEx 返回 HRESULT 值 CLR_E_SHIM_RUNTIMELOAD。If pwszVersion specifies a runtime version that does not exist, CorBindToRuntimeEx returns an HRESULT value of CLR_E_SHIM_RUNTIMELOAD.

执行上下文和 Windows 标识流Execution Context and Flow of Windows Identity

在 CLR 版本1中,WindowsIdentity 对象不流经异步点,如新线程、线程池或计时器回调。In version 1 of the CLR, the WindowsIdentity object does not flow across asynchronous points such as new threads, thread pools, or timer callbacks. 在 CLR 版本2.0 中,ExecutionContext 对象包装了有关当前正在执行的线程的一些信息,并在所有异步点(而不是跨应用程序域边界)传递它。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. 同样,WindowsIdentity 对象还会流经任何异步点。Similarly, the WindowsIdentity object also flows across any asynchronous point. 因此,线程上的当前模拟(如果有)也会流动。Therefore, the current impersonation on the thread, if any, flows too.

可以通过两种方式更改流:You can alter the flow in two ways:

  1. 通过修改 ExecutionContext 设置以按线程抑制流(请参阅 SuppressFlowSuppressFlowSuppressFlowWindowsIdentity 方法)。By modifying the ExecutionContext settings to suppress the flow on a per-thread basis (see the SuppressFlow, SuppressFlow, and SuppressFlowWindowsIdentity methods).

  2. 将进程默认模式更改为版本1兼容模式,其中 WindowsIdentity 对象不在任何异步点上流动,无论当前线程上的 ExecutionContext 设置如何。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. 更改默认模式的方式取决于您使用的是托管可执行文件还是非托管承载接口来加载 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. 对于托管的可执行文件,必须将<legacyImpersonationPolicy >元素的 enabled 属性设置为 "true"。For managed executables, you must set the enabled attribute of the <legacyImpersonationPolicy> element to true.

    2. 对于非托管承载接口,请在调用 CorBindToRuntimeEx 函数时设置 startupFlags 参数中的 STARTUP_LEGACY_IMPERSONATION 标志。For unmanaged hosting interfaces, set the STARTUP_LEGACY_IMPERSONATION flag in the startupFlags parameter when calling the CorBindToRuntimeEx function.

    版本1兼容性模式适用于整个进程和进程中的所有应用程序域。The version 1 compatibility mode applies to the entire process and to all the application domains in the process.

要求Requirements

平台: 请参阅系统要求Platforms: See System Requirements.

标头: Mscoree.dllHeader: MSCorEE.h

库: Mscoree.dllLibrary: MSCorEE.dll

.NET Framework 版本: 自 1.0 之后可用Available since 1.0.NET Framework Versions: 自 1.0 之后可用Available since 1.0

请参阅See also