ICLRProfiling::AttachProfiler メソッド

[アーティクル]
05/09/2023

指定されたプロファイラーを、指定されたプロセスにアタッチします。

構文

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 以降で使用可能

次の方法で共有

ICLRProfiling::AttachProfiler メソッド

構文

パラメーター

戻り値

解説

メモリ管理

要件

関連項目

その他のリソース