CorBindToRuntimeEx 関数CorBindToRuntimeEx Function

アンマネージ ホストが共通言語ランタイム (CLR: Common Language Runtime) をプロセスに読み込むことを有効にします。Enables unmanaged hosts to load the common language runtime (CLR) into a process. CorBindToRuntimeCorBindToRuntimeEx関数は、同じ操作を実行が、CorBindToRuntimeEx関数では、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.

この関数は、.NET Framework 4 では廃止されました。This function has been deprecated in the .NET Framework 4.

この関数は、次の操作をホストに許可するパラメーターを受け取ります。This function takes a set of parameters that allow a host to do the following:

  • 読み込むランタイムのバージョンを指定します。Specify the version of the runtime that will be loaded.

  • サーバー ビルドまたはワークステーション ビルドのどちらを読み込むのかを指定します。Indicate whether the server or workstation build should be loaded.

  • 同時実行ガベージ コレクションを実行するか、または非同時実行ガベージ コレクションを実行するかを制御します。Control whether concurrent garbage collection or non-concurrent garbage collection is done.

注意

同時実行ガベージ コレクションは、Intel Itanium アーキテクチャ (以前の IA-64) を実装する 64 ビット システム上で WOW64 x86 エミュレーターを実行しているアプリケーションではサポートされません。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). 64 ビット Windows システム上で WOW64 の使用に関する詳細については、次を参照してください。を実行している 32 ビット アプリケーションします。For more information about using WOW64 on 64-bit Windows systems, see Running 32-bit Applications.

  • アセンブリをドメイン中立として読み込むかどうかを制御します。Control whether assemblies are loaded as domain-neutral.

  • インターフェイス ポインターを取得、 ICorRuntimeHostが開始する前に、CLR のインスタンスを構成するための追加のオプションを設定できます。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.

構文Syntax

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

パラメーターParameters

pwszVersion
[入力] 読み込む CLR のバージョンを示す文字列。[in] A string describing the version of the CLR you want to load.

.NET Framework のバージョン番号はピリオドで区切られた 4 つの部分で構成されます: major.minor.build.revisionします。A version number in the .NET Framework consists of four parts separated by periods: major.minor.build.revision. pwszVersion として渡される文字列は、文字 "v" で始まり、バージョン番号の最初の 3 つの部分がその後に続く必要があります (たとえば "v1.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").

いくつかのバージョンの CLR は、以前のバージョンの CLR との互換性を指定するポリシー ステートメントと共にインストールされています。Some versions of the CLR are installed with a policy statement that specifies compatibility with previous versions of the CLR. 既定では、スタートアップ shim により、ポリシー ステートメントに対して pwszVersion が評価され、要求されたバージョンと互換性がある最新バージョンのランタイムが読み込まれます。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. ホストは shim に対し、次に示すように pwszVersion パラメーターで値 STARTUP_LOADER_SAFEMODE を渡すことにより、ポリシー評価を省略し、startupFlags で指定されたバージョンとまったく同じバージョンを読み込ませることができます。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.

呼び出し元が pwszVersion に null を指定した場合、CorBindToRuntimeEx はバージョン番号が .NET Framework 4 ランタイム未満のインストール済みランタイム セットを識別し、そのランタイム セットから最新バージョンのランタイムを読み込みます。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. .NET Framework 4 以降は読み込まれず、それ以前のバージョンがインストールされていない場合は失敗します。It won't load the .NET Framework 4 or later, and fails if no earlier version is installed. null を渡すと、ホストはどのバージョンのランタイムを読み込むかを制御できなくなることに注意してください。Note that passing null gives the host no control over which version of the runtime is loaded. 状況によってはこのような方法が適切なこともありますが、読み込むバージョンを特定させておくことを強くお勧めします。Although this approach may be appropriate in some scenarios, it is strongly recommended that the host supply a specific version to load.

pwszBuildFlavor
[入力] CLR のサーバー ビルドまたはワークステーション ビルドのどちらを読み込むかを指定する文字列。[in] A string that specifies whether to load the server or the workstation build of the CLR. 有効値は svr または wks です。Valid values are svr and wks. ワークステーション ビルドはシングルプロセッサ コンピューターでクライアント アプリケーションを実行するために最適化され、サーバー ビルドはガベージ コレクションでマルチ プロセッサを利用するために最適化されています。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.

