Função CorBindToRuntimeEx

Artigo
05/09/2023

Permite que os anfitriões não geridos carreguem o runtime de linguagem comum (CLR) para um processo. O CorBindToRuntime e CorBindToRuntimeEx as funções executam a mesma operação, mas a CorBindToRuntimeEx função permite-lhe definir sinalizadores para especificar o comportamento do CLR.

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

Esta função utiliza um conjunto de parâmetros que permitem que um anfitrião faça o seguinte:

Especifique a versão do runtime que será carregada.
Indique se a compilação do servidor ou da estação de trabalho deve ser carregada.
Controle se a libertação da memória simultânea ou a libertação da memória não simultânea é efetuada.

Nota

A libertação da memória simultânea não é suportada em aplicações que executam o emulador WOW64 x86 em sistemas de 64 bits que implementam a arquitetura Intel Itanium (anteriormente denominada IA-64). Para obter mais informações sobre como utilizar WOW64 em sistemas Windows de 64 bits, consulte Executar Aplicações de 32 bits.

Controlar se as assemblagens são carregadas como neutras em domínio.
Obtenha um ponteiro de interface para um ICorRuntimeHost que pode ser utilizado 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 cadeia que descreve a versão do CLR que pretende carregar.

Um número de versão no .NET Framework consiste em quatro partes separadas por períodos: major.minor.build.revision. A cadeia transmitida como pwszVersion tem de começar com o caráter "v" seguido das três primeiras partes do número da versão (por exemplo, "v1.0.1529").

Algumas versões do CLR são instaladas com uma instrução de política que especifica compatibilidade com versões anteriores do CLR. Por predefinição, o shim de arranque avalia pwszVersion as instruções de política e carrega a versão mais recente do runtime compatível com a versão que está a ser pedida. Um anfitrião pode forçar o shim a ignorar a avaliação da política e carregar a versão exata especificada ao pwszVersion transmitir um valor de STARTUP_LOADER_SAFEMODE para o startupFlags parâmetro, conforme descrito abaixo.

Se o autor da chamada especificar nulo para pwszVersion, CorBindToRuntimeEx identifica o conjunto de runtimes instalados cujos números de versão são inferiores ao runtime .NET Framework 4 e carrega a versão mais recente do runtime desse conjunto. Não carregará o .NET Framework 4 ou posterior e falhará se não estiver instalada nenhuma versão anterior. Tenha em atenção que transmitir nulo não dá ao anfitrião qualquer controlo sobre que versão do runtime é carregada. Embora esta abordagem possa ser adequada em alguns cenários, recomenda-se vivamente que o anfitrião forneça uma versão específica para carregar.

pwszBuildFlavor
[in] Uma cadeia 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 está otimizada para tirar partido de vários processadores para libertação da memória e a compilação da estação de trabalho está otimizada para aplicações cliente em execução numa máquina de processador único.

Se pwszBuildFlavor estiver definida como nula, a compilação da estação de trabalho é carregada. Ao executar num computador de processador único, a compilação da estação de trabalho é sempre carregada, mesmo que pwszBuildFlavor esteja definida como svr. No entanto, se pwszBuildFlavor estiver definido como svr e for especificada uma libertação da memória simultânea (veja a descrição do startupFlags parâmetro), a compilação do servidor é carregada.

startupFlags
[in] Uma combinação de valores da enumeração STARTUP_FLAGS . Estes sinalizadores controlam a libertação da memória simultânea, o código neutro do domínio e o comportamento do pwszVersion parâmetro. A predefinição é um domínio único se não estiver definido nenhum sinalizador. 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 destes sinalizadores, veja a enumeração STARTUP_FLAGS .

rclsid
[in] A CLSID da coclasse que implementa a interface ICorRuntimeHost ou ICLRRuntimeHost . Os valores suportados são CLSID_CorRuntimeHost ou CLSID_CLRRuntimeHost.

riid
[in] O IID da interface pedida de rclsid. Os valores suportados são IID_ICorRuntimeHost ou IID_ICLRRuntimeHost.

ppv
[fora] O ponteiro da interface devolvido para riid.

Observações

Se pwszVersion especificar uma versão de runtime que não existe, CorBindToRuntimeEx devolve um valor HRESULT de CLR_E_SHIM_RUNTIMELOAD.

Contexto de Execução e Fluxo da Identidade do Windows

Na versão 1 do CLR, o WindowsIdentity objeto não flui em pontos assíncronos, como novos threads, conjuntos de threads ou chamadas de retorno de temporizador. Na versão 2.0 do CLR, um ExecutionContext objeto molda algumas informações sobre o thread atualmente em execução e flui-o através de qualquer ponto assíncrono, mas não através dos limites do domínio da aplicação. Da mesma forma, o WindowsIdentity objeto também flui através de qualquer ponto assíncrono. Portanto, a representação atual no thread, se existir, também flui.

Pode alterar o fluxo de duas formas:

Ao modificar as ExecutionContext definições para suprimir o fluxo por thread (veja os SuppressFlowmétodos , SuppressFlowe SuppressFlowWindowsIdentity ).
Ao alterar o modo predefinido do processo para o modo de compatibilidade da versão 1, em que o WindowsIdentity objeto não flui em nenhum ponto assíncrono, independentemente das ExecutionContext definições no thread atual. A forma como altera o modo predefinido depende se utiliza um executável gerido ou uma interface de alojamento não gerida para carregar o CLR:
1. Para executáveis geridos, tem de definir o enabled atributo do <elemento legacyImpersonationPolicy> como true.
2. Para interfaces de alojamento não geridas, defina o STARTUP_LEGACY_IMPERSONATION sinalizador no parâmetro ao startupFlags chamar a CorBindToRuntimeEx função.
O modo de compatibilidade da versão 1 aplica-se a todo o processo e a todos os domínios de aplicação no processo.

Requisitos

Plataformas: Veja Requisitos de Sistema.

Cabeçalho: MSCorEE.h

Biblioteca: MSCorEE.dll

.NET Framework Versões: Disponível desde 1.0

Partilhar via