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
これは、ランタイムが特定のコマンドにエラーで応答した場合に、スローされる可能性があります。
.NET