場合pwszBuildFlavorに設定されている null の場合、ワークステーション ビルドが読み込まれます。If pwszBuildFlavor is set to null, the workstation build is loaded. シングル プロセッサ コンピューターでを実行するときに常にワークステーション ビルドが読み込まれて、たとえpwszBuildFlavorに設定されているsvrします。When running on a single-processor machine, the workstation build is always loaded, even if pwszBuildFlavor is set to svr. ただし場合、pwszBuildFlavorに設定されているsvrと同時実行ガベージ コレクションの指定 (の説明を参照して、startupFlagsパラメーター)、サーバー ビルドが読み込まれます。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
[in]値の組み合わせ、 STARTUP_FLAGS列挙体。[in] A combination of values of the STARTUP_FLAGS enumeration. これらのフラグは、同時実行ガベージ コレクション、ドメインに中立なコード、および pwszVersion パラメーターの動作を制御します。These flags control concurrent garbage collection, domain-neutral code, and the behavior of the pwszVersion parameter. どのフラグも設定されていない場合は、既定はシングル ドメインになります。The default is single domain if no flag is set. 有効な値は、次のとおりです。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

これらのフラグの説明については、次を参照してください。、 STARTUP_FLAGS列挙体。For descriptions of these flags, see the STARTUP_FLAGS enumeration.

rclsid
[in]CLSIDのいずれかを実装するコクラスのICorRuntimeHostまたはICLRRuntimeHostインターフェイス。[in] The CLSID of the coclass that implements either the ICorRuntimeHost or the ICLRRuntimeHost interface. サポートされている値は CLSID_CorRuntimeHost と CLSID_CLRRuntimeHost です。Supported values are CLSID_CorRuntimeHost or CLSID_CLRRuntimeHost.

riid
[入力] 要求された IID のインターフェイスの rclsid[in] The IID of the requested interface from rclsid. サポートされている値は IID_ICorRuntimeHost と IID_ICLRRuntimeHost です。Supported values are IID_ICorRuntimeHost or IID_ICLRRuntimeHost.

ppv
[出力] 返された riid へのインターフェイス ポインター。[out] The returned interface pointer to riid.

RemarksRemarks

pwszVersion で指定したランタイムのバージョンが存在しない場合は、CorBindToRuntimeEx は CLR_E_SHIM_RUNTIMELOAD の HRESULT 値を返します。If pwszVersion specifies a runtime version that does not exist, CorBindToRuntimeEx returns an HRESULT value of CLR_E_SHIM_RUNTIMELOAD.

Windows ID の実行コンテキストとフローExecution Context and Flow of Windows Identity

CLR のバージョン 1 では、WindowsIdentity オブジェクトは、新しいスレッド、スレッド プール、タイマー コールバックなどの非同期ポイント間をフローしません。In version 1 of the CLR, the WindowsIdentity object does not flow across asynchronous points such as new threads, thread pools, or timer callbacks. CLR のバージョン 2.0 では、ExecutionContext オブジェクトは現在実行しているスレッドに関する情報をラップして非同期ポイント間をフローしますが、アプリケーション ドメインの境界を越えることはありません。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. 同様に、WindowsIdentity オブジェクトもすべての非同期ポイント間をフローします。Similarly, the WindowsIdentity object also flows across any asynchronous point. したがって、現在スレッドに偽装がある場合は、その偽装もフローします。Therefore, the current impersonation on the thread, if any, flows too.

2 つの方法のいずれかでフローを変更できます。You can alter the flow in two ways:

  1. ExecutionContext 設定を変更し、スレッド単位ではフローしないようにします (SuppressFlowSuppressFlow、および SuppressFlowWindowsIdentity の各メソッドを参照)。By modifying the ExecutionContext settings to suppress the flow on a per-thread basis (see the SuppressFlow, SuppressFlow, and SuppressFlowWindowsIdentity methods).

  2. 処理の既定のモードを、現在のスレッドの WindowsIdentity 設定がどの状態でも ExecutionContext オブジェクトは非同期ポイント間をフローしない、バージョン 1 互換モードに変更します。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. 既定のモードを変更する方法は、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. マネージ実行可能ファイル、設定する必要があります、enabledの属性、 <legacyImpersonationPolicy >要素trueします。For managed executables, you must set the enabled attribute of the <legacyImpersonationPolicy> element to true.

    2. アンマネージ ホスト インターフェイスを使用する場合は、STARTUP_LEGACY_IMPERSONATION 関数を呼び出すときの startupFlags パラメーターに CorBindToRuntimeEx フラグを設定します。For unmanaged hosting interfaces, set the STARTUP_LEGACY_IMPERSONATION flag in the startupFlags parameter when calling the CorBindToRuntimeEx function.

    バージョン 1 互換モードは、その処理全体および処理のすべてのアプリケーション ドメインに適用されます。The version 1 compatibility mode applies to the entire process and to all the application domains in the process.

必要条件Requirements

プラットフォーム: システム要件に関するページを参照してください。Platforms: See System Requirements.

ヘッダー: MSCorEE.hHeader: MSCorEE.h

ライブラリ: MSCorEE.dllLibrary: MSCorEE.dll

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

関連項目See also