CorBindToRuntimeEx, fonctionCorBindToRuntimeEx Function

Permet aux hôtes non managés de charger le common language runtime (CLR) dans un processus.Enables unmanaged hosts to load the common language runtime (CLR) into a process. Les fonctions CorBindToRuntime et CorBindToRuntimeEx effectuent la même opération, mais la CorBindToRuntimeEx fonction vous permet de définir des indicateurs pour spécifier le comportement du CLR.The CorBindToRuntime and CorBindToRuntimeEx functions perform the same operation, but the CorBindToRuntimeEx function allows you to set flags to specify the behavior of the CLR.

Cette fonction a été dépréciée dans le .NET Framework 4.This function has been deprecated in the .NET Framework 4.

Cette fonction prend un ensemble de paramètres qui permettent à un hôte d’effectuer les opérations suivantes :This function takes a set of parameters that allow a host to do the following:

  • Spécifiez la version du runtime qui sera chargée.Specify the version of the runtime that will be loaded.

  • Indiquez si la build du serveur ou de la station de travail doit être chargée.Indicate whether the server or workstation build should be loaded.

  • Contrôler si les garbage collection simultanées garbage collection ou non simultanées sont effectuées.Control whether concurrent garbage collection or non-concurrent garbage collection is done.

Notes

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).Concurrent garbage collection is not supported in applications running the WOW64 x86 emulator on 64-bit systems that implement the Intel Itanium architecture (formerly called 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.For more information about using WOW64 on 64-bit Windows systems, see Running 32-bit Applications.

  • Contrôler si les assemblys sont chargés comme étant indépendants du domaine.Control whether assemblies are loaded as domain-neutral.

  • Obtenez 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.Obtain an interface pointer to an ICorRuntimeHost that can be used to set additional options for configuring an instance of the CLR before it is started.

SyntaxeSyntax

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

ParamètresParameters

pwszVersion
dans Chaîne décrivant la version du CLR que vous souhaitez charger.[in] A string describing the version of the CLR you want to load.

Un numéro de version dans le .NET Framework se compose de quatre parties séparées par des points : major. minor. Build. Revision.A version number in the .NET Framework consists of four parts separated by periods: major.minor.build.revision. La chaîne transmise comme pwszVersion doit commencer par le caractère « v » suivi des trois premières parties du numéro de version (par exemple, « v 1.0.1529 »).The string passed as pwszVersion must start with the character "v" followed by the first three parts of the version number (for example, "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.Some versions of the CLR are installed with a policy statement that specifies compatibility with previous versions of the CLR. Par défaut, le shim de démarrage est évalué par pwszVersion rapport aux instructions de stratégie et charge la version la plus récente du runtime qui est compatible avec la version demandée.By default, the startup shim evaluates pwszVersion against policy statements and loads the latest version of the runtime that is compatible with the version being requested. 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 une valeur STARTUP_LOADER_SAFEMODE pour le startupFlags paramètre, comme décrit ci-dessous.A host can force the shim to skip policy evaluation and load the exact version specified in pwszVersion by passing a value of STARTUP_LOADER_SAFEMODE for the startupFlags parameter, as described below.

Si l’appelant spécifie null pour pwszVersion , CorBindToRuntimeEx identifie le jeu de 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 à partir de ce jeu.If the caller specifies null for pwszVersion, CorBindToRuntimeEx identifies the set of installed runtimes whose version numbers are lower than the .NET Framework 4 runtime, and loads the latest version of the runtime from that set. Il ne chargera pas le .NET Framework 4 ou version ultérieure et échouera si aucune version antérieure n’est installée.It won't load the .NET Framework 4 or later, and fails if no earlier version is installed. Notez que le passage de la valeur null donne à l’hôte aucun contrôle sur la version du runtime qui est chargée.Note that passing null gives the host no control over which version of the runtime is loaded. 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.Although this approach may be appropriate in some scenarios, it is strongly recommended that the host supply a specific version to load.

pwszBuildFlavor
dans Chaîne qui spécifie s’il faut charger le serveur ou la build de station de travail du CLR.[in] A string that specifies whether to load the server or the workstation build of the CLR. Les valeurs valides sont svr et wks.Valid values are svr and wks. La build du serveur est optimisée pour tirer parti de plusieurs processeurs pour les nettoyages de la mémoire, et la build de la station de travail est optimisée pour les applications clientes exécutées sur un ordinateur à un seul processeur.The server build is optimized to take advantage of multiple processors for garbage collections, and the workstation build is optimized for client applications running on a single-processor machine.

Si pwszBuildFlavor a la valeur null, la build de station de travail est chargée.If pwszBuildFlavor is set to null, the workstation build is loaded. Lors de l’exécution sur un ordinateur à un seul processeur, la build de station de travail est toujours chargée, même si pwszBuildFlavor a la valeur svr .When running on a single-processor machine, the workstation build is always loaded, even if pwszBuildFlavor is set to svr. Toutefois, si pwszBuildFlavor a la valeur svr et que garbage collection simultané est spécifié (voir la description du startupFlags paramètre), la build du serveur est chargée.However, if pwszBuildFlavor is set to svr and concurrent garbage collection is specified (see the description of the startupFlags parameter), the server build is loaded.

startupFlags
dans Combinaison de valeurs de l’énumération STARTUP_FLAGS .[in] A combination of values of the STARTUP_FLAGS enumeration. Ces indicateurs contrôlent les garbage collection simultanés, le code indépendant du domaine et le comportement du pwszVersion paramètre.These flags control concurrent garbage collection, domain-neutral code, and the behavior of the pwszVersion parameter. La valeur par défaut est un domaine unique si aucun indicateur n’est défini.The default is single domain if no flag is set. Les valeurs suivantes sont valides :The following values are valid:

  • 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 une description de ces indicateurs, consultez l’énumération STARTUP_FLAGS .For descriptions of these flags, see the STARTUP_FLAGS enumeration.

rclsid
dans CLSIDDe la coclasse qui implémente l’interface ICorRuntimeHost ou ICLRRuntimeHost .[in] The CLSID of the coclass that implements either the ICorRuntimeHost or the ICLRRuntimeHost interface. Les valeurs prises en charge sont CLSID_CorRuntimeHost ou CLSID_CLRRuntimeHost.Supported values are CLSID_CorRuntimeHost or CLSID_CLRRuntimeHost.

riid
dans IIDDe l’interface demandée à partir de rclsid .[in] The IID of the requested interface from rclsid. Les valeurs prises en charge sont IID_ICorRuntimeHost ou IID_ICLRRuntimeHost.Supported values are IID_ICorRuntimeHost or IID_ICLRRuntimeHost.

ppv
à Pointeur d’interface retourné à riid .[out] The returned interface pointer to riid.

RemarquesRemarks

Si pwszVersion spécifie une version du runtime qui n’existe pas, CorBindToRuntimeEx retourne une valeur HRESULT de CLR_E_SHIM_RUNTIMELOAD.If pwszVersion specifies a runtime version that does not exist, CorBindToRuntimeEx returns an HRESULT value of CLR_E_SHIM_RUNTIMELOAD.

Contexte d’exécution et le workflow de l’identité WindowsExecution Context and Flow of Windows Identity

Dans la version 1 du CLR, l' WindowsIdentity objet n’est pas transmis entre des points asynchrones tels que les nouveaux threads, les pools de threads ou les rappels de minuterie.In version 1 of the CLR, the WindowsIdentity object does not flow across asynchronous points such as new threads, thread pools, or timer callbacks. Dans la version 2,0 du CLR, un ExecutionContext objet encapsule des informations sur le thread en cours d’exécution et le transmet sur n’importe quel point asynchrone, mais pas au-delà des limites du domaine d’application.In version 2.0 of the CLR, an ExecutionContext object wraps some information about the currently executing thread and flows it across any asynchronous point, but not across application domain boundaries. De même, l' WindowsIdentity objet circule également sur n’importe quel point asynchrone.Similarly, the WindowsIdentity object also flows across any asynchronous point. Par conséquent, l’emprunt d’identité actuel sur le thread, le cas échéant, est également transmis.Therefore, the current impersonation on the thread, if any, flows too.

Vous pouvez modifier le Flow de deux manières :You can alter the flow in two ways:

  1. En modifiant les ExecutionContext paramètres pour supprimer le workflow pour chaque thread (consultez les SuppressFlow SuppressFlow méthodes, et SuppressFlowWindowsIdentity ).By modifying the ExecutionContext settings to suppress the flow on a per-thread basis (see the SuppressFlow, SuppressFlow, and SuppressFlowWindowsIdentity methods).

  2. En remplaçant le mode de traitement par défaut par le mode de compatibilité de la version 1, où l' WindowsIdentity objet n’est pas transmis sur un point asynchrone, quels que soient les ExecutionContext paramètres du thread en cours.By changing the process default mode to the version 1 compatibility mode, where the WindowsIdentity object does not flow across any asynchronous point, regardless of the ExecutionContext settings on the current thread. La façon dont vous modifiez le mode par défaut varie selon que vous utilisez un exécutable managé ou une interface d’hébergement non managée pour charger le CLR :How you change the default mode depends on whether you use a managed executable or an unmanaged hosting interface to load the CLR:

    1. Pour les exécutables managés, vous devez affecter enabled à l’attribut de l’élément la valeur <legacyImpersonationPolicy> true .For managed executables, you must set the enabled attribute of the <legacyImpersonationPolicy> element to true.

    2. Pour les interfaces d’hébergement non managées, définissez l' STARTUP_LEGACY_IMPERSONATION indicateur dans le startupFlags paramètre lors de l’appel de la CorBindToRuntimeEx fonction.For unmanaged hosting interfaces, set the STARTUP_LEGACY_IMPERSONATION flag in the startupFlags parameter when calling the CorBindToRuntimeEx function.

    Le mode de compatibilité de la version 1 s’applique à l’ensemble du processus et à tous les domaines d’application du processus.The version 1 compatibility mode applies to the entire process and to all the application domains in the process.

Configuration requiseRequirements

Plateformes : Consultez Configuration requise.Platforms: See System Requirements.

En-tête : MSCorEE. hHeader: MSCorEE.h

Bibliothèque : MSCorEE. dllLibrary: MSCorEE.dll

Versions de .NET Framework :Disponible à partir de 1.0Available since 1.0.NET Framework Versions: Disponible à partir de 1.0Available since 1.0

Voir aussiSee also