Udostępnij przez

Microsoft.Diagnostics.NETCore.Client API

W tej sekcji opisano interfejsy API biblioteki klienta diagnostyki.

DiagnosticsClient, klasa

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

Konstruktor

public DiagnosticsClient(int processId);

Tworzy nowe wystąpienie zgodnego DiagnosticsClient procesu .NET uruchomionego z identyfikatorem processIdprocesu .

processID : identyfikator procesu aplikacji docelowej.

StartEventPipeSession, metody

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

Uruchamia sesję śledzenia eventPipe przy użyciu podanych dostawców i ustawień.

  • providers : an IEnumerable z EventPipeProviders do rozpoczęcia śledzenia.
  • requestRundown: Należy bool zażądać określenia, czy zdarzenia dostawcy uruchamiania ze środowiska uruchomieniowego aplikacji docelowej powinny być żądane.
  • circularBufferMB: Określenie int całkowitego rozmiaru buforu cyklicznego używanego przez środowisko uruchomieniowe aplikacji docelowej podczas zbierania zdarzeń.
  • token (dla przeciążenia asynchronicznego): token do monitorowania żądań anulowania.
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);

Uruchamia sesję śledzenia eventPipe przy użyciu jednego dostawcy.

  • provider : An EventPipeProvider do rozpoczęcia śledzenia.
  • requestRundown: Należy bool zażądać określenia, czy zdarzenia dostawcy uruchamiania ze środowiska uruchomieniowego aplikacji docelowej powinny być żądane.
  • circularBufferMB: Określenie int całkowitego rozmiaru buforu cyklicznego używanego przez środowisko uruchomieniowe aplikacji docelowej podczas zbierania zdarzeń.
  • token (dla przeciążenia asynchronicznego): token do monitorowania żądań anulowania.
public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

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

Uruchamia sesję śledzenia eventPipe przy użyciu elementu EventPipeSessionConfiguration.

  • config / configuration : Element EventPipeSessionConfiguration definiujący sesję.
  • token (dla przeciążenia asynchronicznego): token do monitorowania żądań anulowania.

Uwaga

Zdarzenia rundown zawierają ładunki, które mogą być potrzebne do analizy po analizie, takie jak rozpoznawanie nazw metod przykładów wątków. Jeśli nie wiesz, że nie chcesz tego robić, zalecamy ustawienie requestRundown wartości true. W dużych aplikacjach może to chwilę potrwać.

WriteDump, metoda

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

Zażądaj zrzutu na potrzeby debugowania pośmiertnego aplikacji docelowej. Typ zrzutu można określić przy użyciu wyliczenia DumpType .

  • dumpType : typ zrzutu do zażądania.
  • dumpPath : ścieżka do zrzutu, który ma zostać zapisany.
  • logDumpGeneration : Jeśli ustawiono wartość true, aplikacja docelowa zapisze dzienniki diagnostyczne podczas generowania zrzutu.
public void WriteDump(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags)

Zażądaj zrzutu na potrzeby debugowania pośmiertnego aplikacji docelowej. Typ zrzutu można określić przy użyciu wyliczenia DumpType .

  • dumpType : typ zrzutu do zażądania.
  • dumpPath : ścieżka do zrzutu, który ma zostać zapisany.
  • flags : flagi rejestrowania i zgłaszania awarii. W środowiskach uruchomieniowych mniejszych niż 6.0 obsługiwane jest tylko rejestrowanieEnabled.
public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    bool logDumpGeneration,
    CancellationToken token)

Zażądaj zrzutu na potrzeby debugowania pośmiertnego aplikacji docelowej. Typ zrzutu można określić przy użyciu wyliczenia DumpType .

  • dumpType : typ zrzutu do zażądania.
  • dumpPath : ścieżka do zrzutu, który ma zostać zapisany.
  • logDumpGeneration : Jeśli ustawiono wartość true, aplikacja docelowa zapisze dzienniki diagnostyczne podczas generowania zrzutu.
  • token : token do monitorowania żądań anulowania.
public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags,
    CancellationToken token)

Zażądaj zrzutu na potrzeby debugowania pośmiertnego aplikacji docelowej. Typ zrzutu można określić przy użyciu wyliczenia DumpType .

  • dumpType : typ zrzutu do zażądania.
  • dumpPath : ścieżka do zrzutu, który ma zostać zapisany.
  • flags : flagi rejestrowania i zgłaszania awarii. W środowiskach uruchomieniowych mniejszych niż 6.0 obsługiwane jest tylko rejestrowanieEnabled.
  • token : token do monitorowania żądań anulowania.

