Share via

CorBindToRuntimeHost Function

  • Article

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

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 the caller specifies null for pwszVersion, the latest version of the CLR 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.

  • 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 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 startupFlags parameter), the server build is loaded.

  • 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 the interface you are looking for. Supported values are CLSID_CorRuntimeHost or NULL.
  • riid
    [in] The IID of the interface you are requesting. Supported values for the initial release of the runtime are IID_ICorRuntimeHost or NULL.
  • ppv
    [out] An interface pointer to the version of the runtime that was loaded.

Requirements

Platforms: Windows 2000, Windows XP, Windows Server 2003 family

Header: MSCorEE.idl

Library: MSCorEE.dll

.NET Framework Version: 2.0, 1.1, 1.0

See Also

Reference

CorBindToCurrentRuntime Function
CorBindToRuntime Function
CorBindToRuntimeByCfg Function
CorBindToRuntimeEx Function
ICorRuntimeHost Interface

Other Resources

Hosting Global Static Functions