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.

  • CLR のインスタンスを開始する前に構成するための追加オプションを設定するために使用できる、 ICorRuntimeHostへのインターフェイスポインターを取得します。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 つの部分で構成されます。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. ただし、がpwszBuildFlavorsvr設定され、同時実行ガベージコレクションが指定されている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
から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
から ICorRuntimeHost またはICLRRuntimeHostのいずれかのインターフェイスを実装するコクラスの。CLSID[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.dllHeader: 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