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

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ń.
• bufferingMode : element EventPipeBufferingMode dla sesji. Użyj polecenia Block , aby zażądać kolekcji bez utraty. Przekazywanie Block wymaga .NET 11+ docelowego środowiska uruchomieniowego; w starszym środowisku uruchomieniowym StartEventPipeSession zgłasza błąd UnsupportedCommandException.

Właściwość BufferingMode zwraca tryb buforowania dla sesji. Wartość domyślna , Dropprzechowuje bufor straty środowiska uruchomieniowego.

EventPipeProvider, klasa

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

Konstruktor

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)

Tworzy nowe wystąpienie EventPipeProvider obiektu o podanej nazwie dostawcy, EventLevelsłowach kluczowych i argumentach. Drugie przeciążenie przyjmuje EventPipeProviderEventFilter również filtr, który identyfikatory zdarzeń, które środowisko uruchomieniowe włącza dla dostawcy. Po ustawieniu filtru zdarzeń sesja wymaga .NET 10+ docelowego środowiska uruchomieniowego.

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 .

Właściwość EventFilter

public EventPipeProviderEventFilter EventFilter { get; }

Pobiera opcjonalne EventPipeProviderEventFilter , że środowisko uruchomieniowe ma zastosowanie do identyfikatorów zdarzeń tego dostawcy po filtrze słowa kluczowego i poziomu. Gdy wartość to null, środowisko uruchomieniowe włącza każdy identyfikator zdarzenia dozwolony przez słowo kluczowe i filtr na poziomie.

Uwagi

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

EventPipeProviderEventFilter, klasa

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

    public bool Enable { get; }

    public IReadOnlyList<uint> EventIds { get; }
}

Reprezentuje opcjonalny filtr dla dostawcy w identyfikatorach zdarzeń. Środowisko uruchomieniowe stosuje filtr po słowie kluczowym i filtrze poziomu skojarzonego EventPipeProviderelementu . Filtry zdarzeń wymagają .NET 10+ docelowego środowiska uruchomieniowego.

Konstruktor

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

Tworzy nowe wystąpienie klasy EventPipeProviderEventFilter.

• enable : Jeśli trueelement eventIds jest listą dozwolonych, a środowisko uruchomieniowe włącza tylko te identyfikatory zdarzeń. Jeśli falseparametr eventIds jest listą odmowy, a środowisko uruchomieniowe włącza każdy identyfikator zdarzenia z wyjątkiem wymienionych. Pusta lista odmów włącza zatem wszystkie zdarzenia.
• eventIds : identyfikatory zdarzeń, które mają być włączone lub wyłączone, zgodnie z wartością enable.

Włącz właściwość

public bool Enable { get; }

Pobiera wartość wskazującą, czy EventIds jest to lista dozwolonych (true) czy lista-odmowy (false).

Właściwość EventIds

public IReadOnlyList<uint> EventIds { get; }

Pobiera listę identyfikatorów zdarzeń, które filtr włącza lub wyłącza.

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.

EventPipeBufferingMode, wyliczenie

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

Określa, jak zachowuje się bufor zdarzeń poszczególnych sesji środowiska uruchomieniowego, gdy wypełnia się szybciej niż opróżnianie sesji.

• Drop : domyślne środowisko uruchomieniowe. Sesja używa buforu, który usuwa zdarzenia podczas przepełnienia, więc kolekcja jest strata.
• Block : kolekcja niestrawna. Środowisko uruchomieniowe blokuje producentów zdarzeń, gdy bufor jest pełny, a nie upuszcza zdarzenia. Należy go używać w przypadku kolekcji, które muszą być ukończone, na przykład migawki sterta na dużym stercie. Block nie jest stratą tylko do pojemności buforu, a nie w przypadku wyczerpania pamięci hosta: jeśli środowisko uruchomieniowe nie może przydzielić pamięci, która musi zarezerwować miejsce buforu lub podczas zamykania sesji, pominie zdarzenie zamiast blokowania. Blockwymaga .NET 11+ docelowego środowiska uruchomieniowego; w starszym środowisku uruchomieniowym uruchomienie sesji zgłasza błąd UnsupportedCommandException.

Wyjątki

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

public class DiagnosticsClientException : Exception

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.

Nieobsługiwany wyjątekCommandException

public class UnsupportedCommandException : ServerErrorException

Ten wyjątek jest zgłaszany, gdy polecenie nie jest obsługiwane przez bibliotekę lub środowisko uruchomieniowe procesu docelowego.

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.

BadEncodingException

public class BadEncodingException : ServerErrorException

Ten wyjątek jest zgłaszany, gdy docelowe środowisko uruchomieniowe nie może dekodować ładunku polecenia i go odrzuca. Z dobrze sformułowanego klienta zwykle oznacza to, że środowisko uruchomieniowe jest zbyt stare, aby zrozumieć nowszą skonfigurowaną wartość opcji, więc odrzuca żądanie podczas analizowania.