Microsoft.Diagnostics.NETCore.Client API

Tato část popisuje rozhraní API klientské knihovny diagnostiky.

DiagnosticsClient – třída

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

Vytvoří novou instanci DiagnosticsClient pro kompatibilní proces .NET spuštěný s ID processIdprocesu .

processID : ID procesu cílové aplikace.

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

Spustí trasovací relaci EventPipe pomocí daných zprostředkovatelů a nastavení.

• providers : A IEnumerable of EventPipeProviders začít trasování.
• requestRundown: Určuje bool , jestli se mají požadovat události zprostředkovatele rundownu z modulu runtime cílové aplikace.
• circularBufferMB: Určení int celkové velikosti cyklické vyrovnávací paměti používané modulem runtime cílové aplikace při shromažďování událostí.
• token (pro asynchronní přetížení): Token, který se má monitorovat pro žádosti o zrušení.

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 : Zahájení EventPipeProvider trasování.
• requestRundown: Určuje bool , jestli se mají požadovat události zprostředkovatele rundownu z modulu runtime cílové aplikace.
• circularBufferMB: Určení int celkové velikosti cyklické vyrovnávací paměti používané modulem runtime cílové aplikace při shromažďování událostí.
• token (pro asynchronní přetížení): Token, který se má monitorovat pro žádosti o zrušení.

Poznámka:

Události rundownu obsahují datové části, které mohou být potřeba pro následné analýzy, například překlad názvů metod ukázek vláken. Pokud nevíte, že to nechcete, doporučujeme nastavit requestRundown hodnotu true. Ve velkých aplikacích to může nějakou dobu trvat.

Metoda WriteDump

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

Požádejte o výpis paměti pro ladění cílové aplikace po mortem. Typ výpisu je možné zadat pomocí výčtu DumpType .

• dumpType : Typ výpisu paměti, který se má požadovat.
• dumpPath : Cesta k výpisu paměti, do které se má zapisovat.
• logDumpGeneration : Pokud je nastavená hodnota true, cílová aplikace během generování výpisu paměti zapíše diagnostické protokoly.

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

Požádejte o výpis paměti pro ladění cílové aplikace po mortem. Typ výpisu je možné zadat pomocí výčtu DumpType .

• dumpType : Typ výpisu paměti, který se má požadovat.
• dumpPath : Cesta k výpisu paměti, do které se má zapisovat.
• flags : příznaky protokolování a hlášení o chybách. V modulech runtime menší než 6.0 se podporuje pouze LoggingEnabled.

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

Požádejte o výpis paměti pro ladění cílové aplikace po mortem. Typ výpisu je možné zadat pomocí výčtu DumpType .

• dumpType : Typ výpisu paměti, který se má požadovat.
• dumpPath : Cesta k výpisu paměti, do které se má zapisovat.
• logDumpGeneration : Pokud je nastavená hodnota true, cílová aplikace během generování výpisu paměti zapíše diagnostické protokoly.
• token : Token pro monitorování žádostí o zrušení.

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

Požádejte o výpis paměti pro ladění cílové aplikace po mortem. Typ výpisu je možné zadat pomocí výčtu DumpType .

• dumpType : Typ výpisu paměti, který se má požadovat.
• dumpPath : Cesta k výpisu paměti, do které se má zapisovat.
• flags : příznaky protokolování a hlášení o chybách. V modulech runtime menší než 6.0 se podporuje pouze LoggingEnabled.
• token : Token pro monitorování žádostí o zrušení.

Metoda AttachProfiler

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

Žádost o připojení ICorProfileru k cílové aplikaci

• attachTimeout : Po TimeSpan kterém bude připojení přerušeno.
• profilerGuid : Guid ICorProfiler, který má být připojen.
• profilerPath : Cesta k knihovně DLL ICorProfiler, která se má připojit.
• additionalData : Volitelná další data, která lze předat modulu runtime během připojení profileru.

Metoda SetStartupProfiler

public void SetStartupProfiler(
        Guid profilerGuid,
        string profilerPath);

Nastavte profiler jako spouštěcí profiler. Tento příkaz je platný pouze v době, kdy je modul runtime pozastaven při spuštění.

• profilerGuid : Guid pro profiler, který se má připojit.
• profilerPath : Cesta k profileru, který se má připojit.

Metoda ResumeRuntime

public void ResumeRuntime();

