Microsoft.Diagnostics.NETCore.Client API

發行項
02/27/2024

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

針對相容且以處理序識別碼 processId 執行的 .NET 處理序建立 DiagnosticsClient 的新執行個體。

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：要開始追蹤之 EventPipeProvider 的 IEnumerable。
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)

provider：EventPipeProvider，以開始追蹤。
requestRundown：bool，指定是否應要求來自目標應用程式執行階段的取消提供者事件。
circularBufferMB：int，指定目標應用程式執行階段在收集事件時所使用之迴圈緩衝區的大小總計。
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 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：要附加之 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。

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)

使用指定的提供者名稱、EventLevel、關鍵字和引數來建立 EventPipeProvider 的新執行個體。

Name 屬性

public string Name { get; }

取得提供者的名稱。

EventLevel 屬性

public EventLevel EventLevel { get; }

取得 EventPipeProvider 之指定執行個體的 EventLevel。

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

這個類別代表進行中的 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：僅包含處理序中所有現有執行緒之所有現有追蹤為了擷取堆疊追蹤所需的資訊。有限 GC 堆積記憶體和資訊。
WithHeap：包含處理序中所有現有執行緒為了擷取堆疊追蹤所需的 GC 堆積和資訊。
Triage：僅包含處理序中所有現有執行緒之所有現有追蹤為了擷取堆疊追蹤所需的資訊。有限 GC 堆積記憶體和資訊。某些已知包含潛在敏感性資訊的內容，例如完整模組路徑，將會進行修訂。雖然這是為了減輕某些敏感數據暴露的情況，但不能保證這項修訂功能本身就足以遵守任何關於數據隱私權的特定法律或標準。
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

當執行階段對指定命令回應錯誤時，就可能擲回此項目。

共用方式為

Microsoft.Diagnostics.NETCore.Client API

DiagnosticsClient 類別

建構函式

StartEventPipeSession 方法

WriteDump 方法

AttachProfiler 方法

SetStartupProfiler 方法

ResumeRuntime 方法

SetEnvironmentVariable 方法

GetProcessEnvironment

GetPublishedProcesses 方法

EventPipeProvider 類別

建構函式

Name 屬性

EventLevel 屬性

Keywords 屬性

引數屬性

備註

EventPipeSession 類別

EventStream 屬性

Stop 方法

DumpType 列舉

例外狀況

UnsupportedCommandException

UnsupportedProtocolException

ServerNotAvailableException

ServerErrorException

其他資源