ICLRProfiling::AttachProfiler 메서드

2011-08-09

지정된 프로세스에 특정 프로파일러를 연결합니다.

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 파일에 대한 전체 경로입니다. 이 문자열은 null 종결자를 포함하여 260자를 초과하면 안 됩니다. 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 블록의 복사본 할당을 취소합니다.