Microsoft. Diagnostics.NETCore.Client API

Bu bölümde, tanılama istemci kitaplığının API'leri açıklanmaktadır.

DiagnosticsClient sınıfı

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

Oluşturucu

public DiagnosticsClient(int processId);

İşlem kimliğiyle DiagnosticsClientçalışan uyumlu bir .NET işlemi için yeni bir örneği processId oluşturur.

processID : Hedef uygulamanın işlem kimliği.

StartEventPipeSession yöntemleri

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

Verilen sağlayıcıları ve ayarları kullanarak bir EventPipe izleme oturumu başlatır.

• providers IEnumerable EventPipeProvider: İzlemeye başlamak için bir /s.
• requestRundown bool: Hedef uygulamanın çalışma zamanındaki rundown sağlayıcısı olaylarının istenip istenmeyeceğini belirten bir.
• circularBufferMB int: Hedef uygulamanın olay toplama çalışma zamanı tarafından kullanılan döngüsel arabelleğin toplam boyutunu belirten.
• token (zaman uyumsuz aşırı yükleme için): İptal isteklerini izlemek için belirteç.

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

Tek bir sağlayıcı kullanarak bir EventPipe izleme oturumu başlatır.

• provider: İzlemeyi başlatmak için.EventPipeProvider
• requestRundown bool: Hedef uygulamanın çalışma zamanındaki rundown sağlayıcısı olaylarının istenip istenmeyeceğini belirten bir.
• circularBufferMB int: Hedef uygulamanın olay toplama çalışma zamanı tarafından kullanılan döngüsel arabelleğin toplam boyutunu belirten.
• token (zaman uyumsuz aşırı yükleme için): İptal isteklerini izlemek için belirteç.

public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

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

kullanarak EventPipeSessionConfigurationbir EventPipe izleme oturumu başlatır.

• config / configuration EventPipeSessionConfiguration: Oturumu tanımlayan bir.
• token (zaman uyumsuz aşırı yükleme için): İptal isteklerini izlemek için belirteç.

Not

Rundown olayları, iş parçacığı örneklerinin yöntem adlarını çözümleme gibi analiz sonrası için gerekli olabilecek yükleri içerir. Bunu istemediğinizi bilmiyorsanız true olarak ayarlamanızı requestRundown öneririz. Büyük uygulamalarda bu işlem biraz zaman alabilir.

WriteDump yöntemi

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

Hedef uygulamanın son hata ayıklaması için döküm isteyin. Döküm türü sabit listesi kullanılarak DumpType belirtilebilir.

• dumpType : İstenecek döküm türü.
• dumpPath : Yazılacak döküm yolu.
• logDumpGeneration : olarak trueayarlanırsa, hedef uygulama döküm oluşturma sırasında tanılama günlüklerini yazar.

public void WriteDump(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags)

Hedef uygulamanın son hata ayıklaması için döküm isteyin. Döküm türü sabit listesi kullanılarak DumpType belirtilebilir.

• dumpType : İstenecek döküm türü.
• dumpPath : Yazılacak döküm yolu.
• flags : rapor bayraklarını günlüğe kaydetme ve kilitlenme. 6.0'dan küçük çalışma zamanlarında yalnızca LoggingEnabled desteklenir.

public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    bool logDumpGeneration,
    CancellationToken token)

Hedef uygulamanın son hata ayıklaması için döküm isteyin. Döküm türü sabit listesi kullanılarak DumpType belirtilebilir.

• dumpType : İstenecek döküm türü.
• dumpPath : Yazılacak döküm yolu.
• logDumpGeneration : olarak trueayarlanırsa, hedef uygulama döküm oluşturma sırasında tanılama günlüklerini yazar.
• token : İptal isteklerini izlemek için belirteç.

public Task WriteDumpAsync(
    DumpType dumpType,
    string dumpPath,
    WriteDumpFlags flags,
    CancellationToken token)

Hedef uygulamanın son hata ayıklaması için döküm isteyin. Döküm türü sabit listesi kullanılarak DumpType belirtilebilir.

• dumpType : İstenecek döküm türü.
• dumpPath : Yazılacak döküm yolu.
• flags : rapor bayraklarını günlüğe kaydetme ve kilitlenme. 6.0'dan küçük çalışma zamanlarında yalnızca LoggingEnabled desteklenir.
• token : İptal isteklerini izlemek için belirteç.

ApplyStartupHook yöntemleri

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Belirtilen derlemeyi hedef işlemde ile StartupHook yükler.

• startupHookPath : Başlangıç kancasını içeren derlemenin yolu.
• token (zaman uyumsuz aşırı yükleme için): İptal isteklerini izlemek için belirteç.

