Dela via

Microsoft.Diagnostics.NETCore.Client API

  • Artikel

I det här avsnittet beskrivs API:erna för diagnostikklientbiblioteket.

DiagnosticsClient-klass

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

Skapar en ny instans av DiagnosticsClient för en kompatibel .NET-process som körs med process-ID processIdför .

processID : Process-ID för målprogrammet.

StartEventPipeSession-metoder

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

Startar en EventPipe-spårningssession med hjälp av de angivna leverantörerna och inställningarna.

  • providers : Ett IEnumerable av EventPipeProviders som ska börja spåras.
  • requestRundown: En bool som anger om körningsproviderhändelser från målappens körning ska begäras.
  • circularBufferMB: En int som anger den totala storleken på den cirkelbuffert som används av målappens körning vid insamling av händelser.
  • token (för Async-överlagringen): Token som ska övervakas för annulleringsbegäranden.
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 : En EventPipeProvider för att börja spåra.
  • requestRundown: En bool som anger om körningsproviderhändelser från målappens körning ska begäras.
  • circularBufferMB: En int som anger den totala storleken på den cirkelbuffert som används av målappens körning vid insamling av händelser.
  • token (för Async-överlagringen): Token som ska övervakas för annulleringsbegäranden.

Kommentar

Körningshändelser innehåller nyttolaster som kan behövas för efteranalys, till exempel matchning av metodnamn för trådexempel. Om du inte vet att du inte vill ha det här rekommenderar vi att du anger requestRundown sant. I stora program kan det ta en stund.

WriteDump-metod

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

Begär en dump för felsökning efter slakt av målprogrammet. Du kan ange typen av dump med hjälp av DumpType uppräkningen.

  • dumpType : Typ av dump som ska begäras.
  • dumpPath : Sökvägen till dumpen som ska skrivas ut till.
  • logDumpGeneration : Om det är inställt på truekommer målprogrammet att skriva ut diagnostikloggar under dumpgenereringen.
public void WriteDump(DumpType dumpType, string dumpPath, WriteDumpFlags flags)

Begär en dump för felsökning efter slakt av målprogrammet. Du kan ange typen av dump med hjälp av DumpType uppräkningen.

  • dumpType : Typ av dump som ska begäras.
  • dumpPath : Sökvägen till dumpen som ska skrivas ut till.
  • flags : loggnings- och kraschrapportflaggor. Vid körning som är mindre än 6,0 stöds endast LoggningAktivera.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, bool logDumpGeneration, CancellationToken token)

Begär en dump för felsökning efter slakt av målprogrammet. Du kan ange typen av dump med hjälp av DumpType uppräkningen.

  • dumpType : Typ av dump som ska begäras.
  • dumpPath : Sökvägen till dumpen som ska skrivas ut till.
  • logDumpGeneration : Om det är inställt på truekommer målprogrammet att skriva ut diagnostikloggar under dumpgenereringen.
  • token : Token som ska övervakas för annulleringsbegäranden.
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, WriteDumpFlags flags, CancellationToken token)

Begär en dump för felsökning efter slakt av målprogrammet. Du kan ange typen av dump med hjälp av DumpType uppräkningen.

  • dumpType : Typ av dump som ska begäras.
  • dumpPath : Sökvägen till dumpen som ska skrivas ut till.
  • flags : loggnings- och kraschrapportflaggor. Vid körning som är mindre än 6,0 stöds endast LoggningAktivera.
  • token : Token som ska övervakas för annulleringsbegäranden.

AttachProfiler-metod

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

Begäran om att bifoga en ICorProfiler till målprogrammet.

  • attachTimeout : Därefter TimeSpan avbryts anslutningen.
  • profilerGuid : Guid av ICorProfiler som ska bifogas.
  • profilerPath : Sökväg till den ICorProfiler dll som ska bifogas.
  • additionalData : Valfria ytterligare data som kan skickas till körningen under profileringsanslutningen.

