CorBindToRuntimeHost Function

  • Article

Enables hosts to load a specified version of the common language runtime (CLR) into a process.

This function has been deprecated in the .NET Framework version 4.

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

Parameters

  • pwszVersion
    [in] A string that describes 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 startupFlags parameter.

    If pwszVersion is null, the method does not load any version of the CLR. Instead, it returns CLR_E_SHIM_RUNTIMELOAD, which indicates that it failed to load the runtime.

  • pwszBuildFlavor
    [in] A string that specifies whether to load the server or the workstation build of the CLR. Valid 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.

    If pwszBuildFlavoris set to null, the workstation build is loaded. When running on a single-processor machine, the workstation build is always loaded, even if pwszBuildFlavoris set to svr. However, if pwszBuildFlavoris set to svr and concurrent garbage collection is specified (see the description of the startupFlags parameter), the server build is loaded.

    Note

    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). For more information about using WOW64 on 64-bit Windows systems, see Running 32-bit Applications.

      

  • pwszHostConfigFile
    [in] The name of a host configuration file that specifies the version of the CLR to load. If the file name does not include a fully qualified path, the file is assumed to be in the same directory as the executable that is making the call.

  • pReserved
    [in] Reserved for future extensibility.

  • startupFlags
    [in] A set of flags that controls 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 supported:

    • STARTUP_CONCURRENT_GC: Specifies that concurrent garbage collection should be used. If the caller asks for the server build and specifies concurrent garbage collection on a single-processor machine, the workstation build and non-concurrent garbage collection are used instead.

    • STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN: Specifies that no assemblies are loaded as domain-neutral.

    • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN: Specifies that all assemblies are loaded as domain-neutral.

    • STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST: Specifies that all strong-named assemblies are loaded as domain-neutral.

    • STARTUP_LOADER_SAFEMODE: Specifies that the exact version of the CLR passed in pwszVersion will be loaded. The shim does not evaluate policy to determine the latest compatible version.

  • rclsid
    [in] The CLSID of the coclass that implements either the ICorRuntimeHost or the ICLRRuntimeHost interface. Supported values are CLSID_CorRuntimeHost or CLSID_CLRRuntimeHost.

  • riid
    [in] The IID of the interface you are requesting. Supported values are IID_ICorRuntimeHost or IID_ICLRRuntimeHost.

  • ppv
    [out] An interface pointer to the version of the runtime that was loaded.

Requirements

Platforms: See .NET Framework System Requirements.

Header: MSCorEE.idl

Library: MSCorEE.dll

.NET Framework Versions: 4, 3.5 SP1, 3.5, 3.0 SP1, 3.0, 2.0 SP1, 2.0, 1.1, 1.0

See Also

Reference

CorBindToCurrentRuntime Function

CorBindToRuntime Function

CorBindToRuntimeByCfg Function

CorBindToRuntimeEx Function

ICorRuntimeHost Interface

Other Resources

.NET Framework 1.1 and 2.0 Hosting Global Static Functions