ICLRMetaHostPolicy::GetRequestedRuntime Method

.NET Framework (current version)

Provides an interface to a preferred version of the common language runtime (CLR) based on a hosting policy, managed assembly, version string, and configuration stream. This method does not actually load or activate the CLR, but simply returns the ICLRRuntimeInfo interface that represents the policy result. This method supersedes the GetRequestedRuntimeInfo, GetRequestedRuntimeVersion, CorBindToRuntimeHost, CorBindToRuntimeByCfg, and GetCORRequiredVersion methods.

HRESULT GetRequestedRuntime(  
    [in]  METAHOST_POLICY_FLAGS dwPolicyFlags,  
    [in]  LPCWSTR pwzBinary,  
    [in]  IStream *pCfgStream,  
    [in, out, size_is(*pcchVersion)] LPWSTR pwzVersion,  
    [in, out]  DWORD *pcchVersion,  
    [out, size_is(*pcchImageVersion)] LPWSTR pwzImageVersion,  
    [in, out]  DWORD *pcchImageVersion,  
    [out] DWORD *pdwConfigFlags,  
    [in]  REFIID  riid  
    [out, iid_is(riid), retval] LPVOID *ppRuntime);  


dwPolicyFlags[in] Required. Specifies a member of the METAHOST_POLICY_FLAGS enumeration, representing a binding policy, and any number of modifiers. The only policy that is currently available is METAHOST_POLICY_HIGHCOMPAT.

pwzBinary[in] Optional. Specifies the assembly file path.
pCfgStream[in] Optional. Specifies the configuration file as a System.Runtime.InteropServices.ComTypes.IStream.
pwzVersion[in, out] Optional. Specifies or returns the preferred CLR version to be loaded.
pcchVersion[in, out] Required. Specifies the expected size of pwzVersion as input, to avoid buffer overruns. If pwzVersion is null, pcchVersion contains the expected size of pwzVersion when GetRequestedRuntime returns, to allow pre-allocation; otherwise, pcchVersion contains the number of characters written to pwzVersion.
pwzImageVersion[out] Optional. When GetRequestedRuntime returns, contains the CLR version corresponding to the ICLRRuntimeInfo interface that is returned.
pcchImageVersion[in, out] Optional. Specifies the size of pwzImageVersion as input to avoid buffer overruns. If pwzImageVersion is null, pcchImageVersion contains the required size of pwzImageVersion when GetRequestedRuntime returns, to allow pre-allocation.
pdwConfigFlags[out] Optional. If GetRequestedRuntime uses a configuration file during the binding process, when it returns, pdwConfigFlags contains a METAHOST_CONFIG_FLAGS value that indicates whether the <startup> element has the useLegacyV2RuntimeActivationPolicy attribute set, and the value of the attribute. Apply the METAHOST_CONFIG_FLAGS_LEGACY_V2_ACTIVATION_POLICY_MASK mask to pdwConfigFlags to get the values relevant to useLegacyV2RuntimeActivationPolicy.
riid[in] Specifies the interface identifier IID_ICLRRuntimeInfo for the requested ICLRRuntimeInfo interface.
ppRuntime[out] When GetRequestedRuntime returns, contains a pointer to the corresponding ICLRRuntimeInfo interface.

When this method succeeds, it has the side effect of combining additional flags with the current default startup flags of the returned runtime interface, if and only if one or more of the following elements exist in the configuration stream within the <configuration><runtime> section:

  • <gcServer enabled="true"/> causes STARTUP_SERVER_GC to be set.

  • <etwEnable enabled="true"/> causes STARTUP_ETW to be set.

  • <appDomainResourceMonitoring enabled="true"/> causes STARTUP_ARM to be set.

The resulting default STARTUP_FLAGS value is the bitwise OR combination of the values that are set from the preceding list with the default startup flags.

This method returns the following specific HRESULTs as well as HRESULT errors that indicate method failure.

S_OKThe method completed successfully.
E_POINTERpwzVersion is not null and pcchVersion is null.


 pwzImageVersion is not null and pcchImageVersion is null.
ERROR_INSUFFICIENT_BUFFERThe memory allocated to pwzVerison is inadequate.


The memory allocated to pwzImageVerison is inadequate.
CLR_E_SHIM_RUNTIMELOADdwPolicyFlags includes METAHOST_POLICY_APPLY_UPGRADE_POLICY, and both pwzVersion and pcchVersion are null.

Platforms: See System Requirements.

Header: MetaHost.h

Library: Included as a resource in MSCorEE.dll

.NET Framework Versions: Available since 4

ICLRMetaHostPolicy Interface
CLR Hosting Interfaces Added in the .NET Framework 4 and 4.5
Hosting Interfaces