ICLRProfiling::AttachProfiler 方法
将指定的探查器附加到指定进程。
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 参数指向的数据的内存。 执行 AttachProfiler 调用后，CLR 将生成 pvClientData 指向的内存的副本，并将其传输到目标进程。 当目标进程内的 CLR 接收其自己的 pvClientData 块副本时，CLR 会通过 InitializeForAttach 方法将块传递给探查器，然后从目标进程释放其 pvClientData 块副本。
要求
**平台：**请参见 .NET Framework 系统要求。
**头文件：**CorProf.idl、CorProf.h
**库：**CorGuids.lib
**.NET Framework 版本：**4