Condividi tramite

API Microsoft.Diagnostics.NETCore.Client

Questa sezione descrive le API della libreria client di diagnostica.

Classe DiagnosticsClient

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

Costruttore

public DiagnosticsClient(int processId);

Crea una nuova istanza di DiagnosticsClient per un processo .NET compatibile in esecuzione con ID processo di processId.

processID: ID processo dell'applicazione di destinazione.

Metodi StartEventPipeSession

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

Avvia una sessione di tracciamento EventPipe usando i provider e le impostazioni specificati.

  • providers: un IEnumerable di EventPipeProvider per avviare il tracciamento.
  • requestRundown: un bool che specifica se devono essere richiesti gli eventi del provider di rundown dal runtime dell'app di destinazione.
  • circularBufferMB: un int che specifica le dimensioni totali del buffer circolare usato dal runtime dell'app di destinazione per la raccolta di eventi.
  • token (per l'overload asincrono): token da monitorare per le richieste di annullamento.
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);

Avvia una sessione di traccia EventPipe usando un singolo provider.

  • provider: un EventPipeProvider per avviare il tracciamento.
  • requestRundown: un bool che specifica se devono essere richiesti gli eventi del provider di rundown dal runtime dell'app di destinazione.
  • circularBufferMB: un int che specifica le dimensioni totali del buffer circolare usato dal runtime dell'app di destinazione per la raccolta di eventi.
  • token (per l'overload asincrono): token da monitorare per le richieste di annullamento.
public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

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

Avvia una sessione di traccia EventPipe usando un oggetto EventPipeSessionConfiguration.

  • config / configuration : oggetto EventPipeSessionConfiguration che definisce la sessione.
  • token (per l'overload asincrono): token da monitorare per le richieste di annullamento.

Nota

Gli eventi di rundown contengono payload che possono essere necessari per l'analisi a posteriori, ad esempio la risoluzione dei nomi dei metodi dei campioni di thread. A meno che tu non sappia di non volerlo, si consiglia di impostare requestRundown su true. In applicazioni di grandi dimensioni, questa operazione può richiedere un po' di tempo.

Metodo WriteDump

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

Richiedere un dump per il debug post-mortem dell'applicazione di destinazione. È possibile specificare il tipo di dump usando l'enumerazione DumpType.

  • dumpType : tipo di dump da richiedere.
  • dumpPath : percorso del dump in cui scrivere.
  • logDumpGeneration : se impostato su true, l'applicazione di destinazione scriverà i log di diagnostica durante la generazione del dump.
public void WriteDump(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags)

Richiedere un dump per il debug post-mortem dell'applicazione di destinazione. È possibile specificare il tipo di dump usando l'enumerazione DumpType.

  • dumpType : tipo di dump da richiedere.
  • dumpPath : percorso del dump in cui scrivere.
  • flags : flag di registrazione e report di arresto anomalo del sistema. Nei runtime inferiori alla 6.0 è supportato solo LoggingEnabled.
public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    bool logDumpGeneration,
    CancellationToken token)

Richiedere un dump per il debug post-mortem dell'applicazione di destinazione. È possibile specificare il tipo di dump usando l'enumerazione DumpType.

  • dumpType : tipo di dump da richiedere.
  • dumpPath : percorso del dump in cui scrivere.
  • logDumpGeneration : se impostato su true, l'applicazione di destinazione scriverà i log di diagnostica durante la generazione del dump.
  • token : il token da monitorare per le richieste di annullamento.
public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags,
    CancellationToken token)

Richiedere un dump per il debug post-mortem dell'applicazione di destinazione. È possibile specificare il tipo di dump usando l'enumerazione DumpType.

  • dumpType : tipo di dump da richiedere.
  • dumpPath : percorso del dump in cui scrivere.
  • flags : flag di registrazione e report di arresto anomalo del sistema. Nei runtime inferiori alla 6.0 è supportato solo LoggingEnabled.
  • token : il token da monitorare per le richieste di annullamento.

