CorBindToRuntimeEx 函式

發行項
08/21/2008

更新：2007 年 11 月

讓 Unmanaged 主應用程式將 Common Language Runtime (CLR) 載入處理序。CorBindToRuntime 和 CorBindToRuntimeEx 函式都會執行相同的作業，但 CorBindToRuntimeEx 函式可讓您設定旗標以指定 CLR 的行為。

請參閱裝載 Common Language Runtime，取得使用 CorBindToRuntimeEx 案例的完整描述。

這個函式採用一組參數，可讓主應用程式進行下列作業：

指定將載入的執行階段版本。
指示應否載入伺服器或工作站組建 (Build)。
控制是否完成了並行或非並行的記憶體回收。

注意事項：
在實作 Intel Itanium 架構 (之前稱為 IA-64) 的 64 位元系統中，執行 WOW64 x86 模擬器的應用程式並不支援並行記憶體回收。如需在 64 位元 Windows 系統上使用 WOW64 的詳細資訊，請參閱執行 32 位元應用程式 (英文)。

控制是否以定義域中性方式載入組件。
取得 ICorRuntimeHost 的介面指標，用來設定 CLR 執行個體的其他設定選項，然後再啟動它。

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

參數

pwszVersion
[in] 字串，描述您要載入的 CLR 版本。

.NET Framework 中的版本號碼由四個部分所組成 (其間以英文句號分隔)：major.minor.build.revision。當做 pwszVersion 傳遞的字串必須以字元 "v" 開始，後接版本號碼的前三個部分 (例如，v1.0.1529)。

某些 CLR 版本是以原則陳述式安裝，這種陳述式會指定與先前 CLR 版本的相容性。根據預設，啟動 shim 會根據原則陳述式評估 pwszVersion，並載入與所要求版本相容的最新版本的執行階段。主應用程式可以強制 Shim 略過原則評估，並載入 pwszVersion 中所指定的完全相同的版本，方法是針對 startupFlags 參數傳遞 STARTUP_LOADER_SAFEMODE 的值，如下所述。

如果呼叫端將 pwszVersion 指定 null，則會載入最新版的執行階段。傳遞 null 使主應用程式無法控制載入哪個執行階段版本。雖然這個方法在某些案例中是適當的，但仍強烈建議主應用程式提供要載入的特定版本。
pwszBuildFlavor
[in] 字串，指定是要載入 CLR 的伺服器組建還是工作站組建。有效值為 svr 和 wks。伺服器組建經過最佳化，可利用記憶體回收的個處理器，而工作站組建也已經過最佳化，可用於在單一處理器電腦上執行的用戶端應用程式。

如果 pwszBuildFlavor設定為 null，則會載入工作站組建。在單一處理器的電腦上執行時，即使 pwszBuildFlavor是設為 svr，永遠都會載入工作站組建。不過，如果 pwszBuildFlavor設為 svr 並且指定並行的記憶體回收 (請參閱 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 介面之 coclass 的 CLSID。支援的值為 CLSID_CorRuntimeHost或 CLSID_CLRRuntimeHost。
riid
[in] 從 rclsid 要求之介面的 IID。支援的值為 IID_ICorRuntimeHost 或 IID_ICLRRuntimeHost。
ppv
[out] 傳回的 riid 的介面指標。

備註

如果 pwszVersion 指定了不存在的執行階段版本，則 CorBindToRuntimeEx 會傳回 CLR_E_SHIM_RUNTIMELOAD 的 HRESULT 值。

Windows 識別的執行內容和流程

在 CLR 第 1 版中，WindowsIdentity 物件不會跨非同步點流動，例如新執行緒、執行緒集區或計時器回呼。在 CLR 2.0 版中，ExecutionContext 物件會包裝有關正在執行之執行緒的一些資訊，並且跨任何非同步點 (但不在應用程式定義域界限上) 流動。同樣地，WindowsIdentity 物件也會跨任何非同步點流動。因此，執行緒上目前的模擬 (如果有的話) 也會流動。

您可以使用兩種方法來變更流程：

藉由修改 ExecutionContext 設定，以每個執行緒為基準抑制流程 (請參閱 SuppressFlow、SuppressFlow 和 SuppressFlowWindowsIdentity 方法)。
藉由將處理序預設模式變更為第 1 版相容性模式，不論目前執行緒上的 ExecutionContext 設定為何，WindowsIdentity 物件都不會跨任何非同步點流動。如何變更預設模式取決於使用 Managed 可執行檔還是使用 Unmanaged 裝載介面來載入 CLR：
1. 如果是 Managed 可執行檔，則必須將 <legacyImpersonationPolicy> 項目的 enabled 屬性設定為 true。
2. 如果是 Unmanaged 裝載介面，則在呼叫 CorBindToRuntimeEx 函式時，在 startupFlags 參數中設定 STARTUP_LEGACY_IMPERSONATION 旗標。
第 1 版相容性模式便會套用至整個處理序和處理序中的所有應用程式定義域。