Bagikan melalui

Microsoft.Diagnostics.NETCore.Client API

Bagian ini menjelaskan API pustaka klien diagnostik.

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

Konstruktor

public DiagnosticsClient(int processId);

Membuat instans DiagnosticsClient baru untuk proses .NET yang kompatibel yang berjalan dengan ID proses .processId

processID : ID proses aplikasi target.

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

Memulai sesi pelacakan EventPipe menggunakan penyedia dan pengaturan tertentu.

  • providers : Dari IEnumerableEventPipeProviders untuk mulai melacak.
  • requestRundown: Menentukan bool apakah peristiwa penyedia rundown dari runtime aplikasi target harus diminta.
  • circularBufferMB: Menentukan int ukuran total buffer melingkar yang digunakan oleh runtime aplikasi target saat mengumpulkan peristiwa.
  • token (untuk kelebihan asinkron): Token yang akan dipantau untuk permintaan pembatalan.
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);

Memulai sesi pelacakan EventPipe menggunakan satu penyedia.

  • provider : Untuk EventPipeProvider memulai pelacakan.
  • requestRundown: Menentukan bool apakah peristiwa penyedia rundown dari runtime aplikasi target harus diminta.
  • circularBufferMB: Menentukan int ukuran total buffer melingkar yang digunakan oleh runtime aplikasi target saat mengumpulkan peristiwa.
  • token (untuk kelebihan asinkron): Token yang akan dipantau untuk permintaan pembatalan.
public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

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

Memulai sesi pelacakan EventPipe menggunakan EventPipeSessionConfiguration.

  • config / configuration : Yang EventPipeSessionConfiguration mendefinisikan sesi.
  • token (untuk kelebihan asinkron): Token yang akan dipantau untuk permintaan pembatalan.

Catatan

Peristiwa rundown berisi payload yang mungkin diperlukan untuk analisis pasca, seperti menyelesaikan nama metode sampel utas. Kecuali Anda tahu bahwa Anda tidak menginginkan ini, kami sarankan pengaturan requestRundown ke true. Dalam aplikasi besar, ini mungkin memakan waktu cukup lama.

Metode WriteDump

public void WriteDump(
    DumpType dumpType,
    string dumpPath,
    bool logDumpGeneration=false);

Minta cadangan untuk debugging pasca-mortem aplikasi target. Jenis cadangan dapat ditentukan menggunakan DumpType enum.

  • dumpType : Jenis cadangan yang akan diminta.
  • dumpPath : Jalur ke tempat pembuangan yang akan ditulis.
  • logDumpGeneration : Jika diatur ke true, aplikasi target akan menulis log diagnostik selama pembuatan cadangan.
public void WriteDump(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags)

Minta cadangan untuk debugging pasca-mortem aplikasi target. Jenis cadangan dapat ditentukan menggunakan DumpType enum.

  • dumpType : Jenis cadangan yang akan diminta.
  • dumpPath : Jalur ke tempat pembuangan yang akan ditulis.
  • flags : bendera laporan pengelogan dan crash. Pada runtime kurang dari 6.0, hanya LoggingEnabled yang didukung.
public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    bool logDumpGeneration,
    CancellationToken token)

Minta cadangan untuk debugging pasca-mortem aplikasi target. Jenis cadangan dapat ditentukan menggunakan DumpType enum.

  • dumpType : Jenis cadangan yang akan diminta.
  • dumpPath : Jalur ke tempat pembuangan yang akan ditulis.
  • logDumpGeneration : Jika diatur ke true, aplikasi target akan menulis log diagnostik selama pembuatan cadangan.
  • token : Token yang akan dipantau untuk permintaan pembatalan.
public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags,
    CancellationToken token)

Minta cadangan untuk debugging pasca-mortem aplikasi target. Jenis cadangan dapat ditentukan menggunakan DumpType enum.

  • dumpType : Jenis cadangan yang akan diminta.
  • dumpPath : Jalur ke tempat pembuangan yang akan ditulis.
  • flags : bendera laporan pengelogan dan crash. Pada runtime kurang dari 6.0, hanya LoggingEnabled yang didukung.
  • token : Token yang akan dipantau untuk permintaan pembatalan.

