CorBindToRuntimeEx-Funktion

Artikel
06/04/2023

Ermöglicht es nicht verwalteten Hosts, die Common Language Runtime (CLR) in einen Prozess zu laden. Die CorBindToRuntime-Funktion und die CorBindToRuntimeEx-Funktion führen den gleichen Vorgang aus, in der CorBindToRuntimeEx-Funktion können Sie jedoch Flags festlegen, um das Verhalten der CLR anzugeben.

Diese Funktion ist in .NET Framework 4 veraltet.

Diese Funktion verwendet einen Parametersatz, der einem Host die folgenden Aktionen ermöglicht:

Angeben der Version der zu ladenden Common Language Runtime.
Angeben, ob der Serverbuild oder der Arbeitsstationsbuild geladen werden soll.
Steuern, ob die gleichzeitige oder nicht gleichzeitige Garbage Collection ausgeführt wird.

Hinweis

Die gleichzeitige Garbage Collection wird nicht in Anwendungen unterstützt, die den WOW64 x86-Emulator auf 64-Bit-Systemen mit einer Implementierung der Intel Itanium-Architektur (früher als IA-64 bezeichnet) ausführen. Weitere Informationen zur Verwendung von WOW64 auf 64-Bit-Windows-Systemen finden Sie unter Ausführen von 32-Bit-Anwendungen.

Steuern, ob Assemblys als domänenneutral geladen werden.
Einen Schnittstellenzeiger auf einen ICorRuntimeHost abrufen, mit dem zusätzliche Optionen zum Konfigurieren einer Instanz der CLR vor dem Starten festgelegt werden können.

Syntax

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

Parameter

pwszVersion
[in] Eine Zeichenfolge, die die Version der zu ladenden CLR beschreibt.

Eine Versionsnummer in .NET Framework besteht aus vier Teilen, die durch Punkte getrennt sind: major.minor.build.revision. Die als pwszVersion übergebene Zeichenfolge muss mit dem Buchstaben "v" beginnen, auf den die ersten drei Teile der Versionsnummer folgen (z. B. "v1.0.1529").

Einige Versionen der CLR werden mit einer Richtlinienanweisung installiert, welche die Kompatibilität mit früheren Versionen der CLR angibt. In der Standardeinstellung wertet das Startmodul pwszVersion anhand von Richtlinienanweisungen aus und lädt die neueste Version der Common Language Runtime, die mit der angeforderten Version kompatibel ist. Ein Host kann erzwingen, dass das Startmodul die Richtlinienauswertung überspringt und genau die in pwszVersion angegebene Version lädt, indem wie unten beschrieben der Wert STARTUP_LOADER_SAFEMODE für den startupFlags-Parameter übergeben wird.

Wenn der Aufrufer NULL für pwszVersion angibt, identifiziert CorBindToRuntimeEx den Satz der installierten Laufzeiten, deren Versionsnummer niedriger als die .NET Framework 4-Laufzeit ist, und lädt die neueste Version der Laufzeit von diesem Satz. Sie lädt nicht .NET Framework 4 oder höher und schlägt fehl, wenn keine frühere Version installiert ist. Beachten Sie, dass bei einer Übergabe von NULL der Host nicht steuern kann, welche Version der Laufzeit geladen wird. Auch wenn dieser Ansatz in einigen Szenarien angemessen sein kann, wird das Angeben einer bestimmten zu ladenden Version durch den Host dringend empfohlen.

pwszBuildFlavor
[in] Eine Zeichenfolge, die angibt, ob der Serverbuild oder der Arbeitsstationsbuild der CLR geladen werden soll. Gültige Werte sind svr und wks. Der Serverbuild wurde so optimiert, dass mehrere Prozessoren zur Ausführung der Garbage Collection genutzt werden können. Der Arbeitsstationsbuild wurde für die Ausführung von Clientanwendungen auf einem Computer mit einem einzelnen Prozessor optimiert.

