ICorProfilerCallback2

2008-08-18

更新：2007 年 11 月

提供公共语言运行库 (CLR) 在代码探查器订阅的事件发生时用来通知该探查器的方法。ICorProfilerCallback2 接口是对 ICorProfilerCallback 接口的扩展。也就是说，它提供了 .NET Framework 2.0 版中引入的新回调。

说明：
每个方法实现都必须返回一个 HRESULT，如果成功，则它的值为 S_OK，否则它的值为 E_FAIL。目前，CLR 会忽略每个回调（ICorProfilerCallback::ObjectReferences 除外）返回的 HRESULT。

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);
}

方法

方法	说明
ICorProfilerCallback2::FinalizeableObjectQueued 方法	通知代码探查器某个具有终结器的对象已排入队列，等待终结器线程执行其 Finalize 方法。
ICorProfilerCallback2::GarbageCollectionFinished 方法	通知探查器已完成垃圾回收并为其发出了所有垃圾回收回调。
ICorProfilerCallback2::GarbageCollectionStarted 方法	通知代码探查器已启动垃圾回收。
ICorProfilerCallback2::HandleCreated 方法	通知代码探查器已创建某个垃圾回收句柄。
ICorProfilerCallback2::HandleDestroyed 方法	通知代码探查器某个垃圾回收句柄已销毁。
ICorProfilerCallback2::RootReferences2 方法	通知探查器有关在发生垃圾回收后进行的根引用的信息。此方法是对 ICorProfilerCallback::RootReferences 方法的扩展。
ICorProfilerCallback2::SurvivingReferences 方法	通知探查器有关在垃圾回收中保留下来的对象引用的信息。
ICorProfilerCallback2::ThreadNameChanged 方法	通知代码探查器线程的名称已更改。

备注

当探查器订阅的事件发生时，CLR 将调用 ICorProfilerCallback（或 ICorProfilerCallback2）接口中的方法来通知该探查器。这是 CLR 用来与代码探查器通信的主回调接口。

代码探查器必须实现 ICorProfilerCallback 接口的方法。对于 .NET Framework 2.0 版及更高版本，该探查器还必须实现 ICorProfilerCallback2 方法。每个方法实现都必须返回一个 HRESULT，如果成功，则它的值为 S_OK，否则它的值为 E_FAIL。目前，CLR 会忽略每个回调（ICorProfilerCallback::ObjectReferences 除外）返回的 HRESULT。

代码探查器必须在 Microsoft Windows 注册表中注册其实现 ICorProfilerCallback 和 ICorProfilerCallback2 接口的 COM 对象。代码探查器通过调用 ICorProfilerInfo::SetEventMask 来订阅需要接收其相关通知的事件。此操作通常在探查器实现 ICorProfilerCallback::Initialize 时完成。这样，当执行中的运行库进程内即将发生或已发生某个事件时，探查器便能收到来自该运行库的通知。

说明：
探查器注册单个 COM 对象。如果探查器面向的是 .NET Framework 1.0 或 1.1 版，则该 COM 对象仅需实现 ICorProfilerCallback 的方法。如果探查器面向的是 .NET Framework 2.0 版及更高版本，则该 COM 对象还必须实现 ICorProfilerCallback2 的方法。

要求

**平台：**请参见 .NET Framework 系统要求。

**头文件：**CorProf.idl

**库：**CorGuids.lib

**.NET Framework 版本：**3.5 SP1、3.5、3.0 SP1、3.0、2.0 SP1、2.0

请参见

参考

ICorProfilerCallback

其他资源

分析接口