PerfMap yöntemleri

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Hedef işlemde performans eşlemelerinin oluşturulmasını denetler.

• type PerfMapType: Etkinleştirileceği performans eşlemesinin türünü belirtir.

AttachProfiler yöntemi

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

Hedef uygulamaya ICorProfiler ekleme isteği.

• attachTimeout : Bundan TimeSpan sonra ekleme durdurulacak.
• profilerGuid : Guid eklenecek ICorProfiler için.
• profilerPath : Eklenecek ICorProfiler dll'sinin yolu.
• additionalData : Profil oluşturucu ekleme sırasında çalışma zamanına geçirilebilen isteğe bağlı ek veriler.

SetStartupProfiler yöntemi

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Başlangıç profili oluşturucu olarak bir profil oluşturucu ayarlayın. Çalışma zamanı başlangıçta duraklatılırken bu komutu vermek yalnızca geçerlidir.

• profilerGuid : Guid profil oluşturucunun eklenmesi için.
• profilerPath : Eklenecek profil oluşturucunun yolu.

ResumeRuntime yöntemi

public void ResumeRuntime();

Çalışma zamanına başlangıçta duraklatıldıktan sonra yürütmeyi sürdürmesini söyleyin.

SetEnvironmentVariable yöntemi

public void SetEnvironmentVariable(
    string name,
    string value);

Hedef işlemde bir ortam değişkeni ayarlayın.

• name : Ayarlanacağı ortam değişkeninin adı.
• value : Ayarlanacağı ortam değişkeninin değeri.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Hedef işlemden tüm ortam değişkenlerini ve değerlerini alır.

GetPublishedProcesses yöntemi

public static IEnumerable<int> GetPublishedProcesses();

IEnumerable Eklenebilen tüm etkin .NET işlemlerinin işlem kimliklerini alın.

EventPipeSessionConfiguration sınıfı

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 EventPipeSessionConfiguration(
        IEnumerable<EventPipeProvider> providers,
        int circularBufferSizeMB,
        long rundownKeyword,
        bool requestStackwalk,
        EventPipeBufferingMode bufferingMode);

    public bool RequestRundown { get; }

    public int CircularBufferSizeInMB { get; }

    public bool RequestStackwalk { get; }

    public long RundownKeyword { get; }

    public EventPipeBufferingMode BufferingMode { get; }

    public IReadOnlyCollection<EventPipeProvider> Providers { get; }
}

bir EventPipeSessioniçin yapılandırmayı temsil eder.

• providers IEnumerable EventPipeProvider: Etkinleştirecek bir sn.
• circularBufferSizeMB : Olayları toplamak için çalışma zamanının arabelleğinin MB cinsinden boyutu.
• requestRundown : ise true, çalışma zamanından rundown olayları isteyin.
• requestStackwalk : ise true, yayılan her olay için bir yığın izlemesi kaydedin.
• rundownKeyword : Rundown olayları için kullanılan anahtar sözcük maskesi.
• bufferingMode EventPipeBufferingMode: Oturum için. Kayıpsız toplama isteğinde bulunmak için kullanın Block . Block Geçirme için .NET 11'den fazla hedef çalışma zamanı gerekir; eski bir çalışma zamanında oluşturur StartEventPipeSessionUnsupportedCommandException.

BufferingMode özelliği, oturum için arabelleğe alma modunu döndürür. varsayılan değeri, Dropçalışma zamanının kayıplı arabelleği tutar.

EventPipeProvider sınıfı

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

    public EventPipeProvider(
        string name,
        EventLevel eventLevel,
        long keywords,
        IDictionary<string, string> arguments,
        EventPipeProviderEventFilter eventFilter)

    public string Name { get; }

    public EventLevel EventLevel { get; }

    public long Keywords { get; }

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

    public EventPipeProviderEventFilter EventFilter { 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);
}

Oluşturucu

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

public EventPipeProvider(
    string name,
    EventLevel eventLevel,
    long keywords,
    IDictionary<string, string> arguments,
    EventPipeProviderEventFilter eventFilter)

Belirtilen sağlayıcı adı, EventPipeProvider, anahtar sözcükler ve bağımsız değişkenlerle yeni bir örneği EventLevel oluşturur. İkinci aşırı yükleme, çalışma zamanının sağlayıcı için etkinleştirdiği Olay Kimliklerini filtreleyen bir EventPipeProviderEventFilter de alır. Bir olay filtresi ayarladığınızda oturum için .NET 10'undan fazla hedef çalışma zamanı gerekir.

Name özelliği

public string Name { get; }

Sağlayıcının adını alır.

EventLevel özelliği

public EventLevel EventLevel { get; }

EventLevel Verilen örneğini EventPipeProvideralır.

Anahtar sözcükler özelliği

