Microsoft.Diagnostics.NETCore.Client API

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

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

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

Inicia uma sessão de rastreamento do EventPipe usando um único provedor.

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

public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

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

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

• config / configuration : um EventPipeSessionConfiguration que define a sessão.
• token (para a sobrecarga assíncrona): o token a ser monitorado para solicitações de cancelamento.

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

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Carrega o assembly especificado com um StartupHook no processo de destino.

• startupHookPath : o caminho para o assembly que contém o gancho de inicialização.
• token (para a sobrecarga assíncrona): o token a ser monitorado para solicitações de cancelamento.

Métodos perfMap

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Controla a geração de mapas perf no processo de destino.

• type : o PerfMapType que indica o tipo de mapa perf a ser habilitado.

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 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 de um EventPipeSession.

• providers : um IEnumerable de EventPipeProviders para habilitar.
• circularBufferSizeMB : o tamanho em MB do buffer do runtime para coletar eventos.
• requestRundown : se true, solicite eventos de rundown do runtime.
• requestStackwalk : se true, registre um rastreamento de pilha para cada evento emitido.
• rundownKeyword : a máscara de palavra-chave usada para eventos de rundown.

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

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

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.

Parar métodos

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

Interrompe a sessão EventPipe determinada.

• cancellationToken (para a sobrecarga assíncrona): o token a ser monitorado para solicitações de cancelamento.

método Dispose

public void Dispose();

Libera 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 auxiliar que cria uma DiagnosticsClient porta de diagnóstico e gerencia o tempo de vida da conexão do servidor de diagnóstico subjacente.

• Instance : o DiagnosticsClient runtime de destino conectado.
• DisposeAsync : descarta o servidor/conexão subjacente de forma assíncrona.
• FromDiagnosticPort : cria uma nova DiagnosticsClientConnector a partir da porta de diagnóstico especificada.

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

• diagnosticPort : a cadeia de caracteres de porta de diagnóstico (por exemplo, uma porta de escuta ou conexão) pela qual se conectar.
• ct: o token a se monitorar para solicitações de cancelamento.

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.

Enumeração WriteDumpFlags

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

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

• None : nenhum comportamento adicional.
• LoggingEnabled : habilite o registro em log básico durante a geração de despejo.
• VerboseLoggingEnabled : habilite o log detalhado durante a geração de despejo.
• CrashReportEnabled : habilite a geração de um relatório de falha.

Enumeração PerfMapType

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

Representa o tipo de comportamento de mapa perf que pode ser habilitado.

• None : nenhuma saída de mapa perf.
• All : habilite todas as saídas de mapa perf compatíveis com o runtime.
• JitDump : habilite a saída do mapa do JIT dump perf.
• PerfMap : habilite a saída do mapa perf tradicional.

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.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

Essa exceção é gerada quando um criador de perfil já está carregado no runtime de destino e outra anexação é tentada.