Enables unmanaged hosts to load the common language runtime (CLR) into a process.
This function has been deprecated in the .NET Framework 4.
HRESULT CorBindToRuntime ( [in] LPCWSTR pwszVersion, [in] LPCWSTR pwszBuildFlavor, [in] REFCLSID rclsid, [in] REFIID riid, [out] LPVOID FAR *ppv );
[in] A string describing the version of the CLR you want to load.
A version number in the .NET Framework consists of four parts separated by periods: major.minor.build.revision. 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").
Some versions of the CLR are installed with a policy statement that specifies compatibility with previous versions of the CLR. 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. 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
flags parameter, as described below.
If the caller specifies null for
pwszVersion, the latest version of the runtime is loaded. 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.
[in] A string that specifies whether to load the server or the workstation build of the CLR. Valid values are
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 is set to null, the workstation build is loaded. When running on a single-processor machine, the workstation build is always loaded, even if
pwszBuildFlavor is set to
svr. However, if
pwszBuildFlavor is set to
svr and concurrent garbage collection is specified (see the description of the
flags parameter), the server build is loaded.
IID of the requested interface from
rclsid. Supported values are IID_ICorRuntimeHost or IID_ICLRRuntimeHost.
[out] The returned interface pointer to
pwszVersion specifies a runtime version that does not exist,
CorBindToRuntimeEx returns an HRESULT value of CLR_E_SHIM_RUNTIMELOAD.
CorBindToRuntime perform the same operation, but the
CorBindToRuntimeEx function allows you to set flags to specify the behavior of the CLR.
Execution Context and Flow of Windows Identity
In version 1 of the CLR, the WindowsIdentity object does not flow across asynchronous points such as new threads, thread pools, or timer callbacks. 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. 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:
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. How you change the default mode depends on whether you use a managed executable or an unmanaged hosting interface to load the CLR:
For managed executables, you must set the
enabledattribute of the <legacyImpersonationPolicy> element to
For unmanaged hosting interfaces, set the
STARTUP_LEGACY_IMPERSONATIONflag in the
flagsparameter when calling the
The version 1 compatibility mode applies to the entire process and to all the application domains in the process.
Platforms: See System Requirements.
.NET Framework Versions: Available since 1.0