Microsoft.Diagnostics.NETCore.Client API

Esta seção descreve as APIs da biblioteca de cliente de diagnóstico.

DiagnosticsClient classe

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

Construtor

public DiagnosticsClient(int processId);

Cria uma nova instância do DiagnosticsClient para um processo .NET compatível em execução com a ID do processo .processId

processID : ID do processo do aplicativo 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 uma sessão de rastreamento do EventPipe usando os provedores e configurações fornecidos.

• providers : Um IEnumerable de EventPipeProviders para iniciar o rastreamento.
• requestRundown: A bool especificando se os eventos do provedor de rundown do tempo de execução do aplicativo de destino devem ser solicitados.
• circularBufferMB: Uma int especificação do tamanho total do buffer circular usado pelo tempo de execução do aplicativo de destino na coleta de eventos.
• token (para a sobrecarga Assíncrona): O token para monitorar solicitações de cancelamento.

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 : Um EventPipeProvider para começar a traçar.
• requestRundown: A bool especificando se os eventos do provedor de rundown do tempo de execução do aplicativo de destino devem ser solicitados.
• circularBufferMB: Uma int especificação do tamanho total do buffer circular usado pelo tempo de execução do aplicativo de destino na coleta de eventos.
• token (para a sobrecarga Assíncrona): O token para monitorar solicitações de cancelamento.

Método WriteDump

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

Solicite um dump para depuração post-mortem do aplicativo de destino. O tipo de despejo pode ser especificado usando o DumpType enum.

• dumpType : Tipo de despejo a ser solicitado.
• dumpPath : O caminho para o despejo a ser escrito.
• logDumpGeneration : Se definido como true, o aplicativo de destino gravará logs de diagnóstico durante a geração de dump.

public void WriteDump(DumpType dumpType, string dumpPath, WriteDumpFlags flags)

Solicite um dump para depuração post-mortem do aplicativo de destino. O tipo de despejo pode ser especificado usando o DumpType enum.

• dumpType : Tipo de despejo a ser solicitado.
• dumpPath : O caminho para o despejo a ser escrito.
• flags : sinalizadores de registro e relatório de falhas. Em tempos de execução inferiores a 6.0, apenas LoggingEnabled é suportado.

public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, bool logDumpGeneration, CancellationToken token)

Solicite um dump para depuração post-mortem do aplicativo de destino. O tipo de despejo pode ser especificado usando o DumpType enum.

• dumpType : Tipo de despejo a ser solicitado.
• dumpPath : O caminho para o despejo a ser escrito.
• logDumpGeneration : Se definido como true, o aplicativo de destino gravará logs de diagnóstico durante a geração de dump.
• token : O token para monitorar solicitações de cancelamento.

public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, WriteDumpFlags flags, CancellationToken token)

Solicite um dump para depuração post-mortem do aplicativo de destino. O tipo de despejo pode ser especificado usando o DumpType enum.

• dumpType : Tipo de despejo a ser solicitado.
• dumpPath : O caminho para o despejo a ser escrito.
• flags : sinalizadores de registro e relatório de falhas. Em tempos de execução inferiores a 6.0, apenas LoggingEnabled é suportado.
• token : O token para monitorar solicitações de cancelamento.

Método AttachProfiler

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

Solicitação para anexar um ICorProfiler ao aplicativo de destino.

• attachTimeout : A TimeSpan após o qual anexar será abortado.
• profilerGuid : Guid do ICorProfiler a anexar.
• profilerPath : Caminho para a dll ICorProfiler a ser anexada.
• additionalData : Dados adicionais opcionais que podem ser passados para o tempo de execução durante a conexão do profiler.

Método SetStartupProfiler

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Defina um criador de perfil como o criador de perfil de inicialização. Só é válido emitir este comando enquanto o tempo de execução é pausado na inicialização.

• profilerGuid : Guid para que o criador de perfil seja anexado.
• profilerPath : Caminho para o criador de perfil a ser anexado.