Metodi ApplyStartupHook

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Carica l'assembly specificato con un StartupHook oggetto nel processo di destinazione.

  • startupHookPath : percorso dell'assembly contenente l'hook di avvio.
  • token (per l'overload asincrono): token da monitorare per le richieste di annullamento.

Metodi perfMap

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Controlla la generazione di mappe delle prestazioni nel processo di destinazione.

  • type PerfMapType: che indica il tipo di mapping delle prestazioni da abilitare.

Metodo AttachProfiler

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

Richiedere di collegare un ICorProfiler all'applicazione di destinazione.

  • attachTimeout : un TimeSpan dopo il quale il collegamento verrà interrotto.
  • profilerGuid : Guid dell'ICorProfiler da collegare.
  • profilerPath : percorso della dll ICorProfiler da collegare.
  • additionalData : dati aggiuntivi facoltativi che possono essere passati al runtime durante il collegamento del profiler.

Metodo SetStartupProfiler

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Impostare un profiler come profiler di avvio. È valido solo per eseguire questo comando mentre il runtime viene sospeso all'avvio.

  • profilerGuid : Guid per il profiler da collegare.
  • profilerPath : percorso del profiler da collegare.

Metodo ResumeRuntime

public void ResumeRuntime();

Indicare al runtime di riprendere l'esecuzione dopo che è stata sospesa all'avvio.

Metodo SetEnvironmentVariable

public void SetEnvironmentVariable(
    string name,
    string value);

Impostare una variabile di ambiente nel processo di destinazione.

  • name : nome della variabile di ambiente da impostare.
  • value : valore della variabile di ambiente da impostare.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Ottiene tutte le variabili di ambiente e i relativi valori dal processo di destinazione.

Metodo GetPublishedProcesses

public static IEnumerable<int> GetPublishedProcesses();

Ottenere un IEnumerable degli ID di processo di tutti i processi .NET attivi a cui è possibile collegarsi.

Classe EventPipeSessionConfiguration

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

Rappresenta la configurazione di un oggetto EventPipeSession.

  • providers : oggetto IEnumerable di EventPipeProviderda abilitare.
  • circularBufferSizeMB : dimensioni in MB del buffer del runtime per la raccolta di eventi.
  • requestRundown : se true, richiedere eventi di rundown dal runtime.
  • requestStackwalk : se true, registrare un'analisi dello stack per ogni evento generato.
  • rundownKeyword : maschera di parole chiave usata per gli eventi di rundown.

Classe EventPipeProvider

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

Costruttore

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

Crea una nuova istanza di EventPipeProvider con il nome del provider, EventLevel, le parole chiave e gli argomenti specificati.

Name - proprietà

public string Name { get; }

Ottiene il nome del provider.

Proprietà EventLevel

public EventLevel EventLevel { get; }

Ottiene il EventLevel dell'istanza specificata di EventPipeProvider.

Proprietà Keywords

public long Keywords { get; }

Ottiene un valore che rappresenta la maschera di bit per le parole chiave dell'oggetto EventSource.

Proprietà Arguments

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

Ottiene un IDictionary di stringhe di coppie chiave-valore che rappresentano argomenti facoltativi da passare a EventSource, che rappresenta l'oggetto specificato EventPipeProvider.

Osservazioni:

Questa classe non è modificabile perché EventPipe non consente la modifica della configurazione di un provider durante una sessione EventPipe a partire da .NET Core 3.1.

Classe EventPipeSession

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

    public void Stop();

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

Questa classe rappresenta una sessione EventPipe in corso. Non è modificabile e funge da handle per una sessione EventPipe del runtime specificato.

Proprietà EventStream

public Stream EventStream { get; }

Ottiene un Stream che può essere utilizzato per leggere il flusso di eventi.

Metodi stop

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

Arresta la sessione specificata EventPipe.

  • cancellationToken (per l'overload asincrono): token da monitorare per le richieste di annullamento.

Dispose (metodo)

public void Dispose();

Rilascia le risorse associate a EventPipeSession.

Classe DiagnosticsClientConnector

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

    public ValueTask DisposeAsync();

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

Rappresenta un helper che crea un oggetto DiagnosticsClient da una porta di diagnostica e gestisce la durata della connessione del server di diagnostica sottostante.

  • Instance DiagnosticsClient: oggetto connesso al runtime di destinazione.
  • DisposeAsync : elimina il server/connessione sottostante in modo asincrono.
  • FromDiagnosticPort : crea un nuovo DiagnosticsClientConnector oggetto dalla porta di diagnostica specificata.
public static Task<DiagnosticsClientConnector> FromDiagnosticPort(
    string diagnosticPort,
    CancellationToken ct)
  • diagnosticPort : stringa di porta di diagnostica (ad esempio, una porta di ascolto o connessione) da connettere.
  • ct : il token da monitorare per le richieste di annullamento.

Enumerazione DumpType

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

Rappresenta il tipo di dump che può essere richiesto.

  • Normal: includono solo le informazioni necessarie per acquisire le analisi dello stack di tutte le tracce esistenti per tutti i thread esistenti in un processo. Memoria e informazioni sull'heap GC limitate.
  • WithHeap: include gli heap GC e le informazioni necessarie per acquisire le analisi dello stack per tutti i thread esistenti in un processo.
  • Triage: includono solo le informazioni necessarie per acquisire le analisi dello stack di tutte le tracce esistenti per tutti i thread esistenti in un processo. Memoria e informazioni sull'heap GC limitate. Alcuni contenuti noti per contenere informazioni potenzialmente riservate, ad esempio i percorsi completi dei moduli, verranno elaborati. Sebbene ciò sia destinato a mitigare alcuni casi di esposizione dei dati sensibili, non esiste alcuna garanzia che questa funzionalità di rimozione sia sufficiente per rispettare qualsiasi legge specifica o standard sulla privacy dei dati.
  • Full: includono tutta la memoria accessibile nel processo. I dati di memoria non elaborati vengono inclusi alla fine, in modo che le strutture iniziali possano essere mappate direttamente senza le informazioni sulla memoria non elaborata. Questa opzione può comportare un file di dump molto grande.

Enumerazione WriteDumpFlags

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

Rappresenta opzioni aggiuntive che possono essere specificate quando si richiede un dump.

  • None : nessun comportamento aggiuntivo.
  • LoggingEnabled : abilitare la registrazione di base durante la generazione del dump.
  • VerboseLoggingEnabled : abilitare la registrazione dettagliata durante la generazione del dump.
  • CrashReportEnabled : abilitare la generazione di un report di arresto anomalo del sistema.

Enumerazione PerfMapType

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

Rappresenta il tipo di comportamento della mappa delle prestazioni che può essere abilitato.

  • None : nessun output mappa delle prestazioni.
  • All : abilitare tutti gli output della mappa delle prestazioni supportati dal runtime.
  • JitDump : abilitare l'output della mappa delle prestazioni dump JIT.
  • PerfMap : abilita l'output tradizionale della mappa delle prestazioni.

Eccezioni

Le eccezioni generate dalla libreria sono di tipo DiagnosticsClientException o di tipo derivato.

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

Può essere generata quando il comando non è supportato dalla libreria o dal runtime del processo di destinazione.

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Può essere generata quando il runtime del processo di destinazione non è compatibile con il protocollo IPC di diagnostica usato dalla libreria.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Può essere generata quando il runtime non è disponibile per i comandi IPC di diagnostica, ad esempio all'inizio dell'avvio del runtime prima che il runtime sia pronto per i comandi di diagnostica o quando il runtime viene arrestato.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Può essere generata quando il runtime risponde con un errore a un determinato comando.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

Questa eccezione viene generata quando un profiler è già caricato nel runtime di destinazione e viene tentato un altro collegamento.

  • Last updated on