IClrProfiling::AttachProfiler Method

AttachProfiler Method

Collapse All

.NET Framework 4

[This documentation is for preview only, and is subject to change in later releases. Blank topics are included as placeholders.]

Attaches the specified profiler to the specified process.

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

Parameters

dwProfileeProcessID: [in] The process ID of the process to which the profiler should be attached. On a 64-bit machine, the process can be either 32-bit or 64-bit, regardless of the bitness of the trigger process that is calling AttachProfiler. If the user account under which AttachProfiler is called has administrative privileges, the target process may be any process on the system. Otherwise, the target process must be owned by the same user account.
dwMillisecondsMax: [in] The time duration, in milliseconds, to wait for AttachProfiler to complete. The trigger process should pass a timeout that is known to be sufficient for the particular profiler to complete its initialization.
pClsidProfiler: [in] A pointer to the CLSID of the profiler to be loaded. The trigger process can reuse this memory after AttachProfiler returns.
wszProfilerPath: [in] The full path to the profiler’s DLL file to be loaded. This string should contain no more than 260 characters, including the null terminator. If wszProfilerPath is null or an empty string, the common language runtime (CLR) will try to find out the location of the profiler’s DLL file by looking in the registry for the CLSID pointed by pClsidProfiler.
pvClientData: [in] A pointer to data to be passed to the profiler by the ICorProfilerCallback3::InitializeForAttach method. The trigger process can reuse this memory after AttachProfiler returns. If pvClientData is null, cbClientData must be 0 (zero).
cbClientData: [in] The size, in bytes, of the data that pvClientData points to.

Return Value

This method returns the following HRESULTs.

HRESULT	Description
S_OK	The specified profiler has successfully attached to the target process.
CORPROF_E_PROFILER_ALREADY_ACTIVE	There is already a profiler active or attaching to the target process.
CORPROF_E_PROFILER_NOT_ATTACHABLE	The specified profiler does not support attachment. The trigger process may attempt to attach a different profiler.
CORDBG_E_MISSING_DATA_TARGET_INTERFACE	The target process specified by dwProfileeProcessID could not be found.
CORPROF_E_PROFILEE_INCOMPATIBLE_WITH_TRIGGER	Unable to request a profiler attachment because the version of the target process is incompatible with the current process that is calling AttachProfiler.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	The user of the trigger process does not have access to the target process.
HRESULT_FROM_WIN32(ERROR_PRIVILEGE_NOT_HELD)	The user of the trigger process does not have the privileges necessary to attach a profiler to the given target process. The application event log may contain more information.
CORPROF_E_IPC_FAILED	A failure occurred when communicating with the target process. This commonly occurs if the target process was shutting down.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	The target process does not exist or is not running a CLR that supports attachment. This may indicate that the CLR was unloaded since the call to the runtime enumeration method.
HRESULT_FROM_WIN32(ERROR_TIMEOUT)	The timeout expired without beginning to load the profiler. You can retry the attach operation. Timeouts occur because a finalizer in the target process was running for longer than the timeout value.
E_INVALIDARG	One or more parameters have invalid values.
E_FAIL	Some other, unspecified failure occurred.
Other error codes	If the profiler’s ICorProfilerCallback3::InitializeForAttach method returns an HRESULT that indicates failure, AttachProfiler returns that same HRESULT. In this case, E_NOTIMPL is converted to CORPROF_E_PROFILER_NOT_ATTACHABLE.

Remarks

For more information about attaching and detaching profilers, see Profiler Attach and Detach.

Requirements

Platforms: See .NET Framework System Requirements.

Header: CorProf.idl

Library: CorGuids.lib

.NET Framework Versions: 4

Reference

ICorProfilerInfo3 Interface

Other Resources

ICorProfilerCallback

Profiling Interfaces

Profiling (Unmanaged API Reference)