Método ResumeRuntime

public void ResumeRuntime();

Diga ao tempo de execução para retomar a execução depois de ser pausado na inicialização.

Método SetEnvironmentVariable

public void SetEnvironmentVariable(
    string name,
    string value);

Defina uma variável de ambiente no processo de destino.

• name : O nome da variável de ambiente a ser definida.
• value : O valor da variável de ambiente a definir.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Obtém todas as variáveis de ambiente e seus valores do processo de destino.

Método GetPublishedProcesses

public static IEnumerable<int> GetPublishedProcesses();

Obtenha uma IEnumerable das IDs de processo de todos os processos .NET ativos que podem ser anexados.

EventPipeProvider classe

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

Construtor

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

Cria uma nova instância de com o nome do EventPipeProvider provedor fornecido, EventLevelpalavras-chave e argumentos.

Propriedade Name

public string Name { get; }

Obtém o nome do provedor.

Propriedade EventLevel

public EventLevel EventLevel { get; }

Obtém o EventLevel da instância dada de EventPipeProvider.

Propriedade Palavras-chave

public long Keywords { get; }

Obtém um valor que representa a máscara de bits para palavras-chave do EventSource.

Propriedade Arguments

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

Obtém uma IDictionary das cadeias de caracteres de par chave-valor que representam argumentos opcionais a serem passados para EventSource representar o dado EventPipeProvider.

Observações

Essa classe é imutável, porque o EventPipe não permite que a configuração de um provedor seja modificada durante uma sessão do EventPipe a partir do .NET Core 3.1.

EventPipeSession classe

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

Essa classe representa uma sessão EventPipe em andamento. Ele é imutável e atua como um identificador para uma sessão EventPipe do tempo de execução determinado.

Propriedade EventStream

public Stream EventStream { get; }

Obtém um Stream que pode ser usado para ler o fluxo de eventos.

Método Stop

public void Stop();

Interrompe a sessão dada EventPipe .

Enum DumpType

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

Representa o tipo de despejo que pode ser solicitado.

• Normal: Inclua apenas as informações necessárias para capturar rastreamentos de pilha para todos os rastreamentos existentes para todos os threads existentes em um processo. Memória e informações de pilha GC limitadas.
• WithHeap: Inclui os heaps GC e as informações necessárias para capturar rastreamentos de pilha para todos os threads existentes em um processo.
• Triage: Inclua apenas as informações necessárias para capturar rastreamentos de pilha para todos os rastreamentos existentes para todos os threads existentes em um processo. Memória e informações de pilha GC limitadas. Alguns conteúdos conhecidos por conterem informações potencialmente confidenciais, como caminhos de módulos completos, serão editados. Embora isso se destine a mitigar alguns casos de exposição de dados confidenciais, não há garantia de que esse recurso de redação, por si só, seja suficiente para cumprir qualquer lei ou padrão específico em relação à privacidade de dados.
• Full: Inclua toda a memória acessível no processo. Os dados de memória bruta são incluídos no final, para que as estruturas iniciais possam ser mapeadas diretamente sem as informações de memória bruta. Essa opção pode resultar em um arquivo de despejo muito grande.

Exceções

As exceções lançadas da biblioteca são do tipo DiagnosticsClientException ou de um tipo derivado.

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

Isso pode ser lançado quando o comando não é suportado pela biblioteca ou pelo tempo de execução do processo de destino.

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Isso pode ser lançado quando o tempo de execução do processo de destino não é compatível com o protocolo IPC de diagnóstico usado pela biblioteca.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Isso pode ser gerado quando o tempo de execução não está disponível para comandos IPC de diagnóstico, como no início da inicialização do tempo de execução antes que o tempo de execução esteja pronto para comandos de diagnóstico ou quando o tempo de execução estiver sendo desligado.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Isso pode ser lançado quando o tempo de execução responde com um erro a um determinado comando.