public long Keywords { get; }

anahtar sözcükleri EventSourceiçin bit maskesini temsil eden bir değer alır.

Arguments özelliği

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

Verilen öğesini temsil etmek için geçirilecek IDictionary isteğe bağlı bağımsız değişkenleri temsil eden anahtar-değer çifti dizelerinden birini EventSourceEventPipeProvideralır.

EventFilter özelliği

public EventPipeProviderEventFilter EventFilter { get; }

Çalışma zamanının anahtar sözcük ve düzey filtresinden sonra bu sağlayıcının Olay Kimlikleri için geçerli olduğu isteğe bağlı EventPipeProviderEventFilter değeri alır. değeri olduğunda null, çalışma zamanı anahtar sözcüğün ve düzey filtresinin izin verdiği her Olay Kimliğini etkinleştirir.

Açıklamalar

EventPipe, .NET Core 3.1 itibarıyla bir EventPipe oturumu sırasında sağlayıcı yapılandırmasının değiştirilmesine izin vermediğinden bu sınıf sabittir.

EventPipeProviderEventFilter sınıfı

public sealed class EventPipeProviderEventFilter
{
    public EventPipeProviderEventFilter(
        bool enable,
        IReadOnlyList<uint> eventIds);

    public bool Enable { get; }

    public IReadOnlyList<uint> EventIds { get; }
}

Olay Kimlikleri üzerinde isteğe bağlı bir sağlayıcı başına filtreyi temsil eder. Çalışma zamanı, ilişkili EventPipeProvideranahtar sözcüğünden ve düzey filtresinden sonra filtreyi uygular. Olay filtreleri için .NET 10'undan fazla hedef çalışma zamanı gerekir.

Oluşturucu

public EventPipeProviderEventFilter(
    bool enable,
    IReadOnlyList<uint> eventIds);

öğesinin yeni bir örneğini EventPipeProviderEventFilteroluşturur.

• enable : ise true, eventIds bir izin listesidir ve çalışma zamanı yalnızca bu Olay Kimliklerini etkinleştirir. eventIds isefalse, reddetme listesidir ve çalışma zamanı listelenenler dışında her Olay Kimliğini etkinleştirir. Bu nedenle boş bir reddetme listesi tüm olayları etkinleştirir.
• eventIds : tarafından enablebelirlenen, etkinleştirilen veya devre dışı bırakılan Olay Kimlikleri.

Özelliği etkinleştir

public bool Enable { get; }

İzin verme listesi () veya reddetme listesi (truefalse) olup olmadığını EventIds gösteren bir değer alır.

EventIds özelliği

public IReadOnlyList<uint> EventIds { get; }

Filtrenin etkinleştirdiğini veya devre dışı bırakdığını olay kimliklerinin listesini alır.

EventPipeSession sınıfı

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

    public void Stop();

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

Bu sınıf, devam eden bir EventPipe oturumlarını temsil eder. Sabittir ve verilen çalışma zamanının EventPipe oturumu için tanıtıcı işlevi görür.

EventStream özelliği

public Stream EventStream { get; }

Olay akışını okumak için kullanılabilecek bir Stream alır.

Durdurma yöntemleri

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

Verilen EventPipe oturumu durdurur.

• cancellationToken (zaman uyumsuz aşırı yükleme için): İptal isteklerini izlemek için belirteç.

Dispose yöntemi

public void Dispose();

ile EventPipeSessionilişkili kaynakları serbest bırakır.

DiagnosticsClientConnector sınıfı

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

    public ValueTask DisposeAsync();

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

Bir tanılama bağlantı noktasından bir DiagnosticsClient oluşturan ve temel alınan tanılama sunucusu bağlantısının ömrünü yöneten bir yardımcıyı temsil eder.

• Instance DiagnosticsClient: Hedef çalışma zamanına bağlı.
• DisposeAsync : Temel alınan sunucuyu/bağlantıyı zaman uyumsuz olarak atar.
• FromDiagnosticPort : Belirtilen tanılama bağlantı noktasından yeni DiagnosticsClientConnector bir oluşturur.

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

• diagnosticPort : Üzerinden bağlanacak tanılama bağlantı noktası dizesi (örneğin, dinleme veya bağlantı noktası).
• ct : İptal isteklerini izlemek için belirteç.

DumpType sabit listesi

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

İstenebilecek döküm türünü temsil eder.

