Compartir a través de

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 bool RequestRundown { get; }

    public int CircularBufferSizeInMB { get; }

    public bool RequestStackwalk { get; }

    public long RundownKeyword { 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.

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

Constructor

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

Crea una instancia de EventPipeProvider con el nombre de proveedor, la enumeración EventLevel, las palabras claves y los argumentos especificados.

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.

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 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.

Excepciones

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

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

Esto se puede producir cuando el comando no es compatible con la biblioteca ni con el entorno de ejecución del proceso de destino.

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.

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.

  • Last updated on