ICLRProfiling::AttachProfiler 方法

项目
05/09/2023

将指定的探查器附加到指定的进程中。

语法

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 位计算机上，被分析进程的位数必须匹配调用 AttachProfiler 的触发进程的位数。如果调用 AttachProfiler 的用户帐户具有管理特权，则目标进程可能是系统上的任何进程。否则，相同的用户帐户必须拥有目标进程。

dwMillisecondsMax
[in] AttachProfiler 完成的持续时间（以毫秒为单位）。触发器进程应传递一个特定探查器足以完成其初始化的已知超时。

pClsidProfiler
[in] 指向要加载的探查器 CLSID 的指针。 AttachProfiler 返回后，触发器进程可重用此内存。

wszProfilerPath
[in] 要加载的探查器 DLL 文件的完整路径。此字符串应包含不超过 260 个字符，包括 null 终止符。如果 wszProfilerPath 为 null 或为空字符串，公共语言运行时 (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 块的副本。

要求

平台：请参阅系统要求。

头文件： CorProf.idl、CorProf.h

库：CorGuids.lib

.NET Framework 版本：自 4 起可用

ICLRProfiling::AttachProfiler 方法

语法

参数

返回值

注解

内存管理

要求

另请参阅

反馈

其他资源