Função CorBindToRuntimeEx

Artigo
05/09/2023

Permite que hosts não gerenciados carreguem o CLR (Common Language Runtime) em um processo. As funções CorBindToRuntime e CorBindToRuntimeEx executam a mesma operação, mas a função CorBindToRuntimeEx permite definir sinalizadores para especificar o comportamento do CLR.

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

Essa função usa um conjunto de parâmetros que permitem que um host faça o seguinte:

Especificar a versão do runtime que será carregada.
Indicar se o build do servidor ou da estação de trabalho deve ser carregado.
Controlar se é feita a coleta de lixo simultânea ou não simultânea.

Observação

Não há suporte para coleta de lixo simultânea em aplicativos que executam o emulador WOW64 x86 em sistemas de 64 bits que implementam a arquitetura Intel Itanium (anteriormente chamada IA-64). Para obter mais informações sobre como usar o WOW64 em sistemas Windows de 64 bits, consulte Executar aplicativos de 32 bits.

Controlar se os assemblies são carregados como neutros ao domínio.
Obter um ponteiro de interface para um ICorRuntimeHost que pode ser usado para definir opções adicionais para configurar uma instância do CLR antes de ser iniciada.

Sintaxe

HRESULT CorBindToRuntimeEx (  
    [in]  LPCWSTR      pwszVersion,
    [in]  LPCWSTR      pwszBuildFlavor,
    [in]  DWORD        startupFlags,
    [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 em pwszVersion passando um valor de STARTUP_LOADER_SAFEMODE para o parâmetro startupFlags, conforme descrito abaixo.

Se o chamador especificar nulo para pwszVersion, CorBindToRuntimeEx identificará o conjunto de runtimes instalados cujos números de versão são inferiores ao runtime .NET Framework 4 e carregará a versão mais recente do runtime desse conjunto. Ele não carregará o .NET Framework 4 ou posterior e falhará se não estiver instalada nenhuma versão anterior. Observe que passar nulo não dá ao host nenhum controle sobre qual versão do runtime é 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âmetro startupFlags), a compilação do servidor será carregada.

startupFlags
[in] Uma combinação de valores da enumeração STARTUP_FLAGS. Esses sinalizadores controlam a coleta de lixo simultânea, o código neutro do domínio e o comportamento do parâmetro pwszVersion. O padrão será domínio único se nenhum sinalizador for definido. Os seguintes valores são válidos:

STARTUP_CONCURRENT_GC
STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN
STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN
STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST
STARTUP_LOADER_SAFEMODE
STARTUP_LOADER_SETPREFERENCE
STARTUP_SERVER_GC
STARTUP_HOARD_GC_VM
STARTUP_SINGLE_VERSION_HOSTING_INTERFACE
STARTUP_LEGACY_IMPERSONATION
STARTUP_DISABLE_COMMITTHREADSTACK
STARTUP_ALWAYSFLOW_IMPERSONATION

Para obter descrições desses sinalizadores, consulte a enumeração STARTUP_FLAGS.

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.

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 startupFlags 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