Microsoft.Diagnostics.NETCore.Client API

  • [アーティクル]

このセクションでは、診断クライアント ライブラリの 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 のプロセス ID で実行されている互換性のある .NET プロセス用に、DiagnosticsClient の新しいインスタンスを作成します。

processID: ターゲット アプリケーションのプロセス ID。

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 (非同期オーバーロードの場合): キャンセル要求を監視するためのトークン。

Note

ランダウン イベントには、スレッド サンプルのメソッド名の解決などの事後分析に必要なペイロードが含まれています。 これが必要ないことがわかっている場合を除き、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 プロセスのプロセス ID の 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 のキーワードのビットマスクを表す値を取得します。

Arguments プロパティ

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

指定した EventPipeProvider を表す EventSource に渡す省略可能な引数を表す、キーと値のペアの文字列の IDictionary を取得します。

解説

.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

これは、ランタイムが特定のコマンドにエラーで応答した場合に、スローされる可能性があります。