API de Microsoft.Diagnostics.NETCore.Client

  • Artículo

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

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

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 para supervisar 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)
  • 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 para supervisar 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 async 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 async 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é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 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();
}

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étodo Stop

public void Stop();

Detiene la sesión de EventPipe especificada.

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

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.