Microsoft.Diagnostics.NETCore.Client API

  • Artikel

Bagian ini menjelaskan API pustaka klien diagnostik.

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

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

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

Menghentikan sesi yang diberikan EventPipe .

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.
  • 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.

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.