Compartilhar via

Método ICLRMetaHostPolicy::GetRequestedRuntime

  • Artigo

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

Confira também