CorBindToRuntimeEx, fonction

Article
08/10/2011

Permet à des hôtes non managés de charger le Common Language Runtime (CLR) dans un processus. Les fonctions CorBindToRuntime et CorBindToRuntimeEx exécutent la même opération, mais la fonction CorBindToRuntimeEx vous permet de définir des indicateurs de manière à spécifier le comportement du CLR.

Cette fonction est déconseillée dans le .NET Framework version 4.

Consultez Vue d'ensemble de l'hébergement pour obtenir une description complète des scénarios dans lesquels CorBindToRuntimeEx est utilisée.

Cette fonction utilise un ensemble de paramètres qui permettent à un hôte d'effectuer les actions suivantes :

spécifier la version du runtime qui sera chargée ;
indiquer si la build du serveur ou de la station de travail doit être chargée ;
contrôler si le garbage collection simultané ou le garbage collection non simultané est effectué ;

Remarque
Le garbage collection simultané n'est pas pris en charge dans les applications exécutant l'émulateur WOW64 x86 sur les systèmes 64 bits qui implémentent l'architecture Intel Itanium (anciennement appelée IA-64).Pour plus d'informations sur l'utilisation de WOW64 sur les systèmes Windows 64 bits, consultez Exécution d'applications 32 bits (en anglais).

contrôler si les assemblys sont chargés comme étant indépendants du domaine ;
obtenir un pointeur d'interface vers un ICorRuntimeHost qui permet de définir des options supplémentaires de manière à configurer une instance du CLR avant son démarrage.

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

Paramètres

pwszVersion
[in] Chaîne décrivant la version du CLR à charger.

Dans le .NET Framework, un numéro de version est constitué de quatre parties séparées par des points : major.minor.build.revision. La chaîne passée en tant que pwszVersion doit commencer par le caractère « v » suivi des trois premières parties du numéro de version (par exemple « v1.0.1529 »).

Certaines versions du CLR sont installées avec une instruction de stratégie qui spécifie la compatibilité avec les versions précédentes du CLR. Par défaut, le shim de démarrage évalue pwszVersion en fonction des instructions de stratégie et charge la dernière version du runtime compatible avec la version demandée. Un hôte peut obliger le shim à ignorer l'évaluation de stratégie et à charger la version exacte spécifiée dans pwszVersion en passant une valeur de STARTUP_LOADER_SAFEMODE pour le paramètre startupFlags, comme décrit ci-dessous.

Si l'appelant spécifie null pour pwszVersion, la dernière version du runtime est chargée. Lorsque la valeur null est passée, l'hôte n'a aucun contrôle sur la version du runtime qui est chargée. Bien que cette approche puisse convenir dans certains scénarios, il est fortement recommandé que l'hôte fournisse une version spécifique à charger.
pwszBuildFlavor
[in] Chaîne qui spécifie s'il convient de charger la build du serveur ou de la station de travail du CLR. Les valeurs valides sont svr et wks. La build du serveur est optimisée de manière à utiliser plusieurs processeurs pour les garbage collection, tandis que la build de la station de travail est optimisée pour les applications clientes s'exécutant sur un ordinateur à un seul processeur.

Si la valeur de pwszBuildFlavor est null, la build de la station de travail est chargée. Lors de l'exécution sur un ordinateur à un seul processeur, la build de la station de travail est toujours chargée, même si pwszBuildFlavora pour valeur svr. Toutefois, si pwszBuildFlavora pour valeur svr et qu'un garbage collection simultané est spécifié (consultez la description du paramètre startupFlags ci-dessous), la build du serveur est chargée.
startupFlags
[in] Combinaison de valeurs de l'énumération STARTUP_FLAGS. Ces indicateurs contrôlent le garbage collection simultané, le code indépendant du domaine et le comportement du paramètre pwszVersion. La valeur par défaut est un domaine unique si aucun indicateur n'est défini. Les valeurs suivantes sont valides :
- 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
Pour obtenir la description de ces indicateurs, consultez l'énumération STARTUP_FLAGS.
rclsid
[in] CLSID de la coclasse qui implémente l'interface ICorRuntimeHost ou ICLRRuntimeHost. Les valeurs prises en charge sont CLSID_CorRuntimeHost ou CLSID_CLRRuntimeHost.
riid
[in] IID de l'interface demandée par rclsid. Les valeurs prises en charge sont IID_ICorRuntimeHost ou ID_ICLRRuntimeHost.
ppv
[out] Pointeur d'interface retourné à riid.

Notes

Si pwszVersion spécifie une version du runtime qui n'existe pas, CorBindToRuntimeEx retourne alors une valeur HRESULT de CLR_E_SHIM_RUNTIMELOAD.

Contexte d'exécution et flux de l'identité Windows

Dans la version 1 du CLR, l'objet WindowsIdentity n'est pas transmis entre des points asynchrones (nouveaux threads, pools de threads ou rappels de la minuterie). Dans la version 2.0 du CLR, un objet ExecutionContext encapsule des informations sur le thread en cours d'exécution et les transmet d'un point asynchrone à un autre, mais pas au-delà des limites de domaine d'application. De la même façon, l'objet WindowsIdentity est transmis d'un point asynchrone à un autre. Par conséquent, l'emprunt d'identité actuel sur le thread, le cas échéant, est également transmis.

Vous pouvez changer le flux de deux façons :

En modifiant les paramètres ExecutionContext pour supprimer la transmission thread par thread (consultez les méthodes SuppressFlow, SuppressFlow et SuppressFlowWindowsIdentity).
En remplaçant le mode par défaut du processus par le mode de compatibilité de la version 1, dans lequel l'objet WindowsIdentity n'est pas transmis d'un point asynchrone à un autre, indépendamment des paramètres ExecutionContext sur le thread actuel. La manière dont vous modifiez le mode par défaut dépend de l'utilisation d'un fichier exécutable managé ou d'une interface d'hébergement non managée pour charger le CLR :
1. Pour les fichiers exécutables managés, vous devez affecter true à l'attribut enabled de l'élément <legacyImpersonationPolicy>.
2. Pour les interfaces d'hébergement non managées, définissez les indicateurs STARTUP_LEGACY_IMPERSONATION dans le paramètre startupFlags lors de l'appel de la fonction CorBindToRuntimeEx.
Le mode de compatibilité version 1 s'applique au processus entier et à tous les domaines d'application dans le processus.