CorBindToRuntimeEx 関数

アンマネージ ホストが共通言語ランタイム (CLR: Common Language Runtime) をプロセスに読み込むことを有効にします。 CorBindToRuntime 関数と CorBindToRuntimeEx 関数は同じ操作を実行しますが、CorBindToRuntimeEx 関数を使用すると、CLR の動作を指定するようにフラグを設定できます。

この関数は、.NET Framework 4 で非推奨になっています。

この関数は、次の操作をホストに許可するパラメーターを受け取ります。

  • 読み込むランタイムのバージョンを指定します。

  • サーバー ビルドまたはワークステーション ビルドのどちらを読み込むのかを指定します。

  • 同時実行ガベージ コレクションを実行するか、または非同時実行ガベージ コレクションを実行するかを制御します。

注意

同時実行ガベージ コレクションは、Intel Itanium アーキテクチャ (以前の IA-64) を実装する 64 ビット システム上で WOW64 x86 エミュレーターを実行しているアプリケーションではサポートされません。 64 ビット Windows システムでの WOW64 の使用に関する詳細については、「32 ビット アプリケーションの実行」を参照してください。

  • アセンブリをドメイン中立として読み込むかどうかを制御します。

  • CLR を起動する前に使用して、そのインスタンスを構成するための追加オプションを設定できる、ICorRuntimeHost へのインターフェイス ポインターを取得します。

構文

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

パラメーター

pwszVersion
[入力] 読み込む CLR のバージョンを示す文字列。

.NET Framework のバージョン番号は、major.minor.build.revision のように、ピリオドで区切られた 4 つの部分で構成されています。 pwszVersion として渡される文字列は、文字 "v" で始まり、バージョン番号の最初の 3 つの部分がその後に続く必要があります (たとえば "v1.0.1529")。

いくつかのバージョンの CLR は、以前のバージョンの CLR との互換性を指定するポリシー ステートメントと共にインストールされています。 既定では、スタートアップ shim により、ポリシー ステートメントに対して pwszVersion が評価され、要求されたバージョンと互換性がある最新バージョンのランタイムが読み込まれます。 ホストは shim に対し、次に示すように pwszVersion パラメーターで値 STARTUP_LOADER_SAFEMODE を渡すことにより、ポリシー評価を省略し、startupFlags で指定されたバージョンとまったく同じバージョンを読み込ませることができます。

呼び出し元が pwszVersion に null を指定した場合、CorBindToRuntimeEx はバージョン番号が .NET Framework 4 ランタイム未満のインストール済みランタイム セットを識別し、そのランタイム セットから最新バージョンのランタイムを読み込みます。 .NET Framework 4 以降は読み込まれず、それ以前のバージョンがインストールされていない場合は失敗します。 null を渡すと、ホストはどのバージョンのランタイムを読み込むかを制御できなくなることに注意してください。 状況によってはこのような方法が適切なこともありますが、読み込むバージョンを特定させておくことを強くお勧めします。

pwszBuildFlavor
[入力] CLR のサーバー ビルドまたはワークステーション ビルドのどちらを読み込むかを指定する文字列。 有効値は svr または wks です。 ワークステーション ビルドはシングルプロセッサ コンピューターでクライアント アプリケーションを実行するために最適化され、サーバー ビルドはガベージ コレクションでマルチ プロセッサを利用するために最適化されています。

pwszBuildFlavor が null に設定されている場合は、ワークステーション ビルドが読み込まれます。 シングルプロセッサ コンピューターで実行するときは、pwszBuildFlavorsvr に設定されている場合でも、常にワークステーション ビルドが読み込まれます。 ただし、pwszBuildFlavorsvr に設定され、同時実行ガベージ コレクションが指定されている場合は (startupFlags パラメーターを参照)、サーバー ビルドが読み込まれます。

startupFlags
[in] STARTUP_FLAGS 列挙体の値の組み合わせ。 これらのフラグは、同時実行ガベージ コレクション、ドメインに中立なコード、および pwszVersion パラメーターの動作を制御します。 どのフラグも設定されていない場合は、既定はシングル ドメインになります。 有効な値は、次のとおりです。

  • 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

これらのフラグの説明については、STARTUP_FLAGS 列挙体を参照してください。

rclsid
[in] ICorRuntimeHost または ICLRRuntimeHost インターフェイスを実装するコクラスの CLSID。 サポートされている値は CLSID_CorRuntimeHost と CLSID_CLRRuntimeHost です。

riid
[入力] 要求された IID のインターフェイスの rclsid。 サポートされている値は IID_ICorRuntimeHost と IID_ICLRRuntimeHost です。

ppv
[出力] 返された riid へのインターフェイス ポインター。

解説

pwszVersion で指定したランタイムのバージョンが存在しない場合は、CorBindToRuntimeEx は CLR_E_SHIM_RUNTIMELOAD の HRESULT 値を返します。

Windows ID の実行コンテキストとフロー

CLR のバージョン 1 では、WindowsIdentity オブジェクトは、新しいスレッド、スレッド プール、タイマー コールバックなどの非同期ポイント間をフローしません。 CLR のバージョン 2.0 では、ExecutionContext オブジェクトは現在実行しているスレッドに関する情報をラップして非同期ポイント間をフローしますが、アプリケーション ドメインの境界を越えることはありません。 同様に、WindowsIdentity オブジェクトもすべての非同期ポイント間をフローします。 したがって、現在スレッドに偽装がある場合は、その偽装もフローします。

2 つの方法のいずれかでフローを変更できます。

  1. ExecutionContext 設定を変更し、スレッド単位ではフローしないようにします (SuppressFlowSuppressFlow、および SuppressFlowWindowsIdentity の各メソッドを参照)。

  2. 処理の既定のモードを、現在のスレッドの WindowsIdentity 設定がどの状態でも ExecutionContext オブジェクトは非同期ポイント間をフローしない、バージョン 1 互換モードに変更します。 既定のモードを変更する方法は、CLR を読み込むときにマネージド実行可能ファイルを使用するか、アンマネージド ホスト インターフェイスを使用するかに応じて異なります。

    1. マネージド実行可能ファイルの場合は、<legacyImpersonationPolicy> 要素の enabled 属性を true に設定する必要があります。

    2. アンマネージ ホスト インターフェイスを使用する場合は、STARTUP_LEGACY_IMPERSONATION 関数を呼び出すときの startupFlags パラメーターに CorBindToRuntimeEx フラグを設定します。

    バージョン 1 互換モードは、その処理全体および処理のすべてのアプリケーション ドメインに適用されます。

必要条件

:システム要件」を参照してください。

ヘッダー: MSCorEE.h

ライブラリ: MSCorEE.dll

.NET Framework のバージョン: 1.0 以降で使用可能

関連項目