Wenn pwszBuildFlavor auf NULL festgelegt wurde, wird automatisch der Arbeitsstationsbuild geladen. Bei der Ausführung auf einem Computer mit einem einzelnen Prozessor wird immer der Arbeitsstationsbuild geladen, selbst wenn pwszBuildFlavor auf svr festgelegt wurde. Wenn jedoch pwszBuildFlavor auf svr festgelegt ist und die gleichzeitige Garbage Collection angegeben wird (siehe Beschreibung des startupFlags-Parameters weiter unten), wird der Serverbuild geladen.

startupFlags
[in] Eine Kombination von Werten der STARTUP_FLAGS-Enumeration. Diese Flags steuern die gleichzeitige Garbage Collection, domänenneutralen Code und das Verhalten des pwszVersion-Parameters. Wenn kein Flag festgelegt ist, gilt als Standardwert die Einzeldomäne. Folgende Werte sind gültig:

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

Beschreibungen dieser Flags finden Sie im Abschnitt zur STARTUP_FLAGS-Enumeration.

rclsid
[in] Die CLSID der Co-Klasse, die entweder die ICorRuntimeHost-Schnittstelle oder die ICLRRuntimeHost-Schnittstelle implementiert. Unterstützte Werte sind "CLSID_CorRuntimeHost" oder "CLSID_CLRRuntimeHost".

riid
[in] Die IID der angeforderten Schnittstelle aus rclsid. Unterstützte Werte sind "IID_ICorRuntimeHost" oder "IID_ICLRRuntimeHost".

ppv
[out] Der zurückgegebene Schnittstellenzeiger auf riid.

Bemerkungen

Wenn pwszVersion eine Laufzeitversion angibt, die nicht vorhanden ist, gibt CorBindToRuntimeEx den HRESULT-Wert CLR_E_SHIM_RUNTIMELOAD zurück.

Ausführungskontext und Übergabe der Windows-Identität

In Version 1 der CLR wird das WindowsIdentity-Objekt nicht über asynchrone Punkte wie neue Threads, Threadpools oder Timerrückrufe übergeben. In Version 2.0 der CLR umschließt ein ExecutionContext-Objekt einige Informationen zum aktuell ausgeführten Thread und übergibt ihn über einen asynchronen Punkt, aber innerhalb der Anwendungsdomäne. Auf ähnliche Weise wird auch das WindowsIdentity-Objekt über einen asynchronen Punkt übergeben. Deshalb wird auch der aktuelle Identitätswechsel auf dem Thread (sofern vorhanden) übergeben.

Sie können den Fluss auf zwei Weisen ändern:

Durch Ändern der ExecutionContext-Einstellungen wird die Übergabe für einzelne Threads unterdrückt (siehe die Methoden SuppressFlow, SuppressFlow und SuppressFlowWindowsIdentity).
Durch Ändern des Prozessstandardmodus in den Kompatibilitätsmodus für Version 1; hier wird das WindowsIdentity-Objekt nicht über asynchrone Punkte übergeben, unabhängig von den ExecutionContext-Einstellungen des aktuellen Threads. Wie der Standardmodus geändert wird, hängt davon ab, ob Sie zum Laden der CLR eine verwaltete ausführbare Datei oder eine nicht verwaltete Hostschnittstelle verwenden:
1. Bei verwalteten ausführbaren Dateien müssen Sie das enabled-Attribut des <legacyImpersonationPolicy>-Elements auf true festlegen.
2. Legen Sie bei nicht verwalteten Hostschnittstellen das STARTUP_LEGACY_IMPERSONATION-Flag im startupFlags-Parameter fest, wenn Sie die CorBindToRuntimeEx-Funktion aufrufen.
Der Kompatibilitätsmodus für Version 1 gilt für den gesamten Prozess und alle Anwendungsdomänen im Prozess.

Anforderungen

Plattformen: Informationen finden Sie unter Systemanforderungen.

Header: MSCorEE.h

Bibliothek: MSCorEE.dll

.NET Framework-Versionen: Seit Version 1.0 verfügbar

Teilen über