API de Microsoft.Diagnostics.NETCore.Client

En esta sección, se describen las API de la biblioteca cliente de diagnóstico.

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

Constructor

public DiagnosticsClient(int processId);

Crea una instancia de DiagnosticsClient para un proceso de .NET compatible que se ejecuta con el identificador de proceso de processId.

processID: identificador de proceso de la aplicación de destino.

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

Inicia una sesión de seguimiento de EventPipe con los proveedores y la configuración proporcionados.

  • providers: un elemento IEnumerable de EventPipeProvider para iniciar el seguimiento.
  • requestRundown: un valor bool que especifica si se deben solicitar eventos del proveedor de detención del entorno de ejecución de la aplicación de destino.
  • circularBufferMB: un elemento int que especifica el tamaño total del búfer circular utilizado por el entorno de ejecución de la aplicación de destino al recopilar eventos.
  • token (para la sobrecarga asincrónica): token que se va a supervisar para las solicitudes de cancelación.
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);

Inicia una sesión de seguimiento de EventPipe mediante un único proveedor.

  • provider: una clase EventPipeProvider para iniciar el seguimiento.
  • requestRundown: un valor bool que especifica si se deben solicitar eventos del proveedor de detención del entorno de ejecución de la aplicación de destino.
  • circularBufferMB: un elemento int que especifica el tamaño total del búfer circular utilizado por el entorno de ejecución de la aplicación de destino al recopilar eventos.
  • token (para la sobrecarga asincrónica): token que se va a supervisar para las solicitudes de cancelación.
public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

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

Inicia una sesión de seguimiento de EventPipe mediante .EventPipeSessionConfiguration

  • config / configuration : que EventPipeSessionConfiguration define la sesión.
  • token (para la sobrecarga asincrónica): token que se va a supervisar para las solicitudes de cancelación.

Nota:

Los eventos de detención contienen cargas que pueden ser necesarias para el análisis posterior, como la resolución de nombres de método de ejemplos de subprocesos. A menos que sepa que no quiere esto, se recomienda establecer requestRundown en true. En aplicaciones de gran tamaño, esto puede tardar un tiempo.

Método WriteDump

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

Solicite un volcado de memoria para la depuración final de la aplicación de destino. El tipo del volcado de memoria se puede especificar mediante la enumeración DumpType

  • dumpType: tipo del volcado de memoria que se va a solicitar.
  • dumpPath: ruta de acceso al volcado de memoria en el que se va a escribir.
  • logDumpGeneration: si se establece en true , la aplicación de destino escribirá los registros de diagnóstico durante la generación del volcado.
public void WriteDump(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags)

Solicite un volcado de memoria para la depuración final de la aplicación de destino. El tipo del volcado de memoria se puede especificar mediante la enumeración DumpType

  • dumpType: tipo del volcado de memoria que se va a solicitar.
  • dumpPath: ruta de acceso al volcado de memoria en el que se va a escribir.
  • flags: marcas de registro e informe de bloqueo. En los entornos de ejecución anteriores a la versión 6.0, solo se admite LoggingEnabled.
public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    bool logDumpGeneration,
    CancellationToken token)

Solicite un volcado de memoria para la depuración final de la aplicación de destino. El tipo del volcado de memoria se puede especificar mediante la enumeración DumpType

  • dumpType: tipo del volcado de memoria que se va a solicitar.
  • dumpPath: ruta de acceso al volcado de memoria en el que se va a escribir.
  • logDumpGeneration: si se establece en true , la aplicación de destino escribirá los registros de diagnóstico durante la generación del volcado.
  • token: token para supervisar las solicitudes de cancelación.
public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags,
    CancellationToken token)

Solicite un volcado de memoria para la depuración final de la aplicación de destino. El tipo del volcado de memoria se puede especificar mediante la enumeración DumpType

  • dumpType: tipo del volcado de memoria que se va a solicitar.
  • dumpPath: ruta de acceso al volcado de memoria en el que se va a escribir.
  • flags: marcas de registro e informe de bloqueo. En los entornos de ejecución anteriores a la versión 6.0, solo se admite LoggingEnabled.
  • token: token para supervisar las solicitudes de cancelación.

