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

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

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

Конструктор

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 (для асинхронной перегрузки): маркер для отслеживания запросов на отмену.

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

Запускает сеанс трассировки EventPipe с помощью одного поставщика.

provider: значение EventPipeProvider для запуска трассировки.
requestRundown: значение bool, указывающее, должны ли быть запрошены события поставщика очистки из среды выполнения целевого приложения.
circularBufferMB: значение int, указывающее общий размер циклического буфера, используемого средой выполнения целевого приложения при сборе событий.
token (для асинхронной перегрузки): маркер для отслеживания запросов на отмену.

public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

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

Запускает сеанс трассировки EventPipe с помощью .EventPipeSessionConfiguration

config / configuration : значение, определяющее EventPipeSessionConfiguration сеанс.
token (для асинхронной перегрузки): маркер для отслеживания запросов на отмену.

Примечание.

События очистки содержат полезные данные, которые могут потребоваться для последующего анализа, например разрешения имен методов для примеров потоков. Если вы не знаете, что это не требуется, рекомендуется задать 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: тип дампа, который требуется запросить.
dumpPath: путь, по которому будет записан дамп.
flags : флаги отчетов о ведении журнала и сбоях. В средах выполнения меньше 6.0 поддерживается только LoggingEnabled.

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

dumpType: тип дампа, который требуется запросить.
dumpPath: путь, по которому будет записан дамп.
logDumpGeneration: если задано значение true, целевое приложение будет записывать журналы диагностики во время создания дампа.
token : маркер для отслеживания запросов на отмену.

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

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

Методы ApplyStartupHook

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Загружает указанную сборку с целевым процессом StartupHook .

startupHookPath : Путь к сборке, содержащей перехватчик запуска.
token (для асинхронной перегрузки): маркер для отслеживания запросов на отмену.

Методы PerfMap

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Управляет созданием карт perf в целевом процессе.

type : указывает PerfMapType тип карты perf для включения.

Метод 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, поддерживающих присоединение.

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

Представляет конфигурацию для EventPipeSessionобъекта .

providers : значение IEnumerableEventPipeProviders для включения.
circularBufferSizeMB : размер в МБ буфера среды выполнения для сбора событий.
requestRundown : Если trueзапросите события запуска из среды выполнения.
requestStackwalk : если true, запишите трассировку стека для каждого из создаваемых событий.
rundownKeyword : маска ключевых слов, используемая для событий запуска.

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

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

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

Свойство EventStream

public Stream EventStream { get; }

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

Остановить методы

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

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

cancellationToken (для асинхронной перегрузки): маркер для отслеживания запросов на отмену.

метод очистки Dispose

public void Dispose();

Освобождает ресурсы, связанные с .EventPipeSession

Класс DiagnosticsClientConnector

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

    public ValueTask DisposeAsync();

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

Представляет вспомогательный элемент, который создает DiagnosticsClient из порта диагностики и управляет временем существования подключения к базовому серверу диагностики.

Instance : подключено DiagnosticsClient к целевой среде выполнения.
DisposeAsync : удаляет базовый сервер или подключение асинхронно.
FromDiagnosticPort : создает новый из DiagnosticsClientConnector указанного порта диагностики.

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

diagnosticPort : строка порта диагностики (например, прослушиватель или подключение) для подключения.
ct : маркер для отслеживания запросов на отмену.

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

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

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

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

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

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

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

None : нет дополнительного поведения.
LoggingEnabled : включите базовое ведение журнала во время создания дампа.
VerboseLoggingEnabled : включите подробное ведение журнала во время создания дампа.
CrashReportEnabled : включите создание отчета о сбоях.

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

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

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

None : нет выходных данных карты perf.
All : включите все выходные данные карты perf, поддерживаемые средой выполнения.
JitDump : включите выходные данные дампа JIT для карты.
PerfMap : включите традиционные выходные данные карты perf.

Исключения

Исключения, выдаваемые из библиотеки, имеют тип 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

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

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

Это исключение возникает при загрузке профилировщика в целевую среду выполнения, а еще одно присоединение выполняется.

Кері байланыс

Бет пайдалы болды ма?

Last updated on 2025-12-18

Бөлісу құралы:

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

Класс DiagnosticsClient

Конструктор

Методы StartEventPipeSession

Метод WriteDump

Методы ApplyStartupHook

Методы PerfMap

Метод AttachProfiler

Метод SetStartupProfiler

Метод ResumeRuntime

Метод SetEnvironmentVariable

GetProcessEnvironment

Метод GetPublishedProcesses

Класс EventPipeSessionConfiguration

Класс EventPipeProvider

Конструктор

Name, свойство

Свойство EventLevel

Свойство Keywords

Свойство Arguments

Замечания

Класс EventPipeSession

Свойство EventStream

Остановить методы

метод очистки Dispose

Класс DiagnosticsClientConnector

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

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

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

Исключения

UnsupportedCommandException

UnsupportedProtocolException

ServerNotAvailableException

ServerErrorException

ProfilerAlreadyActiveException

Кері байланыс

Қосымша ресурстар