ApplyStartupHook, metody

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Ładuje określony zestaw za pomocą StartupHook elementu w procesie docelowym.

  • startupHookPath : ścieżka do zestawu zawierającego punkt zaczepienia uruchamiania.
  • token (dla przeciążenia asynchronicznego): token do monitorowania żądań anulowania.

Metody narzędzia PerfMap

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Steruje generowaniem map wydajności w procesie docelowym.

  • type PerfMapType: wskazujący typ mapy wydajności do włączenia.

AttachProfiler, metoda

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

Żądanie dołączenia elementu ICorProfiler do aplikacji docelowej.

  • attachTimeout : Po TimeSpan którym dołączanie zostanie przerwane.
  • profilerGuid : Guid elementu ICorProfiler do dołączenia.
  • profilerPath : ścieżka do biblioteki DLL ICorProfiler do dołączenia.
  • additionalData : Opcjonalne dodatkowe dane, które można przekazać do środowiska uruchomieniowego podczas dołączania profilera.

SetStartupProfiler, metoda

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Ustaw profilera jako profilera uruchamiania. To polecenie jest prawidłowe tylko wtedy, gdy środowisko uruchomieniowe jest wstrzymane podczas uruchamiania.

  • profilerGuid : Guid aby profiler był dołączany.
  • profilerPath : Ścieżka do profilera, który ma zostać dołączony.

ResumeRuntime, metoda

public void ResumeRuntime();

Poinformuj środowisko uruchomieniowe, aby wznowiło wykonywanie po wstrzymaniu podczas uruchamiania.

SetEnvironmentVariable, metoda

public void SetEnvironmentVariable(
    string name,
    string value);

Ustaw zmienną środowiskową w procesie docelowym.

  • name : nazwa zmiennej środowiskowej do ustawienia.
  • value : wartość zmiennej środowiskowej do ustawienia.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Pobiera wszystkie zmienne środowiskowe i ich wartości z procesu docelowego.

GetPublishedProcesses, metoda

public static IEnumerable<int> GetPublishedProcesses();

IEnumerable Pobierz identyfikatory procesów wszystkich aktywnych procesów platformy .NET, do których można dołączyć.

EventPipeSessionConfiguration, klasa

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

Reprezentuje konfigurację EventPipeSessionelementu .

  • providers : an IEnumerable z EventPipeProviders do włączenia.
  • circularBufferSizeMB : rozmiar w MB buforu środowiska uruchomieniowego do zbierania zdarzeń.
  • requestRundown : jeśli true, zażądaj zdarzeń uruchamiania ze środowiska uruchomieniowego.
  • requestStackwalk : Jeśli true, zarejestruj ślad stosu dla każdego emitowanego zdarzenia.
  • rundownKeyword : maska słowa kluczowego używana do uruchamiania zdarzeń.

EventPipeProvider, klasa

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)

Tworzy nowe wystąpienie EventPipeProvider obiektu o podanej nazwie dostawcy, EventLevelsłowach kluczowych i argumentach.

Name — Właściwość

public string Name { get; }

Pobiera nazwę dostawcy.

EventLevel, właściwość

public EventLevel EventLevel { get; }

EventLevel Pobiera dane wystąpienie klasy EventPipeProvider.

Właściwość Słowa kluczowe

public long Keywords { get; }

Pobiera wartość reprezentującą maskę bitów dla słów kluczowych .EventSource

Właściwość Arguments

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

Pobiera ciągi IDictionary par klucz-wartość reprezentujące opcjonalne argumenty, które mają zostać przekazane do EventSource reprezentowania danego EventPipeProviderelementu .

Uwagi

Ta klasa jest niezmienna, ponieważ usługa EventPipe nie zezwala na modyfikowanie konfiguracji dostawcy podczas sesji EventPipe na platformie .NET Core 3.1.

EventPipeSession, klasa

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

    public void Stop();

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

Ta klasa reprezentuje bieżącą sesję EventPipe. Jest niezmienny i działa jako dojście do sesji EventPipe danego środowiska uruchomieniowego.

Właściwość EventStream

public Stream EventStream { get; }

Pobiera element Stream , który może służyć do odczytywania strumienia zdarzeń.

Metody zatrzymania

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

Zatrzymuje daną EventPipe sesję.

  • cancellationToken (dla przeciążenia asynchronicznego): token do monitorowania żądań anulowania.

Dispose — metoda

public void Dispose();

Zwalnia zasoby skojarzone z elementem EventPipeSession.

