Compartilhar via

Microsoft.Diagnostics.NETCore.Client API

  • Artigo

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

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

Construtor

public DiagnosticsClient(int processId);

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

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

  • providers: um IEnumerable de EventPipeProviders para iniciar o rastreamento.
  • requestRundown um bool que especifica se os eventos do provedor de rundown do runtime do aplicativo de destino devem ser solicitados.
  • circularBufferMB: um int que especifica o tamanho total do buffer circular usado pelo runtime do aplicativo de destino na coleta de eventos.
  • token (para a sobrecarga Assíncrona): o token a ser monitorado para 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 iniciar o rastreamento.
  • requestRundown um bool que especifica se os eventos do provedor de rundown do runtime do aplicativo de destino devem ser solicitados.
  • circularBufferMB: um int que especifica o tamanho total do buffer circular usado pelo runtime do aplicativo de destino na coleta de eventos.
  • token (para a sobrecarga Assíncrona): o token a ser monitorado para solicitações de cancelamento.

Observação

Os eventos de rundown contêm cargas que podem ser necessárias para pós-análise, como a resolução de nomes de método dos exemplos de thread. A menos que você saiba que não deseja isso, recomendamos definir requestRundown como verdadeiro. Em aplicativos grandes, pode demorar um pouco.

Método WriteDump

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

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

  • dumpType: tipo do despejo a ser solicitado.
  • dumpPath: o caminho para o despejo a ser gravado.
  • logDumpGeneration: se definido como true, o aplicativo de destino gravará os logs de diagnóstico durante a geração de despejo.
public void WriteDump(DumpType dumpType, string dumpPath, WriteDumpFlags flags)

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

  • dumpType: tipo do despejo a ser solicitado.
  • dumpPath: o caminho para o despejo a ser gravado.
  • flags: sinalizadores de relatório de log e de falha. Em runtimes anteriores ao 6.0, há suporte apenas para LoggingEnabled.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, bool logDumpGeneration, CancellationToken token)

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

  • dumpType: tipo do despejo a ser solicitado.
  • dumpPath: o caminho para o despejo a ser gravado.
  • logDumpGeneration: se definido como true, o aplicativo de destino gravará os logs de diagnóstico durante a geração de despejo.
  • token: o token a se monitorar para solicitações de cancelamento.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, WriteDumpFlags flags, CancellationToken token)

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

  • dumpType: tipo do despejo a ser solicitado.
  • dumpPath: o caminho para o despejo a ser gravado.
  • flags: sinalizadores de relatório de log e de falha. Em runtimes anteriores ao 6.0, há suporte apenas para LoggingEnabled.
  • token: o token a se monitorar para solicitações de cancelamento.

Método AttachProfiler

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

Solicite a anexação de um ICorProfiler ao aplicativo de destino.

  • attachTimeout: um TimeSpan após o qual a anexação será anulada.
  • profilerGuid: Guid do ICorProfiler a ser anexado.
  • profilerPath: caminho para o ICorProfiler dll a ser anexado.
  • additionalData: dados adicionais opcionais que podem ser passados para o runtime durante a anexação do criador de perfil.

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 esse comando enquanto o runtime estiver 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();

Informa ao runtime para retomar a execução depois de fazer uma pausa na inicialização.

Método SetEnvironmentVariable

public void SetEnvironmentVariable(
    string name,
    string value);

Define 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 ser definida.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

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

Método GetPublishedProcesses

public static IEnumerable<int> GetPublishedProcesses();

Obtém uma IEnumerable das IDs do processo de todos os processos ativos do .NET que podem ser anexados.

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

Construtor

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

Cria uma nova instância de EventPipeProvider com o nome do provedor fornecido, EventLevel, palavras-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 de determinada instância de EventPipeProvider.

Propriedade Keywords

public long Keywords { get; }

Obtém um valor que representa o bitmask para palavras-chave do EventSource.

Propriedade Arguments

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

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

Comentários

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

Classe EventPipeSession

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

Esta classe representa uma sessão EventPipe em andamento. Ela é imutável e atua como identificador para uma sessão EventPipe do runtime especificado.

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

Enumeração DumpType

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

Representa o tipo de despejo que pode ser solicitado.

  • Normal: inclui 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 limitadas de heap do GC.
  • WithHeap: inclui os heaps de GC e as informações necessárias para capturar rastreamentos de pilha para todos os threads existentes em um processo.
  • Triage: inclui 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 limitadas de heap do GC. Alguns conteúdos conhecidos por conter informações potencialmente confidenciais, como caminhos completos do módulo, 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 relacionado à privacidade de dados.
  • Full: inclui 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 geradas na biblioteca são do tipo DiagnosticsClientException ou de um tipo derivado.

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

Pode ser gerado quando não há suporte para o comando na biblioteca ou no runtime do processo de destino.

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Pode ser gerado quando o runtime do processo de destino não é compatível com o protocolo IPC de diagnóstico usado pela biblioteca.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Pode ser gerado quando o runtime não está disponível para comandos de IPC de diagnóstico, como na inicialização do runtime antes que o runtime esteja pronto para comandos de diagnóstico ou quando o runtime está sendo desligado.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Pode ser gerado quando o runtime responde com um erro a determinado comando.