CorBindToRuntimeEx, fonction

Article
05/09/2023

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

Cette fonction a été dépréciée dans le .NET Framework 4.

Cette fonction prend un ensemble de paramètres qui permettent à un hôte d’effectuer les opérations suivantes :

Spécifier la version du runtime qui sera chargée.
Indiquer si la build pour serveur ou pour station de travail doit être chargée.
Contrôler si un garbage collection simultané ou un garbage collection non simultané est effectué.

Notes

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

Contrôler si les assemblys sont chargés comme étant indépendants du domaine.
Obtenir un pointeur d’interface vers un ICorRuntimeHost qui peut être utilisé pour définir des options supplémentaires pour configurer une instance du CLR avant son démarrage.

Syntaxe

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

Paramètres

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

Un numéro de version dans le .NET Framework se compose de quatre parties séparées par des points : majeure.mineure.build.révision. La chaîne passée comme 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 déclaration 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 par rapport aux déclarations de la stratégie et charge la version la plus récente du runtime compatible avec la version demandée. Un hôte peut forcer le shim à ignorer l’évaluation de la stratégie et à charger la version exacte spécifiée dans pwszVersion en passant la valeur de STARTUP_LOADER_SAFEMODE pour le paramètre startupFlags, comme décrit ci-dessous.

Si l’appelant spécifie Null pour pwszVersion, CorBindToRuntimeEx identifie l’ensemble des runtimes installés dont les numéros de version sont inférieurs au runtime .NET Framework 4, et charge la version la plus récente du runtime disponible dans cet ensemble. Il ne charge pas le .NET Framework 4 ou ultérieur, et échoue si aucune version antérieure n’est installée. Notez que passer une valeur Null ne donne pas à l’hôte le contrôle de la version du runtime qui est chargée. Bien que cette approche puisse être appropriée 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 faut charger la build pour serveur ou pour station de travail du CLR. Les valeurs valides sont svr et wks. La build pour serveur est optimisée pour tirer parti de plusieurs processeurs pour les garbage collections, et la build de station de travail est optimisée pour les applications clientes s’exécutant sur une machine monoprocesseur.

Si pwszBuildFlavor est défini sur Null, la build pour station de travail est chargée. Lors de l’exécution sur une machine monoprocesseur, la build pour station de travail est toujours chargée, même si pwszBuildFlavor est défini sur svr. Cependant, si pwszBuildFlavor est défini sur svr et qu’un garbage collection simultané est spécifié (consultez la description du paramètre startupFlags), la build pour 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 seul domaine 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_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 une description de ces indicateurs, consultez l’énumération STARTUP_FLAGS.

rclsid
[in] Le CLSID de la coclasse qui implémente le ICorRuntimeHost ou l’interface ICLRRuntimeHost. Les valeurs prises en charge sont CLSID_CorRuntimeHost ou CLSID_CLRRuntimeHost.

riid
[in] IID de l’interface demandée depuis rclsid. Les valeurs prises en charge sont IID_ICorRuntimeHost ou IID_ICLRRuntimeHost.

ppv
[out] Pointeur d’interface retourné vers riid.

Remarques

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

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

Dans la version 1 du CLR, l’objet WindowsIdentity ne circule pas entre des points asynchrones comme des nouveaux threads, des pools de threads ou des rappels du minuteur. Dans la version 2.0 du CLR, un objet ExecutionContext encapsule certaines informations sur le thread en cours d’exécution et les fait circuler vers n’importe quel point asynchrone, mais pas à travers les limites du domaine d’application. De même, l’objet WindowsIdentity circule également vers n’importe quel point asynchrone. Par conséquent, l’éventuel emprunt d’identité actuel sur le thread circule également.

Vous pouvez modifier le flux de deux façons :

En modifiant les paramètres ExecutionContext pour supprimer le flux au niveau d’un thread (consultez les méthodes SuppressFlow, SuppressFlow et SuppressFlowWindowsIdentity).
En changeant le mode de processus par défaut en mode de compatibilité de version 1, où l’objet WindowsIdentity ne circule vers aucun point asynchrone, quels que soient les paramètres ExecutionContext sur le thread actuel. La façon dont vous changez le mode par défaut dépend de ce que vous utilisez un exécutable managé ou une interface d’hébergement non managée pour charger le CLR :
1. Pour les exécutables managés, vous devez définir l’attribut enabled de l’élément <legacyImpersonationPolicy> sur true.
2. Pour les interfaces d’hébergement non managées, définissez l’indicateur STARTUP_LEGACY_IMPERSONATION dans le paramètre startupFlags lors de l’appel de la fonction CorBindToRuntimeEx.
Le mode de compatibilité version 1 s’applique à l’ensemble du processus et à tous les domaines d’application du processus.

Configuration requise

Plateformes : Consultez Configuration requise.

En-tête : MSCorEE.h

Bibliothèque : MSCorEE.dll

Versions de .NET Framework : disponible depuis la version 1.0

Partager via