Microsoft.Diagnostics.NETCore.Client API

项目
10/02/2024

本部分介绍诊断客户端库 API。

DiagnosticsClient 类

public DiagnosticsClient
{
    public DiagnosticsClient(int processId);

    public EventPipeSession StartEventPipeSession(
        IEnumerable<EventPipeProvider> providers,
        bool requestRundown = true,
        int circularBufferMB = 256);

    public Task<EventPipeSession> StartEventPipeSessionAsync(
        IEnumerable<EventPipeProvider> providers,
        bool requestRundown,
        int circularBufferMB = 256,
        CancellationToken token = default);

    public void WriteDump(
        DumpType dumpType,
        string dumpPath,
        bool logDumpGeneration = false);

    public async Task WriteDumpAsync(
        DumpType dumpType,
        string dumpPath,
        bool logDumpGeneration,
        CancellationToken token);

    public void AttachProfiler(
        TimeSpan attachTimeout,
        Guid profilerGuid,
        string profilerPath,
        byte[] additionalData = null);

    public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

    public void ResumeRuntime();

    public void SetEnvironmentVariable(
        string name,
        string value);

    public Dictionary<string, string> GetProcessEnvironment();

    public static IEnumerable<int> GetPublishedProcesses();
}

构造函数

public DiagnosticsClient(int processId);

为使用进程 ID processId 运行的兼容 .NET 进程创建新实例 DiagnosticsClient。

processID：目标应用程序的进程 ID。

StartEventPipeSession 方法

public EventPipeSession StartEventPipeSession(
    IEnumerable<EventPipeProvider> providers,
    bool requestRundown = true,
    int circularBufferMB = 256);
public Task<EventPipeSession> StartEventPipeSessionAsync(
    IEnumerable<EventPipeProvider> providers,
    bool requestRundown,
    int circularBufferMB = 256,
    CancellationToken token = default);

使用给定提供程序和设置启动 EventPipe 跟踪会话。

providers：要开始跟踪的 EventPipeProvider 的 IEnumerable。
requestRundown：一个 bool，用于指定是否应请求来自目标应用运行时的断开提供程序事件。
circularBufferMB：一个 int，用于指定目标应用运行时在收集事件时使用的循环缓冲区的总大小。
token（对于异步重载）：用于监视取消请求的令牌。

public EventPipeSession StartEventPipeSession(EventPipeProvider provider, bool requestRundown = true, int circularBufferMB = 256)
public Task<EventPipeSession> StartEventPipeSessionAsync(EventPipeProvider provider, bool requestRundown, int circularBufferMB = 256, CancellationToken token = default)

provider：要开始跟踪的 EventPipeProvider。
requestRundown：一个 bool，用于指定是否应请求来自目标应用运行时的断开提供程序事件。
circularBufferMB：一个 int，用于指定目标应用运行时在收集事件时使用的循环缓冲区的总大小。
token（适用于异步重载）：用于监视取消请求的令牌。

注意

断开事件包含可能需要用于后期分析的有效负载，如解析线程示例的方法名称。除非知道不需要此内容，否则建议将 requestRundown 设置为 true。在大型应用程序中，这可能需要一段时间。

WriteDump 方法

public void WriteDump(
    DumpType dumpType,
    string dumpPath,
    bool logDumpGeneration=false);

请求转储以事后调试目标应用程序。可以使用 DumpType 枚举指定转储类型。

dumpType：要请求的转储类型。
dumpPath：要写出到其中的转储的路径。
logDumpGeneration：如果设置为 true，则目标应用程序将在转储生成期间写出诊断日志。

public void WriteDump(DumpType dumpType, string dumpPath, WriteDumpFlags flags)

请求转储以事后调试目标应用程序。可以使用 DumpType 枚举指定转储类型。

dumpType：要请求的转储类型。
dumpPath：要写出到其中的转储的路径。
flags：日志记录和故障报告标志。在低于 6.0 的运行时上，仅支持 LoggingEnabled。

public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, bool logDumpGeneration, CancellationToken token)

请求转储以事后调试目标应用程序。可以使用 DumpType 枚举指定转储类型。

dumpType：要请求的转储类型。
dumpPath：要写出到其中的转储的路径。
logDumpGeneration：如果设置为 true，则目标应用程序将在转储生成期间写出诊断日志。
token：要监视取消请求的标记。

public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, WriteDumpFlags flags, CancellationToken token)

请求转储以事后调试目标应用程序。可以使用 DumpType 枚举指定转储类型。

dumpType：要请求的转储类型。
dumpPath：要写出到其中的转储的路径。
flags：日志记录和故障报告标志。在低于 6.0 的运行时上，仅支持 LoggingEnabled。
token：要监视取消请求的标记。

AttachProfiler 方法

public void AttachProfiler(
    TimeSpan attachTimeout,
    Guid profilerGuid,
    string profilerPath,
    byte[] additionalData=null);

请求将 ICorProfiler 附加到目标应用程序。