Řekněte modulu runtime, aby po pozastavení při spuštění obnovil spouštění.

SetEnvironmentVariable – metoda

public void SetEnvironmentVariable(
    string name,
    string value);

Nastavte proměnnou prostředí v cílovém procesu.

• name : Název proměnné prostředí, která se má nastavit.
• value : Hodnota proměnné prostředí, která se má nastavit.

GetProcessEnvironment

public Dictionary<string, string> GetProcessEnvironment()

Získá všechny proměnné prostředí a jejich hodnoty z cílového procesu.

Metoda GetPublishedProcesses

public static IEnumerable<int> GetPublishedProcesses();

IEnumerable Získejte ID procesů všech aktivních procesů .NET, ke kterým je možné připojit.

EventPipeProvider – třída

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)

Vytvoří novou instanci EventPipeProvider s daným názvem zprostředkovatele, EventLevelklíčovými slovy a argumenty.

Name – vlastnost

public string Name { get; }

Získá název zprostředkovatele.

EventLevel – vlastnost

public EventLevel EventLevel { get; }

EventLevel Získá danou instanci EventPipeProvider.

Vlastnost Klíčová slova

public long Keywords { get; }

Získá hodnotu, která představuje bitová maska pro klíčová slova EventSource.

Argumenty – vlastnost

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

Získá dvojici IDictionary klíč-hodnota řetězce představující volitelné argumenty, které EventSource mají být předány představující dané EventPipeProvider.

Poznámky

Tato třída je neměnná, protože EventPipe neumožňuje úpravu konfigurace poskytovatele během relace EventPipe od .NET Core 3.1.

EventPipeSession – třída

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

Tato třída představuje probíhající relaci EventPipe. Je neměnný a funguje jako popisovač relace EventPipe daného modulu runtime.

EventStream – vlastnost

public Stream EventStream { get; }

Stream Získá, který lze použít ke čtení streamu událostí.

Metoda Stop

public void Stop();

Zastaví danou EventPipe relaci.

DumpType – výčet

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

Představuje typ výpisu paměti, který lze vyžádat.

• Normal: Zahrňte pouze informace potřebné k zachycení trasování zásobníku pro všechna existující trasování pro všechna existující vlákna v procesu. Omezená paměť haldy GC a informace.
• WithHeap: Zahrnuje haldy GC a informace potřebné k zachycení trasování zásobníku pro všechna existující vlákna v procesu.
• Triage: Zahrňte pouze informace potřebné k zachycení trasování zásobníku pro všechna existující trasování pro všechna existující vlákna v procesu. Omezená paměť haldy GC a informace. Nějaký obsah, o který se ví, že obsahuje potenciálně citlivé informace, jako jsou úplné cesty k modulům, budou upraveny. I když je to určeno ke zmírnění některých případů vystavení citlivých údajů, není zaručeno, že tato funkce redakce sama o sobě je dostatečná k dodržování jakýchkoli konkrétních zákonů nebo standardů týkajících se ochrany osobních údajů.
• Full: Do procesu zahrňte veškerou dostupnou paměť. Nezpracovaná data paměti jsou zahrnuta na konci, takže počáteční struktury lze mapovat přímo bez informací o nezpracované paměti. Výsledkem této možnosti může být velmi velký soubor s výpisem paměti.

Výjimky

Výjimky, které jsou vyvolány z knihovny, jsou typu DiagnosticsClientException nebo odvozeného typu.

public class DiagnosticsClientException : Exception

Nepodporovaná výjimkaCommandException

public class UnsupportedCommandException : DiagnosticsClientException

To může být vyvolán, pokud příkaz není podporován knihovnou nebo modulem runtime cílového procesu.

Nepodporovaná výjimkaProtocolException

public class UnsupportedProtocolException : DiagnosticsClientException

Může se to vyvolat, pokud modul runtime cílového procesu není kompatibilní s protokolem IPC diagnostiky používaným knihovnou.

ServerNotAvailableException

public class ServerNotAvailableException : DiagnosticsClientException

To může být vyvolána, pokud modul runtime není k dispozici pro diagnostické příkazy IPC, například v rané fázi spouštění modulu runtime před tím, než je modul runtime připravený pro diagnostické příkazy nebo když je modul runtime vypnutý.

Výjimka ServerErrorException

public class ServerErrorException : DiagnosticsClientException

Může se to vyvolat, když modul runtime odpoví chybou daného příkazu.