ICLRProfiling::AttachProfiler-Methode

Artikel
06/01/2023

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

Syntax

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, von dem AttachProfiler aufgerufen wird. 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 desselben Benutzerkontos sein.

dwMillisecondsMax
[in] Die Dauer in Millisekunden, bis AttachProfiler abgeschlossen sein soll. Der Triggerprozess sollte ein Timeout übergeben, 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 wiederverwenden, nachdem AttachProfiler beendet wurde.

wszProfilerPath
[in] Der vollständige Pfad zur DLL-Datei des Profilers, der geladen werden soll. Diese Zeichenfolge darf, einschließlich des NULL-Abschlusszeichens, nicht mehr als 260 Zeichen enthalten. Wenn wszProfilerPath gleich NULL oder eine leere Zeichenfolge ist, versucht die Common Language Runtime (CLR), den Speicherort der DLL-Datei des Profilers zu ermitteln, indem sie in der Registrierung nach der CLSID von diesem pClsidProfiler sucht.

pvClientData
[in] Ein Zeiger auf die Daten, die von der ICorProfilerCallback3::InitializeForAttach-Methode an den Profiler übergeben werden sollen. Der Triggerprozess kann diesen Arbeitsspeicher wiederverwenden, nachdem AttachProfiler beendet wurde. Wenn pvClientData gleich NULL ist, muss cbClientData gleich 0 (null) sein.

cbClientData
[in] Die Größe der Daten in Bytes, auf die pvClientData verweist.

Rückgabewert

Diese Methode gibt die folgenden HRESULTs zurück.

HRESULT	BESCHREIBUNG
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, von dem `AttachProfiler` aufgerufen wird.
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 hat nicht die erforderlichen Rechte, um einen Profiler an den angegebenen Zielprozess anzufügen. Das Anwendungsereignisprotokoll enthält möglicherweise weitere Informationen.
CORPROF_E_IPC_FAILED	Fehler bei der Kommunikation mit dem Zielprozess. Dies geschieht häufig, wenn der Zielprozess heruntergefahren 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 kann darauf hinweisen, dass die CLR seit dem Aufruf von der Runtime-Enumerationsmethode 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 hat ungültige Werte.
E_FAIL	Ein anderer, nicht angegebener Fehler ist aufgetreten.
Sonstige Fehlercodes	Wenn die ICorProfilerCallback3::InitializeForAttach-Methode des Profilers ein HRESULT zurückgibt, das einen Fehler angibt, gibt `AttachProfiler` dasselbe HRESULT zurück. In diesem Fall wird E_NOTIMPL in CORPROF_E_PROFILER_NOT_ATTACHABLE konvertiert.

Bemerkungen

Speicherverwaltung

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

Anforderungen

Plattformen: Informationen finden Sie unter Systemanforderungen.

Header: CorProf.idl, CorProf.h

Bibliothek: CorGuids.lib

.NET Framework-Versionen: Seit Version 4 verfügbar.

Freigeben über