attachTimeout：将在其后中止附加的 TimeSpan。
profilerGuid：要附加的 ICorProfiler 的 Guid。
profilerPath：要附加的 ICorProfiler dll 的路径。
additionalData：在探查器附加过程中可传递给运行时的可选其他数据。

SetStartupProfiler 方法

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

将探查器设置为启动探查器。只有在启动时暂停运行时发出此命令才有效。

profilerGuid：要附加的探查器的 Guid。
profilerPath：要附加的探查器的路径。

ResumeRuntime 方法

public void ResumeRuntime();

通知运行时在启动时暂停后恢复执行。

SetEnvironmentVariable 方法

public void SetEnvironmentVariable(
    string name,
    string value);

在目标进程中设置环境变量。

name：要设置的环境变量的名称。
value：要设置的环境变量的值。

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

从目标进程获取所有环境变量及其值。

GetPublishedProcesses 方法

public static IEnumerable<int> GetPublishedProcesses();

获取可附加到 IEnumerable 所有活动 .NET 进程的进程 ID。

EventPipeProvider 类

public class EventPipeProvider
{
    public EventPipeProvider(
        string name,
        EventLevel eventLevel,
        long keywords = 0,
        IDictionary<string, string> arguments = null)

    public string Name { get; }

    public EventLevel EventLevel { get; }

    public long Keywords { get; }

    public IDictionary<string, string> Arguments { get; }

    public override string ToString();

    public override bool Equals(object obj);

    public override int GetHashCode();

    public static bool operator ==(Provider left, Provider right);

    public static bool operator !=(Provider left, Provider right);
}

构造函数

public EventPipeProvider(
    string name,
    EventLevel eventLevel,
    long keywords = 0,
    IDictionary<string, string> arguments = null)

创建具有给定提供程序名称、EventLevel、关键字和参数的新 EventPipeProvider 实例。

Name 属性

public string Name { get; }

获取提供程序的名称。

EventLevel 属性

public EventLevel EventLevel { get; }

获取 EventPipeProvider 的给定实例的 EventLevel。

Keywords 属性

public long Keywords { get; }

获取一个代表 EventSource 的关键字的位掩码的值。

Arguments 属性

public IDictionary<string, string> Arguments { get; }

获取键/值对字符串的 IDictionary，这些字符串代表要传递给代表给定 EventPipeProvider 的 EventSource 的可选参数。

备注

此类不可变，因为 EventPipe 不允许在截至 .NET Core 3.1 的 EventPipe 会话过程中修改提供程序的配置。

EventPipeSession 类

public class EventPipeSession : IDisposable
{
    public Stream EventStream { get; }
    public void Stop();
}

此类表示正在进行的 EventPipe 会话。它是不可变的，充当给定运行时的 EventPipe 会话的句柄。

EventStream 属性

public Stream EventStream { get; }

获取可用于读取事件流的 Stream。

Stop 方法

public void Stop();

停止给定的 EventPipe 会话。

DumpType 枚举

public enum DumpType
{
    Normal = 1,
    WithHeap = 2,
    Triage = 3,
    Full = 4
}

代表可以请求的转储类型。

Normal：只包含为进程中的所有现有线程的所有现有跟踪捕获堆栈跟踪所需的信息。有限的 GC 堆内存和信息。
WithHeap：包含 GC 堆以及为进程中的所有现有线程捕获堆栈跟踪所需的信息。
Triage：只包含为进程中的所有现有线程的所有现有跟踪捕获堆栈跟踪所需的信息。有限的 GC 堆内存和信息。某些已知包含潜在敏感信息的内容（如完整模块路径）将进行修订。虽然这旨在缓解某些敏感数据泄露情况，但不能保证此修订功能本身足以遵守任何有关数据隐私的特定法律或标准。
Full：包含进程中的所有可访问内存。原始内存数据包含在末尾，因此无需原始内存信息即可直接映射初始结构。此选项可能会导致转储文件非常大。

异常

从库中引发的异常的类型为 DiagnosticsClientException 或派生类型。

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

当库或目标进程的运行时不支持该命令时，可能会引发此异常。

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

当目标进程的运行时与库使用的诊断 IPC 协议不兼容时，可能会引发此异常。

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

当运行时不可用于诊断 IPC 命令（例如在运行时尚未准备好执行诊断命令的运行时启动早期）或运行时关闭时，可能会引发此异常。

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

当运行时错误响应给定命令时，可能会引发此异常。

通过

Microsoft.Diagnostics.NETCore.Client API

DiagnosticsClient 类

构造函数

StartEventPipeSession 方法

WriteDump 方法

AttachProfiler 方法

SetStartupProfiler 方法

ResumeRuntime 方法

SetEnvironmentVariable 方法

GetProcessEnvironment

GetPublishedProcesses 方法

EventPipeProvider 类

构造函数

Name 属性

EventLevel 属性

Keywords 属性

Arguments 属性

备注

EventPipeSession 类

EventStream 属性

Stop 方法

DumpType 枚举

异常

UnsupportedCommandException

UnsupportedProtocolException

ServerNotAvailableException

ServerErrorException

其他资源