Condividi tramite

API Microsoft.Diagnostics.NETCore.Client

  • Articolo

Questa sezione descrive le API della libreria client di diagnostica.

Classe DiagnosticsClient

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

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): il 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)
  • 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): il 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 async 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 async 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.

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

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.

Metodo Stop

public void Stop();

Arresta la sessione specificata EventPipe.

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.

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.