ICLRProfiling::AttachProfiler-Methode

Artikel
08/10/2011

Fügt den angegebenen Profiler an den angegebenen Prozess an.

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

Parameter

dwProfileeProcessID
[in] Die Prozess-ID des Prozesses, an den der Profiler angefügt werden soll. Auf einem 64-Bit-Computer muss die Bitanzahl des profilierten Prozesses der Bitanzahl des Triggerprozesses entsprechen, der AttachProfiler aufruft. Wenn das Benutzerkonto, unter dem AttachProfiler aufgerufen wird, über Administratorrechte verfügt, kann der Zielprozess jeder Prozess im System sein. Andernfalls muss der Zielprozess im Besitz des gleichen Benutzerkontos sein.
dwMillisecondsMax
[in] Die Dauer in Millisekunden, bis AttachProfiler abgeschlossen werden soll. Der Triggerprozess sollte ein Timeout überschreiten, von dem bekannt ist, dass es für den Abschluss der Initialisierung des betreffenden Profilers ausreicht.
pClsidProfiler
[in] Ein Zeiger auf die CLSID des Profilers, der geladen werden soll. Der Triggerprozess kann diesen Arbeitsspeicher nach dem Beenden von AttachProfiler wiederverwenden.
wszProfilerPath
[in] Der vollständige Pfad für die DLL-Datei des Profilers, die geladen werden soll. Diese Zeichenfolge darf nicht mehr 260 Zeichen, einschließlich des NULL-Abschlusszeichens, enthalten. Wenn wszProfilerPath NULL oder eine leere Zeichenfolge ist, versucht die Common Language Runtime (CLR), den Speicherort der DLL-Datei des Profilers anhand der Registrierung für die CLSID zu ermitteln, auf die pClsidProfiler zeigt.
pvClientData
[in] Ein Zeiger auf Daten, die von der ICorProfilerCallback3::InitializeForAttach-Methode an den Profiler übergeben werden sollen. Der Triggerprozess kann diesen Arbeitsspeicher nach dem Beenden von AttachProfiler wiederverwenden. Wenn pvClientData NULL ist, muss cbClientData 0 (null) sein.
cbClientData
[in] Die Größe in Bytes der Daten, auf die pvClientData zeigt.

Rückgabewert

Diese Methode gibt die folgenden HRESULTs zurück:

HRESULT	Beschreibungen
S_OK	Der angegebene Profiler wurde erfolgreich an den Zielprozess angefügt.
CORPROF_E_PROFILER_ALREADY_ACTIVE	Es ist bereits ein Profiler aktiv, oder es wird bereits ein Profiler an den Zielprozess angefügt.
CORPROF_E_PROFILER_NOT_ATTACHABLE	Anfügen wird vom angegebenen Profiler nicht unterstützt. Der Triggerprozess versucht möglicherweise, einen anderen Profiler anzufügen.
CORPROF_E_PROFILEE_INCOMPATIBLE_WITH_TRIGGER	Das Anfügen eines Profilers kann nicht angefordert werden, da die Version des Zielprozesses nicht mit dem aktuellen Prozess kompatibel ist, der AttachProfiler aufruft.
HRESULT_FROM_WIN32(ERROR_ACCESS_DENIED)	Der Benutzer des Triggerprozesses hat keinen Zugriff auf den Zielprozess.
HRESULT_FROM_WIN32(ERROR_PRIVILEGE_NOT_HELD)	Der Benutzer des Triggerprozesses verfügt nicht über die erforderlichen Rechte, um einen Profiler an den angegebenen Zielprozess anzufügen. Möglicherweise enthält das Anwendungsereignisprotokoll weitere Informationen.
CORPROF_E_IPC_FAILED	Bei der Kommunikation mit dem Zielprozess ist ein Fehler aufgetreten. Dies geschieht im Allgemeinen, wenn der Zielprozess gerade beendet wurde.
HRESULT_FROM_WIN32(ERROR_FILE_NOT_FOUND)	Der Zielprozess ist nicht vorhanden oder führt keine CLR aus, die Anfügen unterstützt. Dies bedeutet möglicherweise, dass die CLR seit dem Aufruf der Laufzeitenumerationsmethode entladen wurde.
HRESULT_FROM_WIN32(ERROR_TIMEOUT)	Das Timeout ist abgelaufen, ohne dass mit dem Laden des Profilers begonnen wurde. Sie können den Anfügevorgang wiederholen. Timeouts treten auf, wenn ein Finalizer im Zielprozess für einen längeren Zeitraum als durch den Timeoutwert angegeben ausgeführt wird.
E_INVALIDARG	Mindestens ein Parameter verfügt über ungültige Werte.
E_FAIL	Ein anderer, nicht angegebener Fehler ist aufgetreten.
Weitere Fehlercodes	Wenn die die ICorProfilerCallback3::InitializeForAttach-Methode des Profilers ein HRESULT zurückgibt, das einen Fehler angibt, gibt AttachProfiler das gleiche HRESULT zurück. In diesem Fall wird E_NOTIMPL in CORPROF_E_PROFILER_NOT_ATTACHABLE konvertiert.

Hinweise

Weitere Informationen über das Anfügen und Trennen von Profilern finden Sie unter Anfügen und Trennen des Profilers.

Speicherverwaltung

Entsprechend den COM-Konventionen ist der Aufrufer von AttachProfiler (z. B. der vom Profilerentwickler erstellte Triggercode) für das Zuordnen des Arbeitsspeichers und das Freigeben des Speichers für die Daten zuständig, auf die der pvClientData-Parameter zeigt. Wenn CLR den AttachProfiler-Aufruf ausführt, erstellt es eine Kopie des Arbeitsspeichers, auf den pvClientData zeigt und es an den Zielprozess überträgt. Wenn CLR im Zielprozess eine eigene Kopie des pvClientData-Blocks empfängt, übergibt es den Block über die InitializeForAttach-Methode an den Profiler und gibt dann seine Kopie des pvClientData-Blocks aus dem Zielprozess frei.