Método ICLRMetaHostPolicy::GetRequestedRuntime

Artigo
05/10/2023

Fornece uma interface para uma versão preferencial do CLR (common language runtime) com base em uma política de hospedagem, assembly gerenciado, cadeia de caracteres de versão e fluxo de configuração. Esse método não carrega nem ativa o CLR, mas simplesmente retorna a interface ICLRRuntimeInfo que representa o resultado da política. Esse método substitui os métodos GetRequestedRuntimeInfo, GetRequestedRuntimeVersion, CorBindToRuntimeHost, CorBindToRuntimeByCfg e GetCORRequiredVersion.

Sintaxe

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

Parâmetros

Nome	Descrição
`dwPolicyFlags`	[in] Obrigatório. Especifica um membro da enumeração METAHOST_POLICY_FLAGS, representando uma política de associação e qualquer número de modificadores. A única política disponível no momento é METAHOST_POLICY_HIGHCOMPAT. Os modificadores incluem METAHOST_POLICY_EMULATE_EXE_LAUNCH, METAHOST_POLICY_APPLY_UPGRADE_POLICY, METAHOST_POLICY_SHOW_ERROR_DIALOG, METAHOST_POLICY_USE_PROCESS_IMAGE_PATH e METAHOST_POLICY_ENSURE_SKU_SUPPORTED.
`pwzBinary`	[in] Opcional. Especifica o caminho do arquivo de assembly.
`pCfgStream`	[in] Opcional. Especifica o arquivo de configuração como System.Runtime.InteropServices.ComTypes.IStream.
`pwzVersion`	[in, out] Opcional. Especifica ou retorna a versão de CLR preferencial a ser carregada.
`pcchVersion`	[in, out] Obrigatório. Especifica o tamanho esperado de `pwzVersion` como entrada, para evitar sobrecargas de buffer. Se `pwzVersion` for nulo, `pcchVersion` conterá o tamanho esperado de `pwzVersion` quando `GetRequestedRuntime` retorna, para permitir a pré-alocação. Caso contrário, `pcchVersion` conterá o número de caracteres gravados em `pwzVersion`.
`pwzImageVersion`	[out] Opcional. Quando `GetRequestedRuntime` retorna, contém a versão de CLR correspondente à interface ICLRRuntimeInfo retornada.
`pcchImageVersion`	[in, out] Opcional. Especifica o tamanho de `pwzImageVersion` como entrada para evitar sobrecargas de buffer. Se `pwzImageVersion` for nulo, `pcchImageVersion` conterá o tamanho necessário de `pwzImageVersion` quando `GetRequestedRuntime` retorna, para permitir a pré-alocação.
`pdwConfigFlags`	[out] Opcional. Se `GetRequestedRuntime` usa um arquivo de configuração durante o processo de associação, quando ele retorna, `pdwConfigFlags` conterá um valor METAHOST_CONFIG_FLAGS que indica se o elemento de <inicialização> tem o atributo `useLegacyV2RuntimeActivationPolicy` definido e o valor do atributo. Aplique a máscara METAHOST_CONFIG_FLAGS_LEGACY_V2_ACTIVATION_POLICY_MASK a `pdwConfigFlags` para obter os valores relevantes para `useLegacyV2RuntimeActivationPolicy`.
`riid`	[in] Especifica o identificador de interface IID_ICLRRuntimeInfo para a interface ICLRRuntimeInfo solicitada.
`ppRuntime`	[out] Quando `GetRequestedRuntime` retorna, contém um ponteiro para a interface ICLRRuntimeInfo correspondente.

Comentários

Quando esse método for bem-sucedido, ele terá o efeito colateral de combinar sinalizadores adicionais com os sinalizadores de inicialização padrão atuais da interface de runtime retornada, se e somente se houver um ou mais dos seguintes elementos no fluxo de configuração dentro da seção <configuration><runtime>:

<gcServer enabled="true"/> causa a definição de STARTUP_SERVER_GC.
<etwEnable enabled="true"/> causa a definição de STARTUP_ETW.
<appDomainResourceMonitoring enabled="true"/> causa a definição de STARTUP_ARM.

O valor padrão resultante STARTUP_FLAGS é a combinação OR bit a bit dos valores definidos da lista anterior com os sinalizadores de inicialização padrão.

Valor Retornado

Esse método retorna os seguintes HRESULTs específicos, bem como erros HRESULT que indicam falha de método.

HRESULT	Descrição
S_OK	O método foi concluído com sucesso.
E_POINTER	`pwzVersion` não é nulo e `pcchVersion` é nulo. -ou- `pwzImageVersion` não é nulo e `pcchImageVersion` é nulo.
E_INVALIDARG	`dwPolicyFlags` não especifica `METAHOST_POLICY_HIGHCOMPAT`.
ERROR_INSUFFICIENT_BUFFER	A memória alocada a `pwzVersion` é inadequada. -ou- A memória alocada a `pwzImageVersion` é inadequada.
CLR_E_SHIM_RUNTIMELOAD	`dwPolicyFlags` inclui METAHOST_POLICY_APPLY_UPGRADE_POLICY e ambos `pwzVersion` e `pcchVersion` são nulos.

Requisitos

Plataformas: confira Requisitos do sistema.

Cabeçalho: MetaHost.h

Biblioteca: incluída como um recurso no MSCorEE.dll

Versões do .NET Framework: disponíveis desde 4

Compartilhar via