Funzione CorBindToRuntimeEx

Articolo
09/12/2008

Aggiornamento: novembre 2007

Consente il caricamento di Common Language Runtime in un processo da parte di host non gestiti. Le funzioni CorBindToRuntime e CorBindToRuntimeEx eseguono la stessa operazione, ma la funzione CorBindToRuntimeEx consente di impostare flag per specificare il comportamento di CLR.

Per una descrizione completa degli scenari in cui viene utilizzato il metodo CorBindToRuntimeEx, vedere Hosting di Common Language Runtime.

Questa funzione accetta un insieme di parametri che consentono a un host di effettuare le seguenti operazioni:

Specificare la versione del runtime che verrà caricata.
Indicare se deve essere caricata la build per server o per workstation.
Controllare se viene implementata l'esecuzione simultanea o non simultanea della Garbage Collection.

Nota

L'operazione di Garbage Collection in modalità simultanea non è supportata nelle applicazioni che eseguono l'emulatore WOW64 x86 su sistemi a 64 bit che implementano l'architettura Intel Itanium (precedentemente denominata IA-64). Per ulteriori informazioni sull'utilizzo di WOW64 nei sistemi Windows a 64 bit, vedere Running 32-bit Applications (informazioni in lingua inglese).

Controllare se gli assembly vengono caricati come indipendenti dal dominio.
Ottenere un puntatore a un'interfaccia a un oggetto ICorRuntimeHost che può essere utilizzato per impostare opzioni aggiuntive per la configurazione di un'istanza di Common Language Runtime prima dell'avvio.

HRESULT CorBindToRuntimeEx (
        [in]  LPWSTR    pwszVersion, 
        [in]  LPWSTR    pwszBuildFlavor, 
        [in]  DWORD     startupFlags, 
        [in]  REFCLSID  rclsid, 
        [in]  REFIID    riid, 
        [out] LPVOID*   ppv
);

Parametri

pwszVersion
[in] Stringa che descrive la versione di Common Language Runtime che si desidera caricare.

Un numero di versione in .NET Framework è costituito da quattro parti separate da punti: principale.secondario.build.revisione. La stringa passata come parametro pwszVersion deve iniziare con il carattere "v" seguito dalle prime tre parti del numero di versione (ad esempio, "v1.0.1529").

Alcune versioni di Common Language Runtime vengono installate con un'istruzione dei criteri che specifica la compatibilità con le versioni precedenti di Common Language Runtime. Per impostazione predefinita, lo shim di avvio confronta il valore di pwszVersion con le istruzioni dei criteri e carica l'ultima versione di Common Language Runtime compatibile con la versione richiesta. Un host può imporre allo shim di ignorare la valutazione dei criteri e di caricare l'esatta versione specificata in pwszVersion passando un valore STARTUP_LOADER_SAFEMODE per il parametro startupFlags, come descritto di seguito.

Se il chiamante specifica null nel parametro pwszVersion, verrà caricata la versione più recente del runtime. Se viene passato null, l'host non disporrà di alcun controllo sulla versione del runtime caricata. Sebbene questa soluzione possa risultare appropriata in alcuni scenari, è tuttavia consigliabile che l'host fornisca una specifica versione da caricare.
pwszBuildFlavor
[in] Stringa che specifica se deve essere caricata la build di Common Language Runtime per server o per workstation. I valori validi sono svr e wks. La build per server è ottimizzata per l'utilizzo di più processori durante le operazioni di Garbage Collection, mentre la build per workstation è ottimizzata per le applicazioni client eseguite su computer con singolo processore.

Se pwszBuildFlavor è impostato su null, verrà caricata la build per workstation. In caso di esecuzione su un computer con singolo processore, verrà sempre caricata la build per workstation, anche se il valore pwszBuildFlavor è impostato su svr. Se tuttavia pwszBuildFlavorviene impostato su svr e viene specificata l'esecuzione simultanea della Garbage Collection, come indicato nella descrizione del parametro startupFlags riportata di seguito, verrà caricata la build per server.
startupFlags
[in] Una combinazione di valori dell'enumerazione STARTUP_FLAGS. Questi flag controllano l'esecuzione simultanea della Garbage Collection, il codice indipendente dal dominio e il comportamento del parametro pwszVersion. Se non è impostato nessun flag, l'impostazione predefinita è un dominio singolo. Di seguito vengono illustrati i valori validi.
- STARTUP_CONCURRENT_GC
- STARTUP_LOADER_OPTIMIZATION_SINGLE_DOMAIN
- STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN
- STARTUP_LOADER_OPTIMIZATION_MULTI_DOMAIN_HOST
- STARTUP_LOADER_SAFEMODE
- STARTUP_LEGACY_IMPERSONATION
- STARTUP_LOADER_SETPREFERENCE
- STARTUP_SERVER_GC
- STARTUP_HOARD_GC_VM
- STARTUP_SINGLE_VERSION_HOSTING_INTERFACE
- STARTUP_LEGACY_IMPERSONATION
- STARTUP_DISABLE_COMMITTHREADSTACK
- STARTUP_ALWAYSFLOW_IMPERSONATION
Per le descrizioni di questi flag, vedere l'enumerazione STARTUP_FLAGS.
rclsid
[in] CLSID della coclasse che implementa l'interfaccia ICorRuntimeHost. I valori supportati sono CLSID_CorRuntimeHost o CLSID_CLRRuntimeHost.
riid
[in] IID dell'interfaccia richiesta da rclsid. I valori supportati sono IID_ICorRuntimeHost o IID_ICLRRuntimeHost.
ppv
[out] Puntatore a interfaccia restituito per riid.

Note

Se il parametro pwszVersion specifica una versione di runtime che non esiste, la funzione CorBindToRuntimeEx restituisce un valore HRESULT di CLR_E_SHIM_RUNTIMELOAD.

Contesto di esecuzione e flusso dell'identità Windows

Nella versione 1 di Common Language Runtime, l'oggetto WindowsIdentity non passa da un punto asincrono all'altro, intendendo per punti asincroni i nuovi thread, i pool di thread o i callback del timer. Nella versione 2.0 di Common Language Runtime un oggetto ExecutionContext esegue il wrapping di alcune informazioni sul thread attualmente in esecuzione e ne effettua il passaggio tra punti asincroni qualsiasi, ma non attraverso i limiti del dominio dell'applicazione. Analogamente, anche l'oggetto WindowsIdentity passa da un punto asincrono all'altro. Viene pertanto passata anche l'eventuale rappresentazione corrente sul thread.

È possibile alterare il passaggio in due modi:

Modificando le impostazioni ExecutionContext per eliminare il flusso per i singoli thread. Vedere i metodi SuppressFlow, SuppressFlow e SuppressFlowWindowsIdentity.
Impostando la modalità predefinita del processo sulla modalità di compatibilità con la versione 1, in cui l'oggetto WindowsIdentity non passa tra punti asincroni qualsiasi, indipendentemente dalle impostazioni ExecutionContext sul thread corrente. Il ricorso all'uno o all'altro sistema per cambiare la modalità predefinita dipende dal fatto che si utilizzi un eseguibile gestito o un'interfaccia di hosting non gestita per caricare Common Language Runtime:
1. Per gli eseguibili gestiti, è necessario impostare l'attributo del parametro enabled dell'elemento <legacyImpersonationPolicy> su true.
2. Per le interfacce di hosting non gestite, impostare il flag STARTUP_LEGACY_IMPERSONATION nel parametro startupFlags al momento della chiamata alla funzione CorBindToRuntimeEx.
La modalità di compatibilità con la versione 1 si applica all'intero processo e a tutti i domini applicazione nel processo.