• Normal: Yalnızca bir işlemdeki tüm mevcut iş parçacıkları için mevcut tüm izlemeler için yığın izlemelerini yakalamak için gerekli bilgileri ekleyin. Sınırlı GC yığını belleği ve bilgileri.
• WithHeap: Bir işlemdeki tüm mevcut iş parçacıkları için yığın izlemelerini yakalamak için gereken GC yığınlarını ve bilgileri içerir.
• Triage: Yalnızca bir işlemdeki tüm mevcut iş parçacıkları için mevcut tüm izlemeler için yığın izlemelerini yakalamak için gerekli bilgileri ekleyin. Sınırlı GC yığını belleği ve bilgileri. Tam modül yolları gibi hassas olabilecek bilgiler içerdiği bilinen bazı içerikler yeniden dağıtılır. Bu, bazı hassas verilerin açığa çıkarılma durumlarını azaltmaya yönelik olsa da, bu yeniden değiştirme özelliğinin veri gizliliğiyle ilgili herhangi bir yasaya veya standarda uymak için yeterli olduğunu garanti etmemektedir.
• Full: Tüm erişilebilir belleği sürece dahil edin. Ham bellek verileri sonuna eklenir, böylece ilk yapılar ham bellek bilgileri olmadan doğrudan eşlenebilir. Bu seçenek çok büyük bir döküm dosyasına neden olabilir.

WriteDumpFlags sabit listesi

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

Döküm istenirken belirtilebilen ek seçenekleri temsil eder.

• None : Ek davranış yoktur.
• LoggingEnabled : Döküm oluşturma sırasında temel günlüğü etkinleştirin.
• VerboseLoggingEnabled : Döküm oluşturma sırasında ayrıntılı günlüğe kaydetmeyi etkinleştirin.
• CrashReportEnabled : Kilitlenme raporunun oluşturulmasını etkinleştirin.

PerfMapType sabit listesi

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

Etkinleştirilebilen performans eşleme davranışının türünü temsil eder.

• None : Performans eşlemesi çıkışı yok.
• All : Çalışma zamanı tarafından desteklenen tüm performans eşlemesi çıkışlarını etkinleştirin.
• JitDump : JIT dökümü performans eşlemesi çıkışını etkinleştirin.
• PerfMap : Geleneksel performans haritası çıkışını etkinleştirin.

EventPipeBufferingMode sabit listesi

public enum EventPipeBufferingMode
{
    Drop = 0,
    Block = 1
}

Çalışma zamanının oturum başına olay arabelleği, oturumun boşalttığından daha hızlı doldurulduğunda nasıl davranacağını denetler.

• Drop : Çalışma zamanı varsayılanı. Oturum taştığında olayları düşüren bir arabellek kullandığından koleksiyon kayıplı olur.
• Block : Kayıpsız toplama. Olayları bırakmak yerine arabellek dolduğunda çalışma zamanı olay üreticilerini engeller. Büyük bir yığındaki yığın anlık görüntüsü gibi, tamamlanması gereken koleksiyonlar için kullanın. Block yalnızca arabelleğin kapasitesine kadar kayıpsız, ana bilgisayar belleği tükenmesine karşı değil: çalışma zamanı arabellek alanını ayırmak için gereken belleği ayıramıyorsa veya oturum kapatılırken engelleme yerine olayı bırakır. Block.NET 11+ hedef çalışma zamanı gerektirir; daha eski bir çalışma zamanında oturumu başlatırken oluştururUnsupportedCommandException.

Özel durumlar

Kitaplıktan atılan özel durumlar tür DiagnosticsClientException veya türetilmiş türdedir.

public class DiagnosticsClientException : Exception

DesteklenmeyenProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Hedef işlemin çalışma zamanı kitaplık tarafından kullanılan tanılama IPC protokolüyle uyumlu olmadığında bu durum oluşabilir.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Bu, çalışma zamanı tanılama komutları için hazır olmadan önce çalışma zamanı başlatma sırasında erken veya çalışma zamanı kapatılıyor gibi tanılama IPC komutları için kullanılabilir olmadığında oluşabilir.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Bu, çalışma zamanı belirli bir komuta bir hatayla yanıt verdiği zaman oluşabilir.

DesteklenmeyenCommandException

public class UnsupportedCommandException : ServerErrorException

Bu özel durum, komut kitaplık veya hedef işlemin çalışma zamanı tarafından desteklenmediğinde oluşturulur.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

Bu özel durum, bir profil oluşturucu hedef çalışma zamanına zaten yüklendiğinde ve başka bir ekleme denendiğinde oluşturulur.

BadEncodingException

public class BadEncodingException : ServerErrorException

Bu özel durum, hedef çalışma zamanı komut yükünün kodunu çözemediğinde oluşturulur ve yükü reddeder. İyi biçimlendirilmiş bir istemciden, genellikle çalışma zamanının daha yeni yapılandırılmış bir seçenek değerini anlamak için çok eski olduğu ve bu nedenle ayrıştırma sırasında isteği reddettiği anlamına gelir.