Método de ICLRProfiling::AttachProfiler

Artigo
08/08/2011

Anexa o profiler especificado para o processo especificado.

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

Parâmetros

dwProfileeProcessID
[in] A ID de processo do processo ao qual o profiler deve ser anexado. Em uma máquina de 64 bits, número de bits do processo perfilado deve corresponder ao número de bits do processo de disparador que está chamando AttachProfiler. Se a conta de usuário sob a qual AttachProfiler é chamado tenha privilégios administrativos, o processo de destino pode ser qualquer processo no sistema. Caso contrário, o processo de destino deve ser pertencente a mesma conta de usuário.
dwMillisecondsMax
[in] O tempo de duração, em milissegundos, para AttachProfiler para concluir. O processo de disparador deve passar um tempo limite que costuma ser suficiente para o criador de perfil específico concluir sua inicialização.
pClsidProfiler
[in] Um ponteiro para o CLSID do profiler para ser carregado. O processo de disparador pode reutilizar essa memória após AttachProfiler retorna.
wszProfilerPath
[in] O caminho completo para o arquivo DLL do criador de perfil a ser carregado. Essa seqüência deve conter não mais de 260 caracteres, incluindo o terminador null. Se wszProfilerPath é nulo ou uma seqüência vazia, o common language runtime (CLR) tentará encontrar o local do arquivo DLL do profiler procurando no registro o CLSID que pClsidProfiler aponta para.
pvClientData
[in] Um ponteiro para os dados a serem passados para o criador de perfil pela ICorProfilerCallback3::InitializeForAttach método. O processo de disparador pode reutilizar essa memória após AttachProfiler retorna. Se pvClientData for nulo, cbClientData deve ser 0 (zero).
cbClientData
[in] O tamanho, em bytes, dos dados que pvClientData aponta para.

Valor de retorno

Esse método retorna os seguintes HRESULTs.

HRESULT	Descrição
S_OK	O criador de perfil especificado tem anexado com êxito para o processo de destino.
CORPROF_E_PROFILER_ALREADY_ACTIVE	Já existe um gerador de perfil ativo ou anexar ao processo de destino.
CORPROF_E_PROFILER_NOT_ATTACHABLE	O criador de perfil especificado não suporta o anexo. O processo de disparador pode tentar anexar um gerador de perfil diferente.
CORPROF_E_PROFILEE_INCOMPATIBLE_WITH_TRIGGER	Não é possível solicitar um anexo do profiler, porque a versão do processo de destino é incompatível com o processo atual que está chamando AttachProfiler.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	O usuário do processo de disparador não tem acesso ao processo de destino.
HRESULT_FROM_WIN32(ERROR_PRIVILEGE_NOT_HELD)	O usuário do processo de disparador não tem os privilégios necessários para anexar um gerador de perfil para o processo de destino fornecido. O log de eventos do aplicativo pode conter mais informações.
CORPROF_E_IPC_FAILED	Ocorreu uma falha ao se comunicar com o processo de destino. Isso geralmente acontece se o processo de destino estava sendo desligado.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	O processo de destino não existe ou não está executando um CLR que suporta o anexo. Isso pode indicar que o CLR foi descarregado desde a chamada para o método de enumeração de tempo de execução.
HRESULT_FROM_WIN32(ERROR_TIMEOUT)	O tempo limite expirou sem início para carregar o profiler. Você pode repetir a operação de anexação. Tempos limite ocorre quando um finalizador no processo de destino é executado por mais tempo que o valor de tempo limite.
E_INVALIDARG	Um ou mais parâmetros têm valores inválidos.
E_FAIL	Ocorreu alguma falha, não especificada.
Outros códigos de erro	Se o criador de perfil ICorProfilerCallback3::InitializeForAttach método retorna um HRESULT que indica falha, AttachProfiler retorna nesse mesmo HRESULT. Nesse caso, E_NOTIMPL é convertido em CORPROF_E_PROFILER_NOT_ATTACHABLE.

Comentários

Para obter mais informações sobre a anexação e desanexação geradores de perfis, consulte Profiler anexar e desanexar.

Gerenciamento de memória

Manter com as convenções de COM, o chamador de AttachProfiler (por exemplo, o código do disparador criados pelo desenvolvedor do profiler) é responsável por alocar e desalocar a memória para os dados que o pvClientData parâmetro aponta para. Quando o CLR executa o AttachProfiler chamada, ele faz uma cópia da memória que pvClientData aponta para e as transmitem para o processo de destino. Quando o CLR dentro do processo de destino recebe sua própria cópia da pvClientData bloco, ele passa o bloco o criador de perfil através a InitializeForAttach método e, em seguida, desaloca sua cópia do pvClientData bloco do processo de destino.