Partilhar via

Microsoft.Diagnostics.NETCore.Client API

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

DiagnosticsClient classe

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

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 monitorizar pedidos 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);

Inicia uma sessão de rastreio EventPipe usando um único fornecedor.

  • 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 monitorizar pedidos de cancelamento.
public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

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

Inicia uma sessão de rastreamento EventPipe usando um EventPipeSessionConfiguration.

  • config / configuration : E EventPipeSessionConfiguration que define a sessão.
  • token (para a sobrecarga assíncrona): O token para monitorizar pedidos de cancelamento.

Nota

Os eventos de rundown contêm cargas úteis que podem ser necessárias para pós-análise, como a resolução de nomes de método de amostras de thread. A menos que você saiba que não quer isso, recomendamos a configuração requestRundown como true. Em aplicações grandes, isso pode demorar um pouco.

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 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 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étodos ApplyStartupHook

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Carrega o conjunto especificado com a StartupHook no processo alvo.

  • startupHookPath : O caminho até ao conjunto que contém o gancho de arranque.
  • token (para a sobrecarga assíncrona): O token para monitorizar pedidos de cancelamento.

Métodos PerfMap

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Controla a geração de mapas de performance no processo alvo.

  • type : A PerfMapType indicação do tipo de mapa de perfuração a permitir.

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.

Classe 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 a configuração para um EventPipeSession.

  • providers : An IEnumerable of EventPipeProviders para facilitar.
  • circularBufferSizeMB : O tamanho em MB do buffer do runtime para colecionar eventos.
  • requestRundown : Se true, solicitar eventos de rundown do tempo de execução.
  • requestStackwalk : Se true, regista um traço de pilha para cada evento emitido.
  • rundownKeyword : A máscara de palavras-chave usada para eventos de resumo.

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

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

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étodos de paragem

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

Interrompe a sessão dada EventPipe .

  • cancellationToken (para a sobrecarga assíncrona): O token para monitorizar pedidos de cancelamento.

Método de eliminação

public void Dispose();

Liberta recursos associados ao EventPipeSession.

Classe DiagnosticsClientConnector

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

    public ValueTask DisposeAsync();

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

Representa um helper que cria a DiagnosticsClient partir de uma porta de diagnóstico e gere a vida útil da ligação subjacente ao servidor de diagnóstico.

  • Instance : A DiagnosticsClient ligação ao tempo de execução alvo.
  • DisposeAsync : Elimina o servidor/ligação subjacente de forma assíncrona.
  • FromDiagnosticPort : Cria um novo DiagnosticsClientConnector a partir da porta de diagnóstico especificada.
public static Task<DiagnosticsClientConnector> FromDiagnosticPort(
    string diagnosticPort,
    CancellationToken ct)
  • diagnosticPort : A cadeia de portas de diagnóstico (por exemplo, uma porta de escuta ou de conexão) através da qual se deve ligar.
  • ct : O token para monitorar solicitações de cancelamento.

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.

WriteDumpFlags enum

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

Representa opções adicionais que podem ser especificadas ao solicitar um dump.

  • None : Sem comportamentos adicionais.
  • LoggingEnabled : Ativar o registo básico durante a geração de dumps.
  • VerboseLoggingEnabled : Ativar o registo verboso durante a geração de dumps.
  • CrashReportEnabled : Permitir a geração de um relatório de falha.

PerfMapType enum

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

Representa o tipo de comportamento do mapa de desempenho que pode ser ativado.

  • None : Sem saída de mapa de performance.
  • All : Ativar todas as saídas de perf map suportadas pelo runtime.
  • JitDump : Ativar a saída do mapa de desempenho do JIT dump.
  • PerfMap : Ativar a saída tradicional do mapa de desempenho.

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.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

Esta exceção é lançada quando um perfilador já está carregado no runtime de destino e outra anexação é tentada.

  • Last updated on