Metode ApplyStartupHook

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Memuat rakitan yang ditentukan dengan StartupHook dalam proses target.

  • startupHookPath : Jalur ke assembly yang berisi kait startup.
  • token (untuk kelebihan asinkron): Token yang akan dipantau untuk permintaan pembatalan.

Metode PerfMap

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Mengontrol pembuatan peta perf dalam proses target.

  • type : Menunjukkan PerfMapType jenis peta perf untuk diaktifkan.

Metode AttachProfiler

public void AttachProfiler(
    TimeSpan attachTimeout,
    Guid profilerGuid,
    string profilerPath,
    byte[] additionalData=null);

Minta untuk melampirkan ICorProfiler ke aplikasi target.

  • attachTimeout : A TimeSpan setelah itu lampiran akan dibatalkan.
  • profilerGuid : Guid dari ICorProfiler yang akan dilampirkan.
  • profilerPath : Jalur ke dll ICorProfiler yang akan dilampirkan.
  • additionalData : Data tambahan opsional yang dapat diteruskan ke runtime selama lampirkan profiler.

Metode SetStartupProfiler

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Atur profiler sebagai profiler startup. Hanya valid untuk mengeluarkan perintah ini saat runtime dijeda saat startup.

  • profilerGuid : Guid agar profiler dilampirkan.
  • profilerPath : Jalur ke profiler yang akan dilampirkan.

Metode ResumeRuntime

public void ResumeRuntime();

Beri tahu runtime untuk melanjutkan eksekusi setelah dijeda saat startup.

Metode SetEnvironmentVariable

public void SetEnvironmentVariable(
    string name,
    string value);

Atur variabel lingkungan dalam proses target.

  • name : Nama variabel lingkungan yang akan diatur.
  • value : Nilai variabel lingkungan yang akan diatur.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Mendapatkan semua variabel lingkungan dan nilainya dari proses target.

Metode GetPublishedProcesses

public static IEnumerable<int> GetPublishedProcesses();

IEnumerable Dapatkan ID proses dari semua proses .NET aktif yang dapat dilampirkan.

Kelas 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; }
}

Mewakili konfigurasi untuk EventPipeSession.

  • providers : Satu IEnumerable dari EventPipeProvideryang akan diaktifkan.
  • circularBufferSizeMB : Ukuran dalam MB buffer runtime untuk mengumpulkan peristiwa.
  • requestRundown : Jika true, minta peristiwa rundown dari runtime.
  • requestStackwalk : Jika true, rekam jejak tumpukan untuk setiap peristiwa yang dipancarkan.
  • rundownKeyword : Masker kata kunci yang digunakan untuk peristiwa rundown.

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

Konstruktor

public EventPipeProvider(
    string name,
    EventLevel eventLevel,
    long keywords = 0,
    IDictionary<string, string> arguments = null)

Membuat instans EventPipeProvider baru dengan nama penyedia, kata EventLevelkunci, dan argumen yang diberikan.

Properti nama

public string Name { get; }

Mendapatkan nama Penyedia.

Properti EventLevel

public EventLevel EventLevel { get; }

Mendapatkan instans EventLevel yang diberikan dari EventPipeProvider.

Properti kata kunci

public long Keywords { get; }

Mendapatkan nilai yang mewakili bitmask untuk kata kunci .EventSource

Properti argumen

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

IDictionary Mendapatkan string pasangan kunci-nilai yang mewakili argumen opsional yang akan diteruskan untuk EventSource mewakili EventPipeProvider.

Keterangan

Kelas ini tidak dapat diubah, karena EventPipe tidak mengizinkan konfigurasi penyedia dimodifikasi selama sesi EventPipe per .NET Core 3.1.

Kelas EventPipeSession

public class EventPipeSession : IDisposable
{
    public Stream EventStream { get; }

    public void Stop();

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

Kelas ini mewakili sesi EventPipe yang sedang berlangsung. Ini tidak dapat diubah dan bertindak sebagai handel ke sesi EventPipe dari runtime yang diberikan.

Properti EventStream

public Stream EventStream { get; }

Mendapatkan yang Stream dapat digunakan untuk membaca aliran peristiwa.

Hentikan metode

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

Menghentikan sesi yang diberikan EventPipe .

