Função CorBindToRuntime

Artigo
05/10/2023

Permite que hosts não gerenciados carreguem o Common Language Runtime (CLR) em um processo.

Essa função foi preterida no .NET Framework 4.

Sintaxe

HRESULT CorBindToRuntime (  
    [in]  LPCWSTR     pwszVersion,
    [in]  LPCWSTR     pwszBuildFlavor,
    [in]  REFCLSID    rclsid,
    [in]  REFIID      riid,
    [out] LPVOID FAR  *ppv  
);

Parâmetros

pwszVersion
[in] Uma string descrevendo a versão do CLR que você deseja carregar.

Um número de versão no .NET Framework consiste em quatro partes separadas por pontos: major.minor.build.revision. A cadeia de caracteres passada como pwszVersion deve começar com o caractere "v" seguido das três primeiras partes do número de versão (por exemplo, "v1.0.1529").

Algumas versões do CLR são instaladas com uma declaração de política que especifica a compatibilidade com versões anteriores do CLR. Por padrão, o shim de inicialização é avaliado pwszVersion em relação às instruções de política e carrega a versão mais recente do tempo de execução compatível com a versão solicitada. Um host pode forçar o shim a ignorar a avaliação da política e carregar a versão exata especificada pwszVersion passando um valor de STARTUP_LOADER_SAFEMODE para o parâmetro flags, conforme descrito abaixo.

Se o chamador especificar nulo para pwszVersion, a versão mais recente do tempo de execução será carregada. Passar nulo não dá ao host nenhum controle sobre qual versão do tempo de execução é carregada. Embora essa abordagem possa ser apropriada em alguns cenários, é altamente recomendável que o host forneça uma versão específica para carregar.

pwszBuildFlavor
[in] Uma cadeia de caracteres que especifica se deve carregar o servidor ou a compilação da estação de trabalho do CLR. Os valores válidos são svr e wks. A compilação do servidor é otimizada para tirar proveito de vários processadores para coletas de lixo e a compilação da estação de trabalho é otimizada para aplicativos cliente executados em uma máquina de processador único.

Se pwszBuildFlavor estiver definido como nulo, a compilação da estação de trabalho será carregada. Ao executar em uma máquina de processador único, a compilação da estação de trabalho é sempre carregada, mesmo se pwszBuildFlavor estiver definida como svr. No entanto, se pwszBuildFlavor for definido como svr e a coleta de lixo simultânea for especificada (consulte a descrição do parâmetroflags), a compilação do servidor será carregada.

rclsid
[in] O CLSID da coclass que implementa a interface ICorRuntimeHost ou ICLRRuntimeHost. Os valores com suporte são CLSID_CorRuntimeHost ou CLSID_CLRRuntimeHost.

riid
[in] O IID da interface solicitada de rclsid. Os valores com suporte são IID_ICorRuntimeHost ou IID_ICLRRuntimeHost.

ppv
[out] O ponteiro de interface retornado para riid.

Comentários

Se pwszVersion especifica uma versão de tempo de execução que não existe, CorBindToRuntimeEx retorna um valor HRESULT de CLR_E_SHIM_RUNTIMELOAD.

CorBindToRuntimeEx e CorBindToRuntime execute a mesma operação, mas a CorBindToRuntimeEx função permite definir sinalizadores para especificar o comportamento do CLR.

Contexto de execução e fluxo de identidade do Windows

Na versão 1 do CLR, o WindowsIdentity objeto não flui por pontos assíncronos, como novos threads, pools de threads ou retornos de chamada de timer. Na versão 2.0 do CLR, um ExecutionContext objeto encapsula algumas informações sobre o thread em execução no momento e as flui por qualquer ponto assíncrono, mas não pelos limites do domínio do aplicativo. Da mesma forma, o WindowsIdentity objeto também flui por qualquer ponto assíncrono. Portanto, a representação atual no encadeamento, se houver, também flui.

Você pode alterar o fluxo de duas maneiras:

Modificando as ExecutionContext configurações para suprimir o fluxo por thread (consulte os SuppressFlow, SuppressFlow, e SuppressFlowWindowsIdentity métodos).
Alterando o modo padrão do processo para o modo de compatibilidade da versão 1, em que o WindowsIdentity objeto não flui por nenhum ponto assíncrono, independentemente das ExecutionContext configurações no thread atual. Como você altera o modo padrão depende se você usa um executável gerenciado ou uma interface de hospedagem não gerenciada para carregar o CLR:
1. Para executáveis gerenciados, você deve definir o enabled atributo do elemento <legacyImpersonationPolicy> como true.
2. Para interfaces de hospedagem não gerenciadas, defina o STARTUP_LEGACY_IMPERSONATIONsinalizador no flags parâmetro ao chamar a CorBindToRuntimeEx função.
O modo de compatibilidade da versão 1 se aplica a todo o processo e a todos os domínios de aplicativo no processo.

Requisitos

Plataformas: confira Requisitos do sistema.

Cabeçalho: MSCorEE.h

Biblioteca: MSCorEE.dll

Versões do .NET Framework: Disponíveis desde a versão 1.0

Compartilhar via