API Microsoft.Diagnostics.NETCore.Client

  • Article

Cette section décrit les API de la bibliothèque de client de diagnostics.

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

Constructeur

public DiagnosticsClient(int processId);

Crée une instance de DiagnosticsClient pour un processus .NET compatible exécuté avec l’ID de processus de processId.

processID : ID de processus de l’application cible.

Méthodes 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);

Démarre une session de suivi EventPipe à l’aide des fournisseurs et paramètres donnés.

  • providers : IEnumerable de EventPipeProviders permettant de lancer le suivi.
  • requestRundown : bool spécifiant si les événements du fournisseur d’arrêt du runtime de l’application cible doivent être demandés.
  • circularBufferMB : int spécifiant la taille totale de la mémoire tampon circulaire utilisée par le runtime de l’application cible lors de la collecte d’événements.
  • token (pour la surcharge Asynchrone) : jeton permettant de surveiller les requêtes d’annulation.
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 : EventPipeProvider permettant de lancer le suivi.
  • requestRundown : bool spécifiant si les événements du fournisseur d’arrêt du runtime de l’application cible doivent être demandés.
  • circularBufferMB : int spécifiant la taille totale de la mémoire tampon circulaire utilisée par le runtime de l’application cible lors de la collecte d’événements.
  • token (pour la surcharge Asynchrone) : jeton permettant de surveiller les requêtes d’annulation.

Remarque

Les événements d’arrêt contiennent des charges utiles qui peuvent être nécessaires dans le cadre d’une analyse ultérieure, comme la résolution des noms de méthodes des exemples de threads. Sauf si vous ne le souhaitez pas, nous vous recommandons de définir cette valeur requestRundown sur true. Dans les applications volumineuses, cette opération peut prendre un certain temps.

Méthode WriteDump

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

Demande une image mémoire pour le débogage post-mortem de l’application cible. Le type d’image mémoire peut être spécifié à l’aide de l’énumération DumpType.

  • dumpType : type d’image mémoire à demander.
  • dumpPath : chemin d’accès à l’image mémoire destinée à l’écriture.
  • logDumpGeneration : si la valeur est définie sur true, l’application cible écrit les journaux de diagnostic pendant la génération de l’image mémoire.
public void WriteDump(DumpType dumpType, string dumpPath, WriteDumpFlags flags)

Demande une image mémoire pour le débogage post-mortem de l’application cible. Le type d’image mémoire peut être spécifié à l’aide de l’énumération DumpType.

  • dumpType : type d’image mémoire à demander.
  • dumpPath : chemin d’accès à l’image mémoire destinée à l’écriture.
  • flags : indicateurs de journalisation et de rapport d’incident. Sur les runtimes antérieurs à la version 6.0, seul LoggingEnabled est pris en charge.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, bool logDumpGeneration, CancellationToken token)

Demande une image mémoire pour le débogage post-mortem de l’application cible. Le type d’image mémoire peut être spécifié à l’aide de l’énumération DumpType.

  • dumpType : type d’image mémoire à demander.
  • dumpPath : chemin d’accès à l’image mémoire destinée à l’écriture.
  • logDumpGeneration : si la valeur est définie sur true, l’application cible écrit les journaux de diagnostic pendant la génération de l’image mémoire.
  • token : jeton permettant de surveiller les requêtes d’annulation.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, WriteDumpFlags flags, CancellationToken token)

Demande une image mémoire pour le débogage post-mortem de l’application cible. Le type d’image mémoire peut être spécifié à l’aide de l’énumération DumpType.

  • dumpType : type d’image mémoire à demander.
  • dumpPath : chemin d’accès à l’image mémoire destinée à l’écriture.
  • flags : indicateurs de journalisation et de rapport d’incident. Sur les runtimes antérieurs à la version 6.0, seul LoggingEnabled est pris en charge.
  • token : jeton permettant de surveiller les requêtes d’annulation.

Méthode AttachProfiler

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

