Função CorBindToRuntimeEx

Permite que hosts não gerenciados carreguem o CLR (Common Language Runtime) em um processo. O CorBindToRuntime e CorBindToRuntimeEx as funções executam a mesma operação, mas a CorBindToRuntimeEx função permite que você defina 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:

• Especifique a versão do runtime que será carregada.

• Indique se o build do servidor ou da estação de trabalho deve ser carregado.

• Controlar se a coleta de lixo simultânea ou a coleta de lixo não simultânea é feita.

• Controlar se os assemblies são carregados como neutros no domínio.

• Obtenha 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 cadeia de caracteres que descreve a versão do CLR que você deseja carregar.

Um número de versão no .NET Framework consiste em quatro partes separadas por períodos: major.minor.build.revision. A cadeia de caracteres passou como pwszVersion deve começar com o caractere "v" seguido pelas 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 instrução de política que especifica a compatibilidade com versões anteriores do CLR. Por padrão, o shim de inicialização pwszVersion é avaliado em relação às instruções de política e carrega a versão mais recente do runtime compatível com a versão que está sendo 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 do STARTUP_LOADER_SAFEMODEstartupFlags parâmetro, 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 do .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 nenhuma versão anterior estiver instalada. Observe que passar nulo não fornece 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 o servidor ou a compilação da estação de trabalho do CLR deve ser carregado. Os valores válidos são svr e wks. O build do servidor é otimizado para aproveitar vários processadores para coletas de lixo e o build da estação de trabalho é otimizado para aplicativos cliente em execução em um computador de processador único.

Se pwszBuildFlavor estiver definido como nulo, o build da estação de trabalho será carregado. Ao executar em um computador de processador único, o build da estação de trabalho é sempre carregado, mesmo que pwszBuildFlavor esteja definido como svr. No entanto, se pwszBuildFlavor estiver definido svr como e a coleta de lixo simultânea for especificada (consulte a descrição do startupFlags parâmetro), o build do servidor será carregado.

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 pwszVersion parâmetro. 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] A CLSID da coclasse que implementa o ICorRuntimeHost ou a interface 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.

Observações

Se pwszVersion especificar uma versão de runtime que não existe, CorBindToRuntimeEx retornará 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 entre pontos assíncronos, como novos threads, pools de threads ou retornos de chamada de temporizador. Na versão 2.0 do CLR, um ExecutionContext objeto encapsula algumas informações sobre o thread em execução no momento e o flui em qualquer ponto assíncrono, mas não entre os 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 thread, se houver, também flui.

Você pode alterar o fluxo de duas maneiras:

1. Modificando as ExecutionContext configurações para suprimir o fluxo por thread (consulte o , SuppressFlowe SuppressFlowWindowsIdentity os SuppressFlowmétodos).

2. Alterando o modo padrão 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 configurações no thread atual. A forma 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_IMPERSONATION sinalizador 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 do 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

Consulte também

• Função CorBindToCurrentRuntime
• Função CorBindToRuntime
• Função CorBindToRuntimeByCfg
• Função CorBindToRuntimeHost
• ICorRuntimeHost Interface
• Funções de hospedagem CLR preteridas