ICLRMetaHostPolicy::GetRequestedRuntime Method

Artikkeli
09/15/2021

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

Jaa