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 ファイルへの完全パス。 この文字列に含める文字数は、null 終端文字も含めて 260 文字以内にする必要があります。 wszProfilerPath が null または空の文字列である場合、共通言語ランタイム (CLR: Common Language Runtime) は、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 1 つ以上のパラメーターの値が無効です。
E_FAIL 他の何らかの未指定のエラーが発生しました。
その他のエラー コード プロファイラーの ICorProfilerCallback3::InitializeForAttach メソッドが、エラーを示す HRESULT を返す場合、AttachProfiler は、それと同じ HRESULT を返します。 この場合、E_NOTIMPL は CORPROF_E_PROFILER_NOT_ATTACHABLE に変換されます。

解説

メモリ管理

COM 規則に従うと、pvClientData パラメーターが示すデータのメモリの割り当てと割り当て解除の責任は AttachProfiler の呼び出し元 (たとえば、プロファイラーの開発者が作成したトリガー コード) にあります。 CLR は AttachProfiler の呼び出しを実行するときに、pvClientData が示すメモリをコピーし、それを対象プロセスに送信します。 対象プロセス内の CLR が pvClientData ブロックのコピーを受信すると、InitializeForAttach メソッドを通じてプロファイラーにそのブロックを渡してから、対象プロセスから pvClientData ブロックのコピーを解放します。

要件

:「システム要件」を参照してください。

ヘッダー : CorProf.idl、CorProf.h

ライブラリ: CorGuids.lib

.NET Framework のバージョン: 4 以降で使用可能

関連項目