Setting the Startup Options Using CorBindToRuntimeEx

Setting the Startup Options Using CorBindToRuntimeEx

Once you understand the CLR startup options, setting them using CorBindToRuntimeEx is easy. The version and build type options map directly to parameters to the API, and the concurrent garbage collection and the domain-neutral options are specified as flags.

Here's the definition of CorBindToRuntimeEx from mscoree.h:

STDAPI CorBindToRuntimeEx(LPCWSTR pwszVersion,                           LPCWSTR pwszBuildFlavor,                           DWORD startupFlags,                           REFCLSID rclsid,                           REFIID riid,                           LPVOID FAR *ppv);

Table 3-2 describes the parameters to CorBindToRuntimeEx and how they are used to set the CLR startup options.

Table 3-2. CorBindToRuntimeEx Parameters to Configure CLR Startup

CLR Startup Setting	Parameter	Legal Values	Default
Version	pwszVersion	A string describing the version of the CLR to load or specifying NULL. The string must be in the following form: v.major.minor.build For example, to load the CLR that comes with .NET Framework 1.0, you'd pass v1.0.3705. Passing NULL loads the latest version of the CLR installed on the machine.	NULL
Build	pwszBuildFlavor	A string describing whether to load the server or workstation build. The following are valid values: svr and wks. Remember, too, that svr value is ignored on uniprocessor machines. The workstation build is always loaded in such cases.	wks
Concurrent garbage collection	startupFlags	Concurrent garbage collection is turned on by passing STARTUP_CONCURRENT_GC to startupFlags. This flag, along with the flags for the domain-neutral options, is specified by the STARTUP_FLAGS enumeration in mscoree.h.	Enabled
Domain-neutral code	startupFlags	The following are valid values from STARTUP_FLAGS: STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN. No assemblies are loaded domain neutral. STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN. All assemblies are loaded domain neutral. STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST. Strong-named assemblies are loaded domain neutral.	No assemblies loaded domain neutral (except mscorlib)

You'll notice that CorBindToRuntimeEx has three parameters in addition to the ones described in Table 3-2: rclsid, riid, and ppv. These parameters are used to get an interface pointer of type ICLRRuntimeHost through which to access all the functionality in the COM interfaces that are part of the CLR hosting APIs. The capabilities available through ICLRRuntimeHost are described in Chapter 2. Table 3-3 describes the parameters used to get a pointer to ICLRRuntimeHost.

Table 3-3. CorBindToRuntimeEx Parameters to Return ICLRRuntimeHost

Parameter	Description
rclsid	[in][1] The CLSID of the object containing the ICLRRuntimeHost interface. Always pass CLSID_ClrRuntimeHost.[2]
riid	[in] The IID of ICLRRuntimeHost. Always pass IID_ICLRRuntimeHost.
ppv	[out] The address of the returned ICLRRuntimeHost pointer.

^[1] [in] means that the parameter is passed in to the function. [out] means the parameter is returned from the function.

^[2] The need to pass the CLSID and the IID for the runtime host interface might seem unnecessary. The reason these parameters exist is so the API can return interfaces of different types in a future release.