DiagnosticsClientConnector, klasa

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

    public ValueTask DisposeAsync();

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

Reprezentuje pomocnika, który tworzy element DiagnosticsClient z portu diagnostycznego i zarządza okresem istnienia bazowego połączenia serwera diagnostycznego.

  • Instance : połączony DiagnosticsClient ze środowiskiem uruchomieniowym docelowym.
  • DisposeAsync : usuwa serwer/połączenie bazowe asynchronicznie.
  • FromDiagnosticPort : Tworzy nowy DiagnosticsClientConnector z określonego portu diagnostycznego.
public static Task<DiagnosticsClientConnector> FromDiagnosticPort(
    string diagnosticPort,
    CancellationToken ct)
  • diagnosticPort : parametry portu diagnostycznego (na przykład port nasłuchiwania lub łączenia) do nawiązania połączenia za pośrednictwem.
  • ct : token do monitorowania żądań anulowania.

Wyliczenie DumpType

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

Reprezentuje typ zrzutu, którego można zażądać.

  • Normal: dołącz tylko informacje niezbędne do przechwycenia śladów stosu dla wszystkich istniejących śladów dla wszystkich istniejących wątków w procesie. Ograniczona pamięć sterta GC i informacje.
  • WithHeap: zawiera sterty GC i informacje niezbędne do przechwytywania śladów stosu dla wszystkich istniejących wątków w procesie.
  • Triage: dołącz tylko informacje niezbędne do przechwycenia śladów stosu dla wszystkich istniejących śladów dla wszystkich istniejących wątków w procesie. Ograniczona pamięć sterta GC i informacje. Część zawartości, która jest znana z potencjalnie poufnych informacji, takich jak pełne ścieżki modułów, zostanie zredagowana. Chociaż ma to na celu ograniczenie niektórych przypadków ujawnienia poufnych danych, nie ma żadnej gwarancji, że ta funkcja redakcji samodzielnie jest wystarczająca do zachowania zgodności z żadnym konkretnym prawem lub standardem dotyczącym prywatności danych.
  • Full: uwzględnij całą dostępną pamięć w procesie. Dane pierwotnej pamięci są uwzględniane na końcu, dzięki czemu początkowe struktury można mapować bezpośrednio bez nieprzetworzonych informacji o pamięci. Ta opcja może spowodować bardzo duży plik zrzutu.

WriteDumpFlags, wyliczenie

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

Reprezentuje dodatkowe opcje, które można określić podczas żądania zrzutu.

  • None : brak dodatkowego zachowania.
  • LoggingEnabled : Włącz rejestrowanie podstawowe podczas generowania zrzutu.
  • VerboseLoggingEnabled : Włącz pełne rejestrowanie podczas generowania zrzutu.
  • CrashReportEnabled : Włącz generowanie raportu o awarii.

PerfMapType, wyliczenie

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

Reprezentuje typ zachowania mapy wydajności, które można włączyć.

  • None : brak danych wyjściowych mapy wydajności.
  • All : Włącz wszystkie dane wyjściowe mapy wydajności obsługiwane przez środowisko uruchomieniowe.
  • JitDump : Włącz dane wyjściowe mapy wydajności zrzutu JIT.
  • PerfMap : Włącz tradycyjne dane wyjściowe mapy wydajności.

Wyjątki

Wyjątki zgłaszane z biblioteki są typu DiagnosticsClientException lub typu pochodnego.

public class DiagnosticsClientException : Exception

Nieobsługiwany wyjątekCommandException

public class UnsupportedCommandException : DiagnosticsClientException

Może to być zgłaszane, gdy polecenie nie jest obsługiwane przez bibliotekę lub środowisko uruchomieniowe procesu docelowego.

Nieobsługiwany wyjątekProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Może to być zgłaszane, gdy środowisko uruchomieniowe procesu docelowego nie jest zgodne z protokołem IPC diagnostyki używanym przez bibliotekę.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Może to być zgłaszane, gdy środowisko uruchomieniowe nie jest dostępne dla poleceń IPC diagnostyki, takich jak na początku uruchamiania środowiska uruchomieniowego, zanim środowisko uruchomieniowe będzie gotowe do obsługi poleceń diagnostycznych lub gdy środowisko uruchomieniowe zostanie zamknięte.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Może to być zgłaszane, gdy środowisko uruchomieniowe odpowie z błędem dla danego polecenia.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

Ten wyjątek jest zgłaszany, gdy profiler jest już załadowany do docelowego środowiska uruchomieniowego i podjęto próbę dołączenia.

  • Last updated on