Métodos ApplyStartupHook

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Carga el ensamblado especificado con en StartupHook el proceso de destino.

  • startupHookPath : ruta de acceso al ensamblado que contiene el enlace de inicio.
  • token (para la sobrecarga asincrónica): token que se va a supervisar para las solicitudes de cancelación.

Métodos perfMap

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Controla la generación de asignaciones de rendimiento en el proceso de destino.

  • type PerfMapType: que indica el tipo de asignación de rendimiento que se va a habilitar.

Método AttachProfiler

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

Solicitud para adjuntar una interfaz ICorProfiler a la aplicación de destino.

  • attachTimeout: un elemento TimeSpan después del cual se anulará la conexión.
  • profilerGuid: Guid de la interfaz ICorProfiler que se va a adjuntar.
  • profilerPath: ruta de acceso al archivo dll de la interfaz ICorProfiler que se va a conectar.
  • additionalData: datos adicionales opcionales que se pueden pasar al entorno de ejecución durante la conexión del generador de perfiles.

Método SetStartupProfiler

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Establezca un generador de perfiles como generador de perfiles de inicio. Solo es válido emitir este comando cuando el entorno de ejecución se pausa durante el inicio.

  • profilerGuid: Guid para que se asocie el generador de perfiles.
  • profilerPath: ruta de acceso al generador de perfiles que se va a asociar.

Método ResumeRuntime

public void ResumeRuntime();

Indique al entorno de ejecución que reanude la ejecución después de pausarse al inicio.

Método SetEnvironmentVariable

public void SetEnvironmentVariable(
    string name,
    string value);

Establezca una variable de entorno en el proceso de destino.

  • name: el nombre de la variable de entorno que se va a establecer.
  • value: el valor de la variable de entorno que se va a establecer.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Obtiene todas las variables de entorno y sus valores correspondientes del proceso de destino.

Método GetPublishedProcesses

public static IEnumerable<int> GetPublishedProcesses();

Obtenga una interfaz IEnumerable de los identificadores de proceso de todos los procesos de .NET activos a los que se puede conectar.

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

Representa la configuración de un EventPipeSessionobjeto .

  • providers : de IEnumerableEventPipeProviders que se va a habilitar.
  • circularBufferSizeMB : el tamaño en MB del búfer del entorno de ejecución para recopilar eventos.
  • requestRundown : si truees , solicite eventos de ejecución desde el tiempo de ejecución.
  • requestStackwalk : si truees , registre un seguimiento de pila para cada evento emitido.
  • rundownKeyword : la máscara de palabra clave que se usa para los eventos de detención.
  • bufferingMode : para EventPipeBufferingMode la sesión. Use Block para solicitar una colección que no sea de pérdida. Pasar Block requiere un entorno de ejecución de destino de .NET 11+; en un entorno de ejecución anterior, StartEventPipeSession produce UnsupportedCommandException.

La BufferingMode propiedad devuelve el modo de almacenamiento en búfer de la sesión. El valor predeterminado, Drop, mantiene el búfer de pérdida del tiempo de ejecución.

Clase EventPipeProvider

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

Constructor

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)

Crea una instancia de EventPipeProvider con el nombre de proveedor, la enumeración EventLevel, las palabras claves y los argumentos especificados. La segunda sobrecarga también toma un EventPipeProviderEventFilter que filtra qué identificadores de evento habilita el tiempo de ejecución para el proveedor. Al establecer un filtro de eventos, la sesión requiere un entorno de ejecución de destino de más de 10 .NET.

Name (propiedad)

public string Name { get; }

Obtiene el nombre del proveedor.

Propiedad EventLevel

public EventLevel EventLevel { get; }

Obtiene el valor EventLevel de la instancia de EventPipeProvider especificada.

Propiedad Keywords

public long Keywords { get; }

Obtiene un valor que representa la máscara de bits para las palabras clave de EventSource.