  • cancellationToken (untuk kelebihan asinkron): Token yang akan dipantau untuk permintaan pembatalan.

Metode pembuangan

public void Dispose();

Merilis sumber daya yang terkait dengan EventPipeSession.

Kelas DiagnosticsClientConnector

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

    public ValueTask DisposeAsync();

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

Mewakili pembantu yang membuat DiagnosticsClient dari port diagnostik dan mengelola masa pakai koneksi server diagnostik yang mendasarinya.

  • Instance : Terhubung DiagnosticsClient ke runtime target.
  • DisposeAsync : Membuang server/koneksi yang mendasar secara asinkron.
  • FromDiagnosticPort : Membuat baru DiagnosticsClientConnector dari port diagnostik yang ditentukan.
public static Task<DiagnosticsClientConnector> FromDiagnosticPort(
    string diagnosticPort,
    CancellationToken ct)
  • diagnosticPort : String port diagnostik (misalnya, port dengarkan atau sambungkan) untuk disambungkan.
  • ct : Token yang akan dipantau untuk permintaan pembatalan.

Enum DumpType

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

Mewakili jenis cadangan yang dapat diminta.

  • Normal: Sertakan hanya informasi yang diperlukan untuk menangkap jejak tumpukan untuk semua jejak yang ada untuk semua utas yang ada dalam proses. Memori dan informasi tumpukan GC terbatas.
  • WithHeap: Mencakup tumpukan GC dan informasi yang diperlukan untuk menangkap jejak tumpukan untuk semua utas yang ada dalam proses.
  • Triage: Sertakan hanya informasi yang diperlukan untuk menangkap jejak tumpukan untuk semua jejak yang ada untuk semua utas yang ada dalam proses. Memori dan informasi tumpukan GC terbatas. Beberapa konten yang diketahui berisi informasi yang berpotensi sensitif seperti jalur modul lengkap akan diredaksi. Meskipun ini dimaksudkan untuk mengurangi beberapa kasus paparan data sensitif, tidak ada jaminan fitur redaksi ini sendiri cukup untuk mematuhi hukum atau standar tertentu mengenai privasi data.
  • Full: Sertakan semua memori yang dapat diakses dalam proses. Data memori mentah disertakan di akhir, sehingga struktur awal dapat dipetakan secara langsung tanpa informasi memori mentah. Opsi ini dapat menghasilkan file cadangan yang sangat besar.

Enum WriteDumpFlags

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

Mewakili opsi tambahan yang dapat ditentukan saat meminta cadangan.

  • None : Tidak ada perilaku tambahan.
  • LoggingEnabled : Aktifkan pengelogan dasar selama pembuatan cadangan.
  • VerboseLoggingEnabled : Aktifkan pengelogan verbose selama pembuatan cadangan.
  • CrashReportEnabled : Aktifkan pembuatan laporan crash.

Enum PerfMapType

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

Mewakili jenis perilaku peta perf yang dapat diaktifkan.

  • None : Tidak ada output peta perf.
  • All : Aktifkan semua output peta perf yang didukung oleh runtime.
  • JitDump : Aktifkan output peta JIT dump perf.
  • PerfMap : Aktifkan output peta perf tradisional.

Pengecualian

Pengecualian yang dilemparkan dari pustaka berjenis DiagnosticsClientException atau jenis turunan.

public class DiagnosticsClientException : Exception

UnsupportedCommandException

public class UnsupportedCommandException : DiagnosticsClientException

Ini dapat dilemparkan ketika perintah tidak didukung oleh pustaka atau runtime proses target.

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Ini dapat dilemparkan ketika runtime proses target tidak kompatibel dengan protokol IPC diagnostik yang digunakan oleh pustaka.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Ini dapat dilemparkan ketika runtime tidak tersedia untuk perintah IPC diagnostik, seperti awal selama startup runtime sebelum runtime siap untuk perintah diagnostik, atau ketika runtime dimatikan.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Ini dapat dilemparkan ketika runtime merespons dengan kesalahan pada perintah tertentu.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

Pengecualian ini dilemparkan ketika profiler sudah dimuat ke dalam runtime target dan lampiran lain dicoba.

  • Last updated on