CorBindToRuntimeEx

Enables unmanaged hosts to load the common language runtime into a process. See Hosting the Common Language Runtime for a complete description of the scenarios in which CorBindToRuntimeEx is used.

This method takes a set of parameters that allow a host to:

• 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.
• Control whether assemblies are loaded as domain-neutral.
• Obtain an interface pointer to ICorRuntimeHost that can be used to set numerous additional options that allow a host to configure an instance of the common language runtime before it is started. ICorRuntimeHost is described in the Hosting Interfaces documentation in the Tool Developers Guide that ships as part of the .NET Framework SDK.

Syntax

HRESULT CorBindToRuntimeEx(
  LPWSTR pwszVersion,   
  LPWSTR pwszBuildFlavor, 
  DWORD flags,            
  REFCLSID rclsid,      
  REFIID riid,    
  LPVOID* ppv
);

Header file: Include Mscoree.h.

Library: Link with Mscoree.lib.

Parameters

• pwszVersion [in]
  A string describing the version of the common language runtime 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 common language runtime are installed with a policy statement that specifies compatibility with previous versions of the common language runtime. 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 exactly the version specified in pwszVersion by passing STARTUP_LOADER_SAFEMODE in the flags parameter. See description of flags below.

  If the caller specifies null for pwszVersion, the latest version of the common language runtime is loaded. Passing null gives the host no control over which version of the runtime is loaded. While this 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 common language runtime. Valid values are "wks" and "svr". The server build is optimized to take advantage of multiple processors when doing garbage collections, while 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 "svr" is passed and concurrent garbage collection is specified (see description of the flags parameter below), the server build is loaded. Running concurrent garbage collection on a server build is generally not desirable, but the common language runtime startup shim has no special logic to prevent this configuration.

• flags [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 none of the flags is set. The following values are valid:

  STARTUP_CONCURRENT_GC

  Specifies that concurrent garbage collection should be used.

  **Note   **If the caller asks for the server build and concurrent garbage collection on a single-processor machine, the workstation build and non-concurrent garbage collection is run instead.

  STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN

  No assemblies are loaded as domain-neutral.

  STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN

  All assemblies are loaded as domain-neutral.

  STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST

  All strong-named assemblies are loaded as domain-neutral.

  STARTUP_LOADER_SAFEMODE

  Specifies that the exact version of the common language runtime 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 [in]
  The returned interface pointer.