Arguments (propiedad)

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

Obtiene un valor IDictionary de cadenas de par clave-valor que representan los argumentos opcionales que se van a pasar a EventSource para representar el elemento EventPipeProvider especificado.

Propiedad EventFilter

public EventPipeProviderEventFilter EventFilter { get; }

Obtiene la opción que EventPipeProviderEventFilter el tiempo de ejecución se aplica a los identificadores de evento de este proveedor después de la palabra clave y el filtro de nivel. Cuando el valor es null, el tiempo de ejecución habilita todos los identificadores de evento que permite la palabra clave y el filtro de nivel.

Observaciones

Esta clase es inmutable, porque EventPipe no permite modificar la configuración de un proveedor durante una sesión de EventPipe a partir de .NET Core 3.1.

Clase EventPipeProviderEventFilter

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

    public bool Enable { get; }

    public IReadOnlyList<uint> EventIds { get; }
}

Representa un filtro opcional por proveedor en identificadores de evento. El tiempo de ejecución aplica el filtro después de la palabra clave y el filtro de nivel del asociado EventPipeProvider. Los filtros de eventos requieren un entorno de ejecución de destino de más de 10 .NET.

Constructor

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

Crea una nueva instancia de EventPipeProviderEventFilter.

  • enable : si truees , eventIds es una lista de permitidos y el tiempo de ejecución solo habilita esos identificadores de evento. Si falsees , eventIds es una lista de denegación y el tiempo de ejecución habilita todos los identificadores de evento, excepto los enumerados. Por lo tanto, una lista de denegación vacía habilita todos los eventos.
  • eventIds : identificadores de evento para habilitar o deshabilitar, según lo determinado por enable.

Habilitar propiedad

public bool Enable { get; }

Obtiene un valor que indica si EventIds es una lista de permitidos (true) o una lista de denegación (false).

EventIds (propiedad)

public IReadOnlyList<uint> EventIds { get; }

Obtiene la lista de identificadores de evento que el filtro habilita o deshabilita.

Clase EventPipeSession

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

    public void Stop();

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

Esta clase representa una sesión de EventPipe en curso. Es inmutable y actúa como un identificador para una sesión de EventPipe del entorno de ejecución especificado.

Propiedad EventStream

public Stream EventStream { get; }

Obtiene un valor Stream que se puede usar para leer el flujo de eventos.

Métodos stop

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

Detiene la sesión de EventPipe especificada.

  • cancellationToken (para la sobrecarga asincrónica): token que se va a supervisar para las solicitudes de cancelación.

Dispose (método)

public void Dispose();

Libera los recursos asociados a .EventPipeSession

Clase DiagnosticsClientConnector

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

    public ValueTask DisposeAsync();

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

Representa un asistente que crea a DiagnosticsClient partir de un puerto de diagnóstico y administra la duración de la conexión del servidor de diagnóstico subyacente.

  • Instance : el DiagnosticsClient objeto conectado al entorno de ejecución de destino.
  • DisposeAsync : elimina el servidor o la conexión subyacentes de forma asincrónica.
  • FromDiagnosticPort : crea un nuevo DiagnosticsClientConnector a partir del puerto de diagnóstico especificado.
public static Task<DiagnosticsClientConnector> FromDiagnosticPort(
    string diagnosticPort,
    CancellationToken ct)
  • diagnosticPort : cadena de puerto de diagnóstico (por ejemplo, un puerto de escucha o conexión) a través de la que se va a conectar.
  • ct: token para supervisar las solicitudes de cancelación.

Enumeración DumpType

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