SetStartupProfiler-metod

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Ange en profilerare som startprofilerare. Det är bara giltigt att utfärda det här kommandot medan körningen pausas vid start.

  • profilerGuid : Guid för profileraren ska bifogas.
  • profilerPath : Sökväg till profileraren som ska kopplas.

ResumeRuntime-metod

public void ResumeRuntime();

Be körningen att återuppta körningen efter att ha pausats vid start.

SetEnvironmentVariable-metod

public void SetEnvironmentVariable(
    string name,
    string value);

Ange en miljövariabel i målprocessen.

  • name : Namnet på miljövariabeln som ska anges.
  • value : Värdet för miljövariabeln som ska anges.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Hämtar alla miljövariabler och deras värden från målprocessen.

GetPublishedProcesses-metod

public static IEnumerable<int> GetPublishedProcesses();

Hämta ett IEnumerable process-ID för alla aktiva .NET-processer som kan kopplas till.

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

Skapar en ny instans av EventPipeProvider med det angivna providernamnet, EventLevelnyckelorden och argumenten.

Namnegenskap

public string Name { get; }

Hämtar namnet på providern.

EventLevel-egenskap

public EventLevel EventLevel { get; }

Hämtar den EventLevel angivna instansen av EventPipeProvider.

Nyckelordsegenskap

public long Keywords { get; }

Hämtar ett värde som representerar bitmask för nyckelord i EventSource.

Egenskapen Argument

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

Hämtar en IDictionary av nyckel/värde-parsträngar som representerar valfria argument som ska skickas till EventSource som representerar den angivna EventPipeProvider.

Kommentarer

Den här klassen är oföränderlig eftersom EventPipe inte tillåter att en providers konfiguration ändras under en EventPipe-session från och med .NET Core 3.1.

EventPipeSession-klass

public class EventPipeSession : IDisposable
{
    public Stream EventStream { get; }
    public void Stop();
}

Den här klassen representerar en pågående EventPipe-session. Det är oföränderligt och fungerar som ett handtag till en EventPipe-session för den angivna körningen.

Egenskapen EventStream

public Stream EventStream { get; }

Hämtar en Stream som kan användas för att läsa händelseströmmen.

Stoppmetod

public void Stop();

Stoppar den angivna EventPipe sessionen.

DumpType-uppräkning

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

Representerar den typ av dump som kan begäras.

  • Normal: Inkludera bara den information som krävs för att samla in stackspårningar för alla befintliga spårningar för alla befintliga trådar i en process. Begränsat GC-heapminne och information.
  • WithHeap: Innehåller de GC-heaps och information som krävs för att samla in stackspårningar för alla befintliga trådar i en process.
  • Triage: Inkludera bara den information som krävs för att samla in stackspårningar för alla befintliga spårningar för alla befintliga trådar i en process. Begränsat GC-heapminne och information. Visst innehåll som är känt för att innehålla potentiellt känslig information, till exempel fullständiga modulsökvägar, redigeras. Detta är avsett att minimera vissa fall av exponering av känsliga data, men det finns ingen garanti för att den här redigeringsfunktionen i sig är tillräcklig för att följa någon särskild lag eller standard när det gäller datasekretess.
  • Full: Inkludera allt tillgängligt minne i processen. Rådata för minne ingår i slutet, så att de inledande strukturerna kan mappas direkt utan rådata. Det här alternativet kan resultera i en mycket stor dumpfil.

Undantag

Undantag som genereras från biblioteket är av typen DiagnosticsClientException eller en härledd typ.

public class DiagnosticsClientException : Exception

CommandException stöds inte

public class UnsupportedCommandException : DiagnosticsClientException

Detta kan utlöses när kommandot inte stöds av antingen biblioteket eller målprocessens körning.

UnsupportedProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Detta kan genereras när målprocessens körning inte är kompatibel med diagnostik-IPC-protokollet som används av biblioteket.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

Detta kan uppstå när körningen inte är tillgänglig för IPC-diagnostikkommandon, till exempel tidigt under körningsstart innan körningen är klar för diagnostikkommandon eller när körningen stängs av.

ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Detta kan uppstå när körningen svarar med ett fel på ett visst kommando.