Microsoft.Diagnostics.NETCore.Client API

This section describes the APIs of the diagnostics client library.

DiagnosticsClient class

public sealed class DiagnosticsClient
{
    public DiagnosticsClient(int processId);

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

    public EventPipeSession StartEventPipeSession(
        EventPipeProvider provider,
        bool requestRundown = true,
        int circularBufferMB = 256);

    public EventPipeSession StartEventPipeSession(
        EventPipeSessionConfiguration config);

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

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

    public Task<EventPipeSession> StartEventPipeSessionAsync(
        EventPipeSessionConfiguration configuration,
        CancellationToken token);

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

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

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

    public Task WriteDumpAsync(
        DumpType dumpType,
        string dumpPath,
        WriteDumpFlags flags,
        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 void ApplyStartupHook(
        string startupHookPath);

    public Task ApplyStartupHookAsync(
        string startupHookPath,
        CancellationToken token);

    public void EnablePerfMap(
        PerfMapType type);

    public void DisablePerfMap();

    public static IEnumerable<int> GetPublishedProcesses();
}

Constructor

public DiagnosticsClient(int processId);

Creates a new instance of DiagnosticsClient for a compatible .NET process running with process ID of processId.

processID : Process ID of the target application.

StartEventPipeSession methods

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

Starts an EventPipe tracing session using the given providers and settings.

• providers : An IEnumerable of EventPipeProviders to start tracing.
• requestRundown: A bool specifying whether rundown provider events from the target app's runtime should be requested.
• circularBufferMB: An int specifying the total size of circular buffer used by the target app's runtime on collecting events.
• token (for the async overload): The token to monitor for cancellation requests.

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

Starts an EventPipe tracing session using a single provider.

• provider : An EventPipeProvider to start tracing.
• requestRundown: A bool specifying whether rundown provider events from the target app's runtime should be requested.
• circularBufferMB: An int specifying the total size of circular buffer used by the target app's runtime on collecting events.
• token (for the async overload): The token to monitor for cancellation requests.

public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

public Task<EventPipeSession> StartEventPipeSessionAsync(
    EventPipeSessionConfiguration configuration,
    CancellationToken token);

Starts an EventPipe tracing session using an EventPipeSessionConfiguration.

• config / configuration : An EventPipeSessionConfiguration that defines the session.
• token (for the async overload): The token to monitor for cancellation requests.

Note

Rundown events contain payloads that may be needed for post analysis, such as resolving method names of thread samples. Unless you know you do not want this, we recommend setting requestRundown to true. In large applications, this may take a while.

WriteDump method

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

Request a dump for post-mortem debugging of the target application. The type of the dump can be specified using the DumpType enum.

• dumpType : Type of the dump to be requested.
• dumpPath : The path to the dump to be written out to.
• logDumpGeneration : If set to true, the target application will write out diagnostic logs during dump generation.

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

Request a dump for post-mortem debugging of the target application. The type of the dump can be specified using the DumpType enum.

• dumpType : Type of the dump to be requested.
• dumpPath : The path to the dump to be written out to.
• flags : logging and crash report flags. On runtimes less than 6.0, only LoggingEnabled is supported.

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

Request a dump for post-mortem debugging of the target application. The type of the dump can be specified using the DumpType enum.

• dumpType : Type of the dump to be requested.
• dumpPath : The path to the dump to be written out to.
• logDumpGeneration : If set to true, the target application will write out diagnostic logs during dump generation.
• token : The token to monitor for cancellation requests.

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

Request a dump for post-mortem debugging of the target application. The type of the dump can be specified using the DumpType enum.

• dumpType : Type of the dump to be requested.
• dumpPath : The path to the dump to be written out to.
• flags : logging and crash report flags. On runtimes less than 6.0, only LoggingEnabled is supported.
• token : The token to monitor for cancellation requests.

ApplyStartupHook methods

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Loads the specified assembly with a StartupHook in the target process.

• startupHookPath : The path to the assembly containing the startup hook.
• token (for the async overload): The token to monitor for cancellation requests.

PerfMap methods

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Controls generation of perf maps in the target process.

• type : The PerfMapType indicating the type of perf map to enable.

AttachProfiler method

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

Request to attach an ICorProfiler to the target application.

• attachTimeout : A TimeSpan after which attach will be aborted.
• profilerGuid : Guid of the ICorProfiler to be attached.
• profilerPath : Path to the ICorProfiler dll to be attached.
• additionalData : Optional additional data that can be passed to the runtime during profiler attach.

SetStartupProfiler method

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Set a profiler as the startup profiler. It is only valid to issue this command while the runtime is paused at startup.

• profilerGuid : Guid for the profiler to be attached.
• profilerPath : Path to the profiler to be attached.

ResumeRuntime method

public void ResumeRuntime();

Tell the runtime to resume execution after being paused at startup.

SetEnvironmentVariable method

public void SetEnvironmentVariable(
    string name,
    string value);

Set an environment variable in the target process.

• name : The name of the environment variable to set.
• value : The value of the environment variable to set.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Gets all environment variables and their values from the target process.

GetPublishedProcesses method

public static IEnumerable<int> GetPublishedProcesses();

Get an IEnumerable of process IDs of all the active .NET processes that can be attached to.

EventPipeSessionConfiguration class

public sealed class EventPipeSessionConfiguration
{
    public EventPipeSessionConfiguration(
        IEnumerable<EventPipeProvider> providers,
        int circularBufferSizeMB = 256,
        bool requestRundown = true,
        bool requestStackwalk = true);

    public EventPipeSessionConfiguration(
        IEnumerable<EventPipeProvider> providers,
        int circularBufferSizeMB,
        long rundownKeyword,
        bool requestStackwalk = true);

    public EventPipeSessionConfiguration(
        IEnumerable<EventPipeProvider> providers,
        int circularBufferSizeMB,
        long rundownKeyword,
        bool requestStackwalk,
        EventPipeBufferingMode bufferingMode);

    public bool RequestRundown { get; }

    public int CircularBufferSizeInMB { get; }

    public bool RequestStackwalk { get; }

    public long RundownKeyword { get; }

    public EventPipeBufferingMode BufferingMode { get; }

    public IReadOnlyCollection<EventPipeProvider> Providers { get; }
}

Represents the configuration for an EventPipeSession.

• providers : An IEnumerable of EventPipeProviders to enable.
• circularBufferSizeMB : The size in MB of the runtime's buffer for collecting events.
• requestRundown : If true, request rundown events from the runtime.
• requestStackwalk : If true, record a stack trace for every emitted event.
• rundownKeyword : The keyword mask used for rundown events.
• bufferingMode : The EventPipeBufferingMode for the session. Use Block to request non-lossy collection. Passing Block requires a .NET 11+ target runtime; on an older runtime, StartEventPipeSession throws UnsupportedCommandException.

The BufferingMode property returns the buffering mode for the session. The default value, Drop, keeps the runtime's lossy buffer.

EventPipeProvider class

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

    public EventPipeProvider(
        string name,
        EventLevel eventLevel,
        long keywords,
        IDictionary<string, string> arguments,
        EventPipeProviderEventFilter eventFilter)

    public string Name { get; }

    public EventLevel EventLevel { get; }

    public long Keywords { get; }

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

    public EventPipeProviderEventFilter EventFilter { 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);
}

Constructor

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

public EventPipeProvider(
    string name,
    EventLevel eventLevel,
    long keywords,
    IDictionary<string, string> arguments,
    EventPipeProviderEventFilter eventFilter)

Creates a new instance of EventPipeProvider with the given provider name, EventLevel, keywords, and arguments. The second overload also takes an EventPipeProviderEventFilter that filters which Event IDs the runtime enables for the provider. When you set an event filter, the session requires a .NET 10+ target runtime.

Name property

public string Name { get; }

Gets the name of the Provider.

EventLevel property

public EventLevel EventLevel { get; }

Gets the EventLevel of the given instance of EventPipeProvider.

Keywords property

public long Keywords { get; }

Gets a value that represents bitmask for keywords of the EventSource.

Arguments property

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

Gets an IDictionary of key-value pair strings representing optional arguments to be passed to EventSource representing the given EventPipeProvider.

EventFilter property

public EventPipeProviderEventFilter EventFilter { get; }

Gets the optional EventPipeProviderEventFilter that the runtime applies to this provider's Event IDs after the keyword and level filter. When the value is null, the runtime enables every Event ID that the keyword and level filter allows.

Remarks

This class is immutable, because EventPipe does not allow a provider's configuration to be modified during an EventPipe session as of .NET Core 3.1.

EventPipeProviderEventFilter class

public sealed class EventPipeProviderEventFilter
{
    public EventPipeProviderEventFilter(
        bool enable,
        IReadOnlyList<uint> eventIds);

    public bool Enable { get; }

    public IReadOnlyList<uint> EventIds { get; }
}

Represents an optional per-provider filter on Event IDs. The runtime applies the filter after the keyword and level filter of the associated EventPipeProvider. Event filters require a .NET 10+ target runtime.

Constructor

public EventPipeProviderEventFilter(
    bool enable,
    IReadOnlyList<uint> eventIds);

Creates a new instance of EventPipeProviderEventFilter.

• enable : If true, eventIds is an allow-list and the runtime enables only those Event IDs. If false, eventIds is a deny-list and the runtime enables every Event ID except those listed. An empty deny-list therefore enables all events.
• eventIds : The Event IDs to enable or disable, as determined by enable.

Enable property

public bool Enable { get; }

Gets a value that indicates whether EventIds is an allow-list (true) or a deny-list (false).

EventIds property

public IReadOnlyList<uint> EventIds { get; }

Gets the list of Event IDs that the filter enables or disables.

EventPipeSession class

public class EventPipeSession : IDisposable
{
    public Stream EventStream { get; }

    public void Stop();

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

This class represents an ongoing EventPipe session. It is immutable and acts as a handle to an EventPipe session of the given runtime.

EventStream property

public Stream EventStream { get; }

Gets a Stream that can be used to read the event stream.

Stop methods

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

Stops the given EventPipe session.

• cancellationToken (for the async overload): The token to monitor for cancellation requests.

Dispose method

public void Dispose();

Releases resources associated with the EventPipeSession.

DiagnosticsClientConnector class

public sealed class DiagnosticsClientConnector : IAsyncDisposable
{
    public DiagnosticsClient Instance { get; }

    public ValueTask DisposeAsync();

    public static Task<DiagnosticsClientConnector> FromDiagnosticPort(
        string diagnosticPort,
        CancellationToken ct);
}

Represents a helper that creates a DiagnosticsClient from a diagnostic port and manages the lifetime of the underlying diagnostics server connection.

• Instance : The DiagnosticsClient connected to the target runtime.
• DisposeAsync : Disposes the underlying server/connection asynchronously.
• FromDiagnosticPort : Creates a new DiagnosticsClientConnector from the specified diagnostic port.

public static Task<DiagnosticsClientConnector> FromDiagnosticPort(
    string diagnosticPort,
    CancellationToken ct)

• diagnosticPort : The diagnostic port string (for example, a listen or connect port) to connect through.
• ct : The token to monitor for cancellation requests.

DumpType enum

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

Represents the type of dump that can be requested.

• Normal: Include just the information necessary to capture stack traces for all existing traces for all existing threads in a process. Limited GC heap memory and information.
• WithHeap: Includes the GC heaps and information necessary to capture stack traces for all existing threads in a process.
• Triage: Include just the information necessary to capture stack traces for all existing traces for all existing threads in a process. Limited GC heap memory and information. Some content that is known to contain potentially sensitive information such as full module paths will be redacted. While this is intended to mitigate some cases of sensitive data exposure, there is no guarantee this redaction feature on its own is sufficient to comply with any particular law or standard regarding data privacy.
• Full: Include all accessible memory in the process. The raw memory data is included at the end, so that the initial structures can be mapped directly without the raw memory information. This option can result in a very large dump file.

WriteDumpFlags enum

public enum WriteDumpFlags
{
    None = 0x00,
    LoggingEnabled = 0x01,
    VerboseLoggingEnabled = 0x02,
    CrashReportEnabled = 0x04
}

Represents additional options that can be specified when requesting a dump.

• None : No additional behavior.
• LoggingEnabled : Enable basic logging during dump generation.
• VerboseLoggingEnabled : Enable verbose logging during dump generation.
• CrashReportEnabled : Enable generation of a crash report.

PerfMapType enum

public enum PerfMapType
{
    None = 0,
    All = 1,
    JitDump = 2,
    PerfMap = 3
}

Represents the type of perf map behavior that can be enabled.

• None : No perf map output.
• All : Enable all perf map outputs supported by the runtime.
• JitDump : Enable JIT dump perf map output.
• PerfMap : Enable traditional perf map output.

EventPipeBufferingMode enum

public enum EventPipeBufferingMode
{
    Drop = 0,
    Block = 1
}

Controls how the runtime's per-session event buffer behaves when it fills faster than the session drains it.

• Drop : The runtime default. The session uses a buffer that drops events when it overflows, so collection is lossy.
• Block : Non-lossy collection. The runtime blocks event producers when the buffer is full instead of dropping events. Use it for collections that must be complete, such as a heap snapshot on a large heap. Block is non-lossy only up to the buffer's capacity, not against host memory exhaustion: if the runtime can't allocate the memory it needs to reserve buffer space, or during session shutdown, it drops the event instead of blocking. Block requires a .NET 11+ target runtime; on an older runtime, starting the session throws UnsupportedCommandException.

Exceptions

Exceptions that are thrown from the library are of type DiagnosticsClientException or a derived type.

public class DiagnosticsClientException : Exception

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

This may be thrown when the target process's runtime is not compatible with the diagnostics IPC protocol used by the library.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

This may be thrown when the runtime is not available for diagnostics IPC commands, such as early during runtime startup before the runtime is ready for diagnostics commands, or when the runtime is shutting down.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

This may be thrown when the runtime responds with an error to a given command.

UnsupportedCommandException

public class UnsupportedCommandException : ServerErrorException

This exception is thrown when the command is not supported by either the library or the target process's runtime.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

This exception is thrown when a profiler is already loaded into the target runtime and another attach is attempted.

BadEncodingException

public class BadEncodingException : ServerErrorException

This exception is thrown when the target runtime can't decode the command payload and rejects it. From a well-formed client, it usually means the runtime is too old to understand a newer configured option value, so it rejects the request while parsing.