Representa el tipo de volcado de memoria que se puede solicitar.

  • Normal: incluya solo la información necesaria para capturar los seguimientos de la pila para todos los seguimientos y los subprocesos existentes en un proceso. Información y memoria del montón de GC limitadas.
  • WithHeap: incluya la información y los montones de GC necesarios para capturar seguimientos de la pila para todos los subprocesos existentes en un proceso.
  • Triage: incluya solo la información necesaria para capturar los seguimientos de la pila para todos los seguimientos y los subprocesos existentes en un proceso. Información y memoria del montón de GC limitadas. Se censurará parte del contenido que se sabe que contiene información potencialmente confidencial, como rutas de acceso de módulo completas. Aunque esto está pensado para mitigar algunos casos de exposición de datos confidenciales, no hay ninguna garantía de que esta característica de reacción por sí sola sea suficiente para cumplir con cualquier ley o norma concreta con respecto a la privacidad de los datos.
  • Full: incluya toda la memoria accesible en el proceso. Los datos de memoria sin procesar se incluyen al final, de modo que las estructuras iniciales se pueden asignar directamente sin la información de memoria sin procesar. Esta opción puede dar lugar a un archivo de volcado de memoria muy grande.

Enumeración WriteDumpFlags

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

Representa opciones adicionales que se pueden especificar al solicitar un volcado de memoria.

  • None : no hay ningún comportamiento adicional.
  • LoggingEnabled : habilite el registro básico durante la generación de volcados de memoria.
  • VerboseLoggingEnabled : habilite el registro detallado durante la generación de volcados de memoria.
  • CrashReportEnabled : habilite la generación de un informe de bloqueo.

Enumeración PerfMapType

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

Representa el tipo de comportamiento del mapa de rendimiento que se puede habilitar.

  • None : no hay salida de mapa de rendimiento.
  • All : habilite todas las salidas de mapa de rendimiento compatibles con el tiempo de ejecución.
  • JitDump : habilite la salida del mapa de perf de volcado JIT.
  • PerfMap : habilite la salida tradicional del mapa de rendimiento.

Enumeración EventPipeBufferingMode

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

Controla cómo se comporta el búfer de eventos por sesión del runtime cuando se rellena más rápido que la sesión lo purga.

  • Drop : valor predeterminado del entorno de ejecución. La sesión usa un búfer que quita eventos cuando se desborda, por lo que la recopilación se pierde.
  • Block : colección sin pérdida. El tiempo de ejecución bloquea los productores de eventos cuando el búfer está lleno en lugar de quitar eventos. Úselo para colecciones que deben completarse, como una instantánea del montón en un montón grande. Block no es una pérdida solo hasta la capacidad del búfer, no contra el agotamiento de memoria del host: si el tiempo de ejecución no puede asignar la memoria que necesita para reservar espacio de búfer o durante el apagado de la sesión, quita el evento en lugar de bloquear. Blockrequiere un entorno de ejecución de destino de .NET 11+ ; en un entorno de ejecución anterior, al iniciar la sesión se produce UnsupportedCommandException.

Excepciones

Las excepciones que se inician desde la biblioteca son de tipo DiagnosticsClientException o un tipo derivado.

public class DiagnosticsClientException : Exception

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Esto se puede producir cuando el entorno de ejecución del proceso de destino no es compatible con el protocolo IPC de diagnóstico usado por la biblioteca.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Esto se puede producir cuando el entorno de ejecución no está disponible para los comandos IPC de diagnóstico, como al principio del inicio del entorno de ejecución antes de que el entorno de ejecución esté listo para los comandos de diagnóstico, o cuando el entorno de ejecución se está apagando.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Esto se puede producir cuando el entorno de ejecución responde con un error a un comando determinado.

UnsupportedCommandException

public class UnsupportedCommandException : ServerErrorException

Esta excepción se produce cuando el comando no es compatible con la biblioteca o el tiempo de ejecución del proceso de destino.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

Esta excepción se produce cuando ya se carga un generador de perfiles en el tiempo de ejecución de destino y se intenta realizar otra asociación.

BadEncodingException

public class BadEncodingException : ServerErrorException

Esta excepción se produce cuando el tiempo de ejecución de destino no puede descodificar la carga del comando y la rechaza. Desde un cliente bien formado, normalmente significa que el tiempo de ejecución es demasiado antiguo para comprender un valor de opción configurado más reciente, por lo que rechaza la solicitud al analizar.

  • Última actualización o