Microsoft.Diagnostics.NETCore.Client API

本節說明診斷用戶端程式庫的 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);

使用 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 列舉來指定傾印的類型。

dumpType：要要求的傾印類型。
dumpPath：要寫入之傾印的路徑。
flags：記錄和損毀報告旗標。在低於 6.0 的執行階段上，僅支援 LoggingEnabled。

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

要求傾印以進行目標應用程式的事後偵錯。您可以使用 DumpType 列舉來指定傾印的類型。

dumpType：要要求的傾印類型。
dumpPath：要寫入之傾印的路徑。
logDumpGeneration：若設為 true，則目標應用程式將在傾印產生期間寫出診斷記錄。
token：用來監視是否有取消要求的語彙基元。

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

要求傾印以進行目標應用程式的事後偵錯。您可以使用 DumpType 列舉來指定傾印的類型。

dumpType：要要求的傾印類型。
dumpPath：要寫入之傾印的路徑。
flags：記錄和損毀報告旗標。在低於 6.0 的執行階段上，僅支援 LoggingEnabled。
token：用來監視是否有取消要求的語彙基元。

ApplyStartupHook 方法

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

將指定組件載入目標製程中的 a 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：要附加之 ICorProfiler 的 Guid。
profilerPath：要附加之 ICorProfiler dll 的路徑。
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();

取得所有可附加之使用中 .NET 處理序的處理序識別碼 IEnumerable。

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 ： An IEnumerable of EventPipeProviders 以實現。
circularBufferSizeMB ：執行時用來收集事件的緩衝區大小（MB）。
requestRundown ：如果 true，請求執行時的 rundown 事件。
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 之關鍵字的位元遮罩。

引數屬性

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

取得 IDictionary 索引鍵/值組自串代表要傳遞至 EventSource (代表指定的 EventPipeProvider) 的選擇性引數。

備註

此類別不可變，因為自 .NET Core 3.1 起，EventPipe 不允許在 EventPipe 工作階段修改提供者的設定。

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 class

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：僅包含處理序中所有現有執行緒之所有現有追蹤為了擷取堆疊追蹤所需的資訊。有限 GC 堆積記憶體和資訊。
WithHeap：包含處理序中所有現有執行緒為了擷取堆疊追蹤所需的 GC 堆積和資訊。
Triage：僅包含處理序中所有現有執行緒之所有現有追蹤為了擷取堆疊追蹤所需的資訊。有限 GC 堆積記憶體和資訊。某些已知包含潛在敏感性資訊的內容，例如完整模組路徑，將會進行修訂。雖然這是為了減輕某些敏感數據暴露的情況，但不能保證這項修訂功能本身就足以遵守任何關於數據隱私權的特定法律或標準。
Full：包含處理序中所有可存取的記憶體。原始記憶體資料會包含在結尾，所以不需要原始記憶體資訊就能直接對應初始結構。這個選項可能會產生非常大的傾印檔案。

WriteDumpFlags 列舉

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

代表在請求傾倒時可指定的額外選項。

None ：沒有其他行為。
LoggingEnabled ：在dump產生時啟用基本日誌。
VerboseLoggingEnabled ：在dump產生時啟用冗長記錄。
CrashReportEnabled ：啟用產生事故報告。

PerfMapType enum

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

代表可以啟用的 perf map 行為類型。

None ：無孔位圖輸出。
All ：啟用執行時支援的所有 perf map 輸出。
JitDump ：啟用 JIT 傾出 perf map 輸出。
PerfMap ：啟用傳統的 perf map 輸出。

例外狀況

從程式庫擲回的例外狀況屬於 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

共用方式為

Microsoft.Diagnostics.NETCore.Client API

DiagnosticsClient 類別

建構函式

StartEventPipeSession 方法

WriteDump 方法

ApplyStartupHook 方法

PerfMap 方法

AttachProfiler 方法

SetStartupProfiler 方法

ResumeRuntime 方法

SetEnvironmentVariable 方法

GetProcessEnvironment

GetPublishedProcesses 方法

EventPipeSessionConfiguration 類別

EventPipeProvider 類別

建構函式

Name 屬性

EventLevel 屬性

Keywords 屬性

引數屬性

備註

EventPipeSession 類別

EventStream 屬性

停止方法

Dispose 方法

DiagnosticsClientConnector class

DumpType 列舉

WriteDumpFlags 列舉

PerfMapType enum

例外狀況

UnsupportedCommandException

UnsupportedProtocolException

ServerNotAvailableException

ServerErrorException

ProfilerAlreadyActiveException

意見反應

其他資源