ICorProfilerCallback2

Artikel
09/02/2008

Aktualisiert: November 2007

Stellt Methoden bereit, mit denen die Common Language Runtime (CLR) einen Codeprofiler benachrichtigt, wenn die abonnierten Ereignisse des Profilers auftreten. Die ICorProfilerCallback2-Schnittstelle ist eine Erweiterung der ICorProfilerCallback-Schnittstelle. Das heißt, sie stellt neue, in .NET Framework 2.0 eingeführte Rückrufe bereit.

Tipp

Jede Methodenimplementierung muss ein HRESULT zurückgeben, das bei Erfolg den Wert S_OK und bei einem Fehler den Wert E_FAIL aufweist. Die CLR ignoriert derzeit das HRESULT, das von jedem Rückruf außer ICorProfilerCallback::ObjectReferences zurückgegeben wird.

interface ICorProfilerCallback2 : ICorProfilerCallback
{
    HRESULT ThreadNameChanged(
        [in] ThreadID threadId,
        [in] ULONG cchName,
        [in] WCHAR name[]);
    HRESULT GarbageCollectionStarted(
        [in] int cGenerations,
        [in, size_is(cGenerations), length_is(cGenerations)] BOOL generationCollected[],
        [in] COR_PRF_GC_REASON reason);
    HRESULT SurvivingReferences(
        [in]                                    ULONG    cSurvivingObjectIDRanges,
        [in, size_is(cSurvivingObjectIDRanges)] ObjectID objectIDRangeStart[] ,
        [in, size_is(cSurvivingObjectIDRanges)] ULONG    cObjectIDRangeLength[] );
    HRESULT GarbageCollectionFinished();
    HRESULT FinalizeableObjectQueued(
        [in] DWORD finalizerFlags,
        [in] ObjectID objectID);
    HRESULT RootReferences2(
        [in]                     ULONG    cRootRefs,
        [in, size_is(cRootRefs)] ObjectID rootRefIds[],
        [in, size_is(cRootRefs)] COR_PRF_GC_ROOT_KIND rootKinds[],
        [in, size_is(cRootRefs)] COR_PRF_GC_ROOT_FLAGS rootFlags[],
        [in, size_is(cRootRefs)] UINT_PTR rootIds[]);
    HRESULT HandleCreated(
        [in] GCHandleID handleId,
        [in] ObjectID initialObjectId);
    HRESULT HandleDestroyed(
        [in] GCHandleID handleId);
}

Methoden

Methode	Beschreibung
ICorProfilerCallback2::FinalizeableObjectQueued-Methode	Benachrichtigt den Codeprofiler, dass ein Objekt mit einem Finalizer zur Ausführung seiner Finalize-Methode in die Warteschlange des Finalizerthreads gestellt wurde.
ICorProfilerCallback2::GarbageCollectionFinished-Methode	Benachrichtigt den Profiler, dass eine Garbage Collection abgeschlossen und alle zugehörigen Garbage Collection-Rückrufe ausgegeben wurden.
ICorProfilerCallback2::GarbageCollectionStarted-Methode	Benachrichtigt den Codeprofiler, dass eine Garbage Collection gestartet wurde.
ICorProfilerCallback2::HandleCreated-Methode	Benachrichtigt den Codeprofiler, dass ein Garbage Collection-Handle erstellt wurde.
ICorProfilerCallback2::HandleDestroyed-Methode	Benachrichtigt den Codeprofiler, dass ein Garbage Collection-Handle zerstört wurde.
ICorProfilerCallback2::RootReferences2-Methode	Benachrichtigt den Profiler über Stammverweise, nachdem eine Garbage Collection erfolgt ist. Diese Methode ist eine Erweiterung der ICorProfilerCallback::RootReferences-Methode.
ICorProfilerCallback2::SurvivingReferences-Methode	Benachrichtigt den Profiler über Objektverweise, die nach einer Garbage Collection noch vorhanden sind.
ICorProfilerCallback2::ThreadNameChanged-Methode	Benachrichtigt den Codeprofiler, dass sich der Name eines Threads geändert hat.

Hinweise

Die CLR ruft eine Methode in der ICorProfilerCallback-Schnittstelle (oder der ICorProfilerCallback2-Schnittstelle) auf, um den Profiler zu benachrichtigen, wenn ein abonniertes Ereignis des Profilers auftritt. Dies ist die primäre Rückrufschnittstelle, über die die CLR mit dem Codeprofiler kommuniziert.

Ein Codeprofiler muss die Methoden der ICorProfilerCallback-Schnittstelle implementieren. Für .NET Framework, Version 2.0 und höher, muss der Profiler auch die ICorProfilerCallback2-Methoden implementieren. Jede Methodenimplementierung muss ein HRESULT zurückgeben, das bei Erfolg den Wert S_OK und bei einem Fehler den Wert E_FAIL aufweist. Die CLR ignoriert derzeit das HRESULT, das von jedem Rückruf außer ICorProfilerCallback::ObjectReferences zurückgegeben wird.

Ein Codeprofiler muss in der Microsoft Windows-Registrierung sein COM-Objekt registrieren, das die ICorProfilerCallback-Schnittstelle und die ICorProfilerCallback2-Schnittstelle implementiert. Ein Codeprofiler abonniert die Ereignisse, für die er eine Benachrichtigung empfangen möchte, indem er ICorProfilerInfo::SetEventMask aufruft. Dies geschieht in der Regel bei der Implementierung von ICorProfilerCallback::Initialize durch den Profiler. Der Profiler kann dann Benachrichtigungen von der Laufzeit empfangen, wenn demnächst ein Ereignis im gerade ausgeführten Laufzeitprozess auftritt oder aufgetreten ist.

Tipp

Der Profiler registriert ein einzelnes COM-Objekt. Wenn der Profiler auf .NET Framework, Version 1.0 oder 1.1, abzielt, muss das COM-Objekt nur die Methoden von ICorProfilerCallback implementieren. Wenn er auf .NET Framework, Version 2.0 und höher, abzielt, muss das COM-Objekt auch die Methoden von ICorProfilerCallback2 implementieren.

Anforderungen

Plattformen: siehe Systemanforderungen für .NET Framework.

Header: CorProf.idl

Bibliothek: CorGuids.lib

.NET Framework-Versionen: 3.5 SP1, 3.5, 3.0 SP1, 3.0, 2.0 SP1, 2.0

Siehe auch

Referenz

ICorProfilerCallback-Schnittstelle

Weitere Ressourcen

Profilerstellungsschnittstellen

Freigeben über