API-интерфейс Microsoft.Diagnostics.NETCore.Client

  • Статья

В этом разделе описываются API-интерфейсы клиентской библиотеки диагностики.

Класс 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();
}

Конструктор

public DiagnosticsClient(int processId);

Создает новый экземпляр DiagnosticsClient для совместимого процесса .NET, выполняемого с идентификатором процесса processId.

processID указывает идентификатор процесса целевого приложения.

Методы 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);

Запускает сеанс трассировки EventPipe, используя указанные поставщики и параметры.

  • providers: IEnumerable для поставщиков EventPipeProvider для запуска трассировки.
  • requestRundown: значение bool, указывающее, должны ли быть запрошены события поставщика очистки из среды выполнения целевого приложения.
  • circularBufferMB: значение int, указывающее общий размер циклического буфера, используемого средой выполнения целевого приложения при сборе событий.
  • token (для перегрузки Async): маркер для отслеживания запросов на отмену.
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: значение EventPipeProvider для запуска трассировки.
  • requestRundown: значение bool, указывающее, должны ли быть запрошены события поставщика очистки из среды выполнения целевого приложения.
  • circularBufferMB: значение int, указывающее общий размер циклического буфера, используемого средой выполнения целевого приложения при сборе событий.
  • token (для перегрузки Async): маркер для отслеживания запросов на отмену.

Примечание.

События очистки содержат полезные данные, которые могут потребоваться для последующего анализа, например разрешения имен методов для примеров потоков. Если вы не знаете, что это не требуется, рекомендуется задать requestRundown значение true. В больших приложениях это может занять некоторое время.

Метод WriteDump

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

Запросите дамп для отладки целевого приложения после аварийного завершения. Тип дампа можно указать с помощью перечисления DumpType.

  • dumpType: тип дампа, который требуется запросить.
  • dumpPath: путь, по которому будет записан дамп.
  • logDumpGeneration: если задано значение true, целевое приложение будет записывать журналы диагностики во время создания дампа.
public void WriteDump(DumpType dumpType, string dumpPath, WriteDumpFlags flags)

Запросите дамп для отладки целевого приложения после аварийного завершения. Тип дампа можно указать с помощью перечисления DumpType.

  • dumpType: тип дампа, который требуется запросить.
  • dumpPath: путь, по которому будет записан дамп.
  • flags : флаги отчетов о ведении журнала и сбоях. В средах выполнения меньше 6.0 поддерживается только LoggingEnabled.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, bool logDumpGeneration, CancellationToken token)

Запросите дамп для отладки целевого приложения после аварийного завершения. Тип дампа можно указать с помощью перечисления DumpType.

  • dumpType: тип дампа, который требуется запросить.
  • dumpPath: путь, по которому будет записан дамп.
  • logDumpGeneration: если задано значение true, целевое приложение будет записывать журналы диагностики во время создания дампа.
  • token : маркер для отслеживания запросов на отмену.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, WriteDumpFlags flags, CancellationToken token)

Запросите дамп для отладки целевого приложения после аварийного завершения. Тип дампа можно указать с помощью перечисления DumpType.

  • dumpType: тип дампа, который требуется запросить.
  • dumpPath: путь, по которому будет записан дамп.
  • flags : флаги отчетов о ведении журнала и сбоях. В средах выполнения меньше 6.0 поддерживается только LoggingEnabled.
  • token : маркер для отслеживания запросов на отмену.

Метод AttachProfiler

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

Запрос на присоединение ICorProfiler к целевому приложению.

  • attachTimeout: время TimeSpan, по истечении которого присоединение будет прервано.
  • profilerGuid : Guid iCorProfiler, который необходимо подключить.
  • profilerPath: путь к профилировщику ICorProfiler, который необходимо присоединить.
  • additionalData: необязательные дополнительные данные, которые могут быть переданы в среду выполнения во время присоединения профилировщика.

Метод SetStartupProfiler

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Задайте профилировщик в качестве профилировщика запуска. Это допустимо только для выполнения этой команды, пока среда выполнения приостановлена при запуске.

  • profilerGuid : Guid для присоединенного профилировщика.
  • profilerPath : Путь к профилировщику для подключения.

Метод ResumeRuntime

public void ResumeRuntime();

Сообщите среде выполнения возобновить выполнение после приостановки при запуске.

Метод SetEnvironmentVariable

public void SetEnvironmentVariable(
    string name,
    string value);

Задайте переменную среды в целевом процессе.

  • name : имя заданной переменной среды.
  • value : значение заданной переменной среды.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Возвращает все переменные среды и их значения из целевого процесса.

Метод GetPublishedProcesses

public static IEnumerable<int> GetPublishedProcesses();

Получение IEnumerable для идентификаторов всех активных процессов .NET, поддерживающих присоединение.

Класс 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);
}

Конструктор

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

Создает новый экземпляр EventPipeProvider с заданными именем поставщика, EventLevel, ключевыми словами и аргументами.

Name, свойство

public string Name { get; }

Получает имя поставщика.

Свойство EventLevel

public EventLevel EventLevel { get; }

Получает EventLevel для заданного экземпляра EventPipeProvider.

Свойство Keywords

public long Keywords { get; }

Получает значение, представляющее битовую маску для ключевых слов EventSource.

Свойство Arguments

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

Возвращает IDictionary для строк пар "ключ-значение", представляющих необязательные аргументы, которые должны быть переданы в источник EventSource, представляющий заданный поставщик EventPipeProvider.

Замечания

Этот класс является неизменяемым, так как EventPipe не позволяет изменять конфигурацию поставщика во время сеанса EventPipe в .NET Core 3.1.

Класс EventPipeSession

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

Этот класс представляет выполняющийся сеанс EventPipe. Он является неизменяемым и действует как обработчик сеанса EventPipe данной среды выполнения.

Свойство EventStream

public Stream EventStream { get; }

Получает значение Stream, которое может использоваться для считывания потока событий.

Метод Stop

public void Stop();

Останавливает данный сеанс EventPipe.

Перечисление DumpType

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

Представляет тип дампа, который можно запросить.

  • Normal: добавляет только сведения, необходимые для записи трассировок стека для всех существующих трассировок для всех имеющихся потоков в процессе. Ограниченная память кучи сборки мусора и информация.
  • WithHeap: добавляет кучи сборки мусора и сведения, необходимые для записи трассировок стека для всех существующих потоков в процессе.
  • Triage: добавляет только сведения, необходимые для записи трассировок стека для всех существующих трассировок для всех имеющихся потоков в процессе. Ограниченная память кучи сборки мусора и информация.
  • Full: задействует для процесса всю доступную память. Необработанные данные памяти включаются в конец, чтобы начальные структуры можно было сопоставить напрямую без необработанных данных памяти. Этот вариант может привести к созданию очень большого файла дампа.

Исключения

Исключения, выдаваемые из библиотеки, имеют тип DiagnosticsClientException или производный от него.

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

Может выдаваться в связи с тем, что команда не поддерживается библиотекой или средой выполнения целевого процесса.

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Может выдаваться в связи с тем, что среда выполнения целевого процесса несовместима с IPC-протоколом диагностики, используемым библиотекой.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Может выдаваться в связи с тем, что среда выполнения недоступна для диагностических команд IPC, например при раннем запуске во время выполнения до того, как среда выполнения будет готова к выполнению команд диагностики, или когда среда выполнения завершает работу.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Может выдаваться в связи с тем, что среда выполнения отвечает ошибкой на данную команду.