ICLRProfiling::AttachProfiler 方法

發行項
08/12/2011

將指定的分析工具附加至指定的處理序。

HRESULT AttachProfiler(
  [in] DWORD dwProfileeProcessID,
  [in] DWORD dwMillisecondsMax,                     // optional
  [in] const CLSID * pClsidProfiler,
  [in] LPCWSTR wszProfilerPath,                     // optional
  [in] size_is(cbClientData)] void * pvClientData,  // optional
  [in] UINT cbClientData);                          // optional

參數

dwProfileeProcessID
[in] 應附加分析工具之處理序的處理序 ID。在 64 位元機器上，已進行程式碼剖析處理序的 Bitness 必須符呼叫 AttachProfiler 之觸發處理序的 Bitness。如果呼叫 AttachProfiler 的使用者帳戶擁有系統管理員權限，則目標處理序可能是系統上的任何處理序。否則，目標處理序必須是相同使用者帳戶所擁有。
dwMillisecondsMax
[in] 等候 AttachProfiler 完成的期間 (以毫秒為單位)。觸發處理序應傳遞已知足以使特定分析工具完成初始化的逾時。
pClsidProfiler
[in] 要載入之分析工具的 CLSID 的指標。 AttachProfiler 傳回後，觸發處理序可以重複使用這個記憶體。
wszProfilerPath
[in] 要載入之分析工具 DLL 檔案的完整路徑。這個字串長度不可超過 260 個字元，包括 null 結束字元在內。如果 wszProfilerPath 為 null 或空白字串，則 Common Language Runtime (CLR) 會查看 pClsidProfiler 所指向之 CLSID 的登錄，以嘗試找出分析工具之 DLL 檔案的位置。
pvClientData
[in] ICorProfilerCallback3::InitializeForAttach 方法要傳遞至分析工具之資料的指標。 AttachProfiler 傳回後，觸發處理序可以重複使用這個記憶體。如果 pvClientData 為 null，則 cbClientData 必須為 0 (零)。
cbClientData
[in] pvClientData 指向的資料大小 (以位元組計)。

傳回值

這個方法會傳回下列 HRESULT。

HRESULT	描述
S_OK	指定的分析工具已成功附加至目標處理序。
CORPROF_E_PROFILER_ALREADY_ACTIVE	已有一個作用中或附加至目標處理序的分析工具。
CORPROF_E_PROFILER_NOT_ATTACHABLE	指定的分析工具不支援附件。觸發處理序可能嘗試附加不同的分析工具。
CORPROF_E_PROFILEE_INCOMPATIBLE_WITH_TRIGGER	無法要求分析工具附件，因為目標處理序的版本與呼叫 AttachProfiler 的目前處理序不相容。
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	觸發處理序的使用者沒有權限可以存取目標處理序。
HRESULT_FROM_WIN32(ERROR_PRIVILEGE_NOT_HELD)	觸發處理序的使用者沒有附加分析工具至指定之目標處理序所需的權限。應用程式事件記錄檔可能包含更多資訊。
CORPROF_E_IPC_FAILED	與目標處理序通訊時發生錯誤。這樣的情形通常發生在目標處理序正在關閉時。
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	目標處理序不存在，或者沒有在執行支援附件的 CLR。這可能表示，自從呼叫執行階段列舉方法後，已卸載 CLR。
HRESULT_FROM_WIN32(ERROR_TIMEOUT)	還沒開始載入分析工具，逾時就已過時。您可以重試附加作業。當目標處理序中的完成項執行的時間超過逾時值時，便會發生逾時。
E_INVALIDARG	一個或多個參數具有無效的值。
E_FAIL	發生某個未指定的其他失敗。
其他錯誤碼	如果分析工具的 ICorProfilerCallback3::InitializeForAttach 方法傳回表示失敗的 HRESULT，則 AttachProfiler 會傳回相同的 HRESULT。在這個情況下，E_NOTIMPL 會轉換成 CORPROF_E_PROFILER_NOT_ATTACHABLE。

備註

如需附加和中斷連結分析工具的詳細資訊，請參閱附加和中斷連結程式碼剖析工具。

記憶體管理

為了配合 COM 慣例，AttachProfiler 的呼叫端 (例如，由程式碼剖析工具開發人員所撰寫的觸發程序程式碼) 會負責配置和取消配置 pvClientData 參數指向之資料的記憶體。當 CLR 執行 AttachProfiler 呼叫時，它會製造 pvClientData 所指向之記憶體的複本，並將其傳送至目標處理序。當目標處理序內的 CLR 接收到自己的 pvClientData 區塊複本時，便會透過InitializeForAttach 方法將區塊傳遞至分析工具，然後再從目標處理序取消配置其 pvClientData 區塊的複本。