Microsoft.Diagnostics.NETCore.Client-API

  • Artikel

In diesem Abschnitt werden die APIs der Diagnoseclientbibliothek beschrieben.

DiagnosticsClient-Klasse

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

Konstruktor

public DiagnosticsClient(int processId);

Erstellt eine neue Instanz von DiagnosticsClient für einen kompatiblen .NET-Prozess, der mit der Prozess-ID von processId ausgeführt wird.

processID: Prozess-ID der Zielanwendung.

StartEventPipeSession-Methoden

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

Startet eine EventPipe-Ablaufverfolgungssitzung unter Verwendung der angegebenen Anbieter und Einstellungen.

  • providers: Ein IEnumerable von EventPipeProvider-Elementen zum Starten der Ablaufverfolgung.
  • requestRundown: Ein bool, der angibt, ob Rundownanbieterereignisse aus der Runtime der Ziel-App angefordert werden sollen.
  • circularBufferMB: Ein int, der die Gesamtgröße des Zirkelpuffers angibt, welcher von der Runtime der Ziel-App beim Erfassen von Ereignissen verwendet wird.
  • token (für die Async-Überladung): das Token zum Überwachen von Abbruchanforderungen.
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: Ein EventPipeProvider zum Starten der Ablaufverfolgung.
  • requestRundown: Ein bool, der angibt, ob Rundownanbieterereignisse aus der Runtime der Ziel-App angefordert werden sollen.
  • circularBufferMB: Ein int, der die Gesamtgröße des Zirkelpuffers angibt, welcher von der Runtime der Ziel-App beim Erfassen von Ereignissen verwendet wird.
  • token (für die Async-Überladung): das Token zum Überwachen von Abbruchanforderungen.

Hinweis

Rundownereignisse enthalten Nutzlasten, die für die Nachanalyse erforderlich sein können, z. B. das Auflösen von Methodennamen von Threadbeispielen. Sofern Sie dies nicht möchten, wird empfohlen, diesen Wert auf requestRundown zu setzen. Bei großen Anwendungen kann dies eine Weile dauern.

WriteDump-Methode

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

Fordert ein Speicherabbild zum nachträglichen Debuggen der Zielanwendung an. Der Typ des Speicherabbilds kann mithilfe der DumpType-Enumeration angegeben werden.

  • dumpType: Typ des angeforderten Speicherabbilds.
  • dumpPath: Der Pfad zum Speicherabbild, in das geschrieben werden soll.
  • logDumpGeneration: Wenn dieser Wert auf true festgelegt ist, schreibt die Zielanwendung Diagnoseprotokolle während der Generierung des Speicherabbilds.
public void WriteDump(DumpType dumpType, string dumpPath, WriteDumpFlags flags)

Fordert ein Speicherabbild zum nachträglichen Debuggen der Zielanwendung an. Der Typ des Speicherabbilds kann mithilfe der DumpType-Enumeration angegeben werden.

  • dumpType: Typ des angeforderten Speicherabbilds.
  • dumpPath: Der Pfad zum Speicherabbild, in das geschrieben werden soll.
  • flags: Flags für Protokollierungs- und Absturzberichte. Bei Runtimes vor 6.0 wird nur LoggingEnabled unterstützt.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, bool logDumpGeneration, CancellationToken token)

Fordert ein Speicherabbild zum nachträglichen Debuggen der Zielanwendung an. Der Typ des Speicherabbilds kann mithilfe der DumpType-Enumeration angegeben werden.

  • dumpType: Typ des angeforderten Speicherabbilds.
  • dumpPath: Der Pfad zum Speicherabbild, in das geschrieben werden soll.
  • logDumpGeneration: Wenn dieser Wert auf true festgelegt ist, schreibt die Zielanwendung Diagnoseprotokolle während der Generierung des Speicherabbilds.
  • token: das Token zum Überwachen von Abbruchanforderungen.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, WriteDumpFlags flags, CancellationToken token)

Fordert ein Speicherabbild zum nachträglichen Debuggen der Zielanwendung an. Der Typ des Speicherabbilds kann mithilfe der DumpType-Enumeration angegeben werden.

  • dumpType: Typ des angeforderten Speicherabbilds.
  • dumpPath: Der Pfad zum Speicherabbild, in das geschrieben werden soll.
  • flags: Flags für Protokollierungs- und Absturzberichte. Bei Runtimes vor 6.0 wird nur LoggingEnabled unterstützt.
  • token: das Token zum Überwachen von Abbruchanforderungen.

AttachProfiler-Methode

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

Fordert das Anfügen eines ICorProfiler an die Zielanwendung an.

  • attachTimeout: Ein TimeSpan, nach dem das Anfügen abgebrochen wird.
  • profilerGuid: Guid der anzufügenden ICorProfiler-Instanz.
  • profilerPath: Pfad der anzufügenden ICorProfiler-DLL.
  • additionalData: Optionale zusätzliche Daten, die während des Anfügens des Profilers an die Runtime übergeben werden können.

SetStartupProfiler-Methode

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Legt einen Profiler als Startprofiler fest. Dieser Befehl kann nur ausgeführt werden, wenn die Runtime beim Start angehalten wird.

  • profilerGuid: Guid für den anzufügenden Profiler.
  • profilerPath: Pfad zum anzufügenden Profiler.

ResumeRuntime-Methode

public void ResumeRuntime();

Weist die Runtime an, die Ausführung fortzusetzen, nachdem sie beim Start angehalten wurde.

SetEnvironmentVariable-Methode

public void SetEnvironmentVariable(
    string name,
    string value);

Legt eine Umgebungsvariable im Zielprozess fest.

  • name: der Name der festzulegenden Umgebungsvariablen.
  • value: der Wert der festzulegenden Umgebungsvariablen.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Ruft alle Umgebungsvariablen und deren Werte aus dem Zielprozess ab.

GetPublishedProcesses-Methode

public static IEnumerable<int> GetPublishedProcesses();

Ruft ein IEnumerable von Prozess-IDs aller aktiven .NET-Prozesse ab, die zum Anfügen verwendet werden können.

EventPipeProvider-Klasse

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

Konstruktor

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

Erstellt eine neue Instanz von EventPipeProvider mit dem angegebenen Anbieternamen, EventLevel, Schlüsselwörtern und Argumenten.

Name-Eigenschaft

public string Name { get; }

Ruft den Namen des Anbieters ab.

EventLevel-Eigenschaft

public EventLevel EventLevel { get; }

Ruft die EventLevel der angegebenen Instanz von EventPipeProvider ab.

Keywords-Eigenschaft

public long Keywords { get; }

Ruft einen Wert ab, der die Bitmaske für Schlüsselwörter der EventSource darstellt.

Arguments-Eigenschaft

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

Ruft ein IDictionary von Schlüssel-Wert-Paarzeichenfolgen ab, die optionale Argumente darstellen, welche an EventSource übergeben werden sollen, die den angegebenen EventPipeProvider darstellen.

Bemerkungen

Diese Klasse ist unveränderlich, da EventPipe das Ändern der Konfiguration eines Anbieters während einer EventPipe-Sitzung ab .NET Core 3.1 nicht zulässt.

EventPipeSession-Klasse

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

Diese Klasse stellt eine laufende EventPipe-Sitzung dar. Sie ist unveränderlich und fungiert als Handle für eine EventPipe-Sitzung der angegebenen Runtime.

EventStream-Eigenschaft

public Stream EventStream { get; }

Ruft einen Stream ab, der zum Lesen des Ereignisdatenstroms verwendet werden kann.

Stop-Methode

public void Stop();

Beendet die angegebene EventPipe-Sitzung.

DumpType-Enumeration

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

Stellt den Typ des Speicherabbilds dar, das angefordert werden kann.

  • Normal: Es werden nur die Informationen aufgenommen, die zum Erfassen von Stapelüberwachungen für alle vorhandenen Ablaufüberwachungen für alle vorhandenen Threads in einem Prozess erforderlich sind. Heaparbeitsspeicher und -informationen der GC sind eingeschränkt.
  • WithHeap: Es werden nur die GC-Heaps und Informationen aufgenommen, die zum Erfassen von Stapelüberwachungen für alle vorhandenen Threads in einem Prozess erforderlich sind.
  • Triage: Es werden nur die Informationen aufgenommen, die zum Erfassen von Stapelüberwachungen für alle vorhandenen Ablaufüberwachungen für alle vorhandenen Threads in einem Prozess erforderlich sind. Heaparbeitsspeicher und -informationen der GC sind eingeschränkt.
  • Full: Es wird der gesamte verfügbare Arbeitsspeicher im Prozess aufgenommen. Die Rohdaten des Arbeitsspeichers sind am Ende enthalten, sodass die ursprünglichen Strukturen direkt ohne die unformatierten Arbeitsspeicherinformationen zugeordnet werden können. Diese Option kann zu einer sehr großen Speicherabbilddatei führen.

Ausnahmen

Von der Bibliothek ausgelöste Ausnahmen weisen den Typ DiagnosticsClientException oder einen abgeleiteten Typ auf.

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

Diese Ausnahme kann ausgelöst werden, wenn der Befehl weder von der Bibliothek noch von der Runtime des Zielprozesses unterstützt wird.

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Diese Ausnahme kann ausgelöst werden, wenn die Runtime des Zielprozesses nicht mit dem von der Bibliothek verwendeten IPC-Diagnoseprotokoll kompatibel ist.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Diese Ausnahme kann ausgelöst werden, wenn die Runtime nicht für IPC-Diagnosebefehle verfügbar ist, z. B. früh während des Runtimestarts, bevor die Runtime für Diagnosebefehle bereit ist oder beim Herunterfahren der Runtime.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Diese Ausnahme kann ausgelöst werden, wenn die Runtime mit einem Fehler auf einen bestimmten Befehl antwortet.