Demande d’attachement d’un ICorProfiler à l’application cible.

  • attachTimeout : TimeSpan après lequel l’attachement sera abandonné.
  • profilerGuid : Guid du ICorProfiler à attacher.
  • profilerPath : chemin d’accès à la dll ICorProfiler à attacher.
  • additionalData : données supplémentaires facultatives qui peuvent être transmises au runtime pendant l’attachement du profileur.

Méthode SetStartupProfiler

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Définit un profileur comme profileur de démarrage. Cette commande n’est valide que lorsque le runtime est suspendu au démarrage.

  • profilerGuid : Guid du profileur à attacher.
  • profilerPath : chemin d’accès au profileur à attacher.

Méthode ResumeRuntime

public void ResumeRuntime();

Indique au runtime de reprendre l’exécution après une pause au démarrage.

Méthode SetEnvironmentVariable

public void SetEnvironmentVariable(
    string name,
    string value);

Définit une variable d’environnement dans le processus cible.

  • name : nom de la variable d'environnement à définir.
  • value : valeur de la variable d’environnement à définir.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Obtient toutes les variables d’environnement et leurs valeurs à partir du processus cible.

Méthode GetPublishedProcesses

public static IEnumerable<int> GetPublishedProcesses();

Obtient un IEnumerable d’ID de processus pour tous les processus .NET actifs qui peuvent être attachés.

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

Constructeur

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

Crée une instance de EventPipeProvider avec le nom du fournisseur, EventLevel, les mots clés et les arguments donnés.

Nom de la propriété

public string Name { get; }

Obtient le nom du fournisseur.

Propriété EventLevel

public EventLevel EventLevel { get; }

Obtient le EventLevel de l’instance donnée de EventPipeProvider.

Propriété Keywords

public long Keywords { get; }

Obtient une valeur qui représente le masque de bits pour les mots clés de la EventSource.

Arguments (propriété)

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

Obtient un IDictionary de chaînes de paires clé-valeur représentant des arguments facultatifs à transmettre à la EventSource qui représente le EventPipeProvider donné.

Remarques

Cette classe est immuable car, à partir de .NET Core 3.1, EventPipe ne permet pas de modifier la configuration d’un fournisseur pendant une session EventPipe.

Classe EventPipeSession

public class EventPipeSession : IDisposable
{
    public Stream EventStream { get; }
    public void Stop();
}

Cette classe représente une session EventPipe en cours. Elle est immuable et sert de descripteur à une session EventPipe du runtime donné.

Propriété EventStream

public Stream EventStream { get; }

Obtient un Stream qui peut être utilisé pour lire le flux d’événements.

Stop, méthode

public void Stop();

Arrête la session EventPipe donnée.

Énumération DumpType

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

Représente le type d’image mémoire qui peut être demandé.

  • Normal : comprend uniquement les informations nécessaires à la capture des rapports de tous les appels de procédure existants pour tous les threads existants au sein d’un processus. Mémoire et informations de tas GC limitées.
  • WithHeap : comprend les tas GC et les informations nécessaires à la capture des rapports d’appels de procédure pour tous les threads existants au sein d’un processus.
  • Triage : comprend uniquement les informations nécessaires à la capture des rapports de tous les appels de procédure existants pour tous les threads existants au sein d’un processus. Mémoire et informations de tas GC limitées.
  • Full : comprend toute la mémoire accessible dans le processus. Les données de mémoire brute sont incluses à la fin, afin que les structures initiales puissent être mappées directement sans les informations de mémoire brute. Cette option peut générer un fichier d’image mémoire très volumineux.

Exceptions

Les exceptions levées à partir de la bibliothèque sont de type DiagnosticsClientException ou d’un type dérivé.

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

Cette exception peut être levée lorsque la commande n’est pas prise en charge par la bibliothèque ou par le runtime du processus cible.

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Cette exception peut être levée lorsque le runtime du processus cible n’est pas compatible avec le protocole IPC de diagnostic utilisé par la bibliothèque.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Cette exception peut être levée lorsque le runtime n’est pas disponible pour les commandes IPC de diagnostic, par exemple au début du démarrage de l’exécution avant que le runtime soit prêt pour les commandes de diagnostic, ou lorsque le runtime est arrêté.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Cette exception peut être levée lorsque le runtime répond en envoyant une erreur à une commande donnée.