Uređivanje

Podeli preko

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 bool RequestRundown { get; }

    public int CircularBufferSizeInMB { get; }

    public bool RequestStackwalk { get; }

    public long RundownKeyword { 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.

EventPipeProvider class

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

Constructor

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

Creates a new instance of EventPipeProvider with the given provider name, EventLevel, keywords, and arguments.

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.

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.

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.

Exceptions

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

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

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

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.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

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

  • Last updated on