Метод ICLRProfiling::AttachProfiler

Статья
08/11/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] Идентификатор процесса, к которому должен быть подключен профилировщик. На 64-разрядных компьютерах разрядность процесса профилирования должна совпадать с разрядностью триггерного процесса, который вызывает AttachProfiler. Если учетная запись пользователя, от имени которой вызывается метод AttachProfiler, обладает административными привилегиями, целевым процессом может быть любой процесс в системе. В противном случае целевой процесс должен принадлежать той же учетной записи пользователя.
dwMillisecondsMax
[in] Длительность (в миллисекундах) для завершения AttachProfiler. Активирующий процесс должен передать время ожидания, достаточное для того, чтобы конкретный профилировщик завершил свою инициализацию.
pClsidProfiler
[in] Указатель на идентификатор CLSID загружаемого профилировщика. Активизирующий процесс может повторно использовать эту память после возврата метода AttachProfiler.
wszProfilerPath
[in] Полный путь к файлу библиотеки DLL загружаемого профилировщика. Данная строка должна содержать не более 260 символов, включая завершающий символ NULL. Если параметр wszProfilerPath имеет значение null или является пустой строкой, среда CLR попытается найти местоположение файла библиотеки DLL профилировщика в реестре с помощью идентификатора CLSID, на который указывает параметр pClsidProfiler.
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 из целевого процесса.