ICorProfilerCallback2 Interface
Provides methods that are used by the common language runtime (CLR) to notify a code profiler when the events to which the profiler has subscribed occur. The ICorProfilerCallback2 interface is an extension of the ICorProfilerCallback interface. That is, it provides new callbacks introduced in .NET Framework version 2.0.
Note
Each method implementation must return an HRESULT having a value of S_OK on success or E_FAIL on failure. Currently, the CLR ignores the HRESULT that is returned by each callback except ICorProfilerCallback::ObjectReferences.
Methods
| Method | Description |
|---|---|
| FinalizeableObjectQueued Method | Notifies the code profiler that an object with a finalizer has been queued to the finalizer thread for execution of its Finalize method. |
| GarbageCollectionFinished Method | Notifies the profiler that a garbage collection has completed and all garbage collection callbacks have been issued for it. |
| GarbageCollectionStarted Method | Notifies the code profiler that a garbage collection has started. |
| HandleCreated Method | Notifies the code profiler that a garbage collection handle has been created. |
| HandleDestroyed Method | Notifies the code profiler that a garbage collection handle has been destroyed. |
| RootReferences2 Method | Notifies the profiler about root references after a garbage collection has occurred. This method is an extension of the ICorProfilerCallback::RootReferences method. |
| SurvivingReferences Method | Notifies the profiler about object references that have survived a garbage collection. |
| ThreadNameChanged Method | Notifies the code profiler that the name of a thread has changed. |
Remarks
The CLR calls a method in the ICorProfilerCallback (or ICorProfilerCallback2) interface to notify the profiler when an event, to which the profiler had subscribed, occurs. This is the primary callback interface through which the CLR communicates with the code profiler.
A code profiler must implement the methods of the ICorProfilerCallback interface. For the .NET Framework 2.0 and later versions, the profiler must also implement the ICorProfilerCallback2 methods. Each method implementation must return an HRESULT having a value of S_OK on success or E_FAIL on failure. Currently, the CLR ignores the HRESULT that is returned by each callback except ICorProfilerCallback::ObjectReferences.
A code profiler must register in the Microsoft Windows registry, its COM object that implements the ICorProfilerCallback and ICorProfilerCallback2 interfaces. A code profiler subscribes to the events for which it wants to receive notification by calling ICorProfilerInfo::SetEventMask. This is usually done in the profiler's implementation of ICorProfilerCallback::Initialize. The profiler is then able to receive notification from the runtime when an event is about to occur or has just occurred in an executing runtime process.
Note
The profiler registers a single COM object. If the profiler is targeting .NET Framework version 1.0 or 1.1, that COM object need only implement the methods of ICorProfilerCallback. If it is targeting .NET Framework version 2.0 and later, the COM object must also implement the methods of ICorProfilerCallback2.
Requirements
Platforms: See System Requirements.
Header: CorProf.idl, CorProf.h
Library: CorGuids.lib
.NET Framework Versions: Available since 2.0
