Microsoft.Diagnostics.NETCore.Client API

W tej sekcji opisano interfejsy API biblioteki klienta diagnostyki.

DiagnosticsClient, klasa

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

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)

• 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.

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 async 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 async 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.

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ć.

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

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ń.

Stop, metoda

public void Stop();

Zatrzymuje daną EventPipe sesję.

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.

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.