Função CorBindToRuntimeEx

Permite que hosts não geridos carreguem o tempo de execução da linguagem comum (CLR) num processo. O CorBindToRuntime e CorBindToRuntimeEx as funções realizam a mesma operação, mas a CorBindToRuntimeEx função permite definir flags para especificar o comportamento do CLR.

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

Esta função utiliza um conjunto de parâmetros que permitem ao host fazer o seguinte:

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

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

• Controla se a recolha de lixo concorrente ou não concorrente está feita.

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

• Obtenha um ponteiro de interface para um ICorRuntimeHost que possa ser usado para definir opções adicionais para configurar uma instância do CLR antes de esta 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 [dentro] Uma cadeia que descreve a versão do CLR que queres 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 deve começar com o carácter "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 compatibilidade com versões anteriores do CLR. Por defeito, o shim de arranque avalia pwszVersion com base nas declarações de política e carrega a versão mais recente do runtime compatível com a versão solicitada. Um host pode forçar o shim a saltar a avaliação da política e carregar a versão exata especificada em pwszVersion passando um valor de STARTUP_LOADER_SAFEMODE para o startupFlags parâmetro, conforme descrito abaixo.

Se o chamador especificar null para pwszVersion, CorBindToRuntimeEx identifica o conjunto de runtimes instalados cujos números de versão são inferiores ao do runtime do .NET Framework 4, e carrega a versão mais recente do runtime a partir desse conjunto. Não carrega o .NET Framework 4 ou posterior, e falha se não houver uma versão anterior instalada. Note que passar o null não dá ao anfitrião controlo sobre qual versão do runtime é carregada. Embora esta abordagem possa ser adequada em alguns cenários, recomenda-se fortemente que o host forneça uma versão específica para carregar.

pwszBuildFlavor [dentro] Uma cadeia que especifica se deve carregar o servidor ou a build da estação de trabalho do CLR. Os valores válidos são svr e wks. A versão do servidor está otimizada para tirar partido de múltiplos processadores para recolhas de lixo, e a construção da estação de trabalho está otimizada para aplicações cliente a correr numa máquina de processador único.

Se pwszBuildFlavor estiver definido como nulo, a build da estação de trabalho é carregada. Quando é executado numa máquina de processador único, a compilação da estação de trabalho é sempre carregada, mesmo que pwszBuildFlavor esteja definida para svr. No entanto, se pwszBuildFlavor estiver definido como svr e for especificado o garbage collection concorrente (ver a descrição do startupFlags parâmetro), a build do servidor é carregada.

startupFlags [dentro] Uma combinação de valores da STARTUP_FLAGS enumeração. Estas flags controlam a recolha de lixo concorrente, o código neutro em domínio e o comportamento do pwszVersion parâmetro. O padrão é domínio único se não estiver definida a bandeira. 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 descrições destas bandeiras, veja a enumeração STARTUP_FLAGS .

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

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

ppv [fora] O apontador de interface retornado para riid.

Observações

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

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

Na versão 1 do CLR, o WindowsIdentity objeto não flui através de pontos assíncronos como novos threads, pools de threads ou callbacks de temporizador. Na versão 2.0 do CLR, um ExecutionContext objeto envolve alguma informação sobre o thread em execução e faz-na fluir através de qualquer ponto assíncrono, mas não através dos limites do domínio da aplicação. De forma semelhante, o WindowsIdentity objeto também flui através de qualquer ponto assíncrono. Portanto, a imitação atual no tópico, se existir, também flui.

Pode alterar o fluxo de duas formas:

1. Modificando as ExecutionContext definições para suprimir o fluxo por thread (ver os SuppressFlowmétodos , SuppressFlow, e SuppressFlowWindowsIdentity ).

2. Ao alterar o modo predefinido do processo para o modo de compatibilidade da versão 1, onde o WindowsIdentity objeto não flui através de nenhum ponto assíncrono, independentemente das ExecutionContext definições na thread atual. A forma como alteras o modo padrão depende de usares um executável gerido ou uma interface de alojamento não gerida para carregar o CLR:

   1. Para executáveis geridos, deve definir o enabled atributo do <elemento legacyImpersonationPolicy> para true.

   2. Para interfaces de alojamento não geridas, defina o STARTUP_LEGACY_IMPERSONATION flag no startupFlags parâmetro ao 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 do processo.

Requisitos

Plataformas: Consulte Requisitos do sistema.

Cabeçalho: MSCorEE.h

Biblioteca: MSCorEE.dll

Versões do .NET Framework: Disponível desde 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