Edit

ICLRMetaHostPolicy::GetRequestedRuntime Method

  • Article

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.

Syntax

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);

Parameters

Name Description
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.

Modifiers include METAHOST_POLICY_EMULATE_EXE_LAUNCH, METAHOST_POLICY_APPLY_UPGRADE_POLICY, METAHOST_POLICY_SHOW_ERROR_DIALOG, METAHOST_POLICY_USE_PROCESS_IMAGE_PATH, and METAHOST_POLICY_ENSURE_SKU_SUPPORTED.
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.

Remarks

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.

Return Value

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

HRESULT Description
S_OK The method completed successfully.
E_POINTER pwzVersion is not null and pcchVersion is null.

-or-

pwzImageVersion is not null and pcchImageVersion is null.
E_INVALIDARG dwPolicyFlags does not specify METAHOST_POLICY_HIGHCOMPAT.
ERROR_INSUFFICIENT_BUFFER The memory allocated to pwzVersion is inadequate.

-or-

The memory allocated to pwzImageVersion is inadequate.
CLR_E_SHIM_RUNTIMELOAD dwPolicyFlags includes METAHOST_POLICY_APPLY_UPGRADE_POLICY, and both pwzVersion and pcchVersion are null.

Requirements

Platforms: See System Requirements.

Header: MetaHost.h

Library: Included as a resource in MSCorEE.dll

.NET Framework Versions: Available since 4

See also