Microsoft.Diagnostics.NETCore.Client API

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

DiagnosticsClient – třída

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

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

Spustí trasovací relaci EventPipe pomocí jednoho zprostředkovatele.

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

public EventPipeSession StartEventPipeSession(
    EventPipeSessionConfiguration config);

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

Spustí relaci trasování EventPipe pomocí objektu EventPipeSessionConfiguration.

config / configuration : Definuje EventPipeSessionConfiguration relaci.
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 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 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í.

Metody ApplyStartupHook

public void ApplyStartupHook(
    string startupHookPath);

public Task ApplyStartupHookAsync(
    string startupHookPath,
    CancellationToken token);

Načte zadané sestavení s objektem v cílovém StartupHook procesu.

startupHookPath : Cesta k sestavení obsahující spouštěcí háku.
token (pro asynchronní přetížení): Token, který se má monitorovat pro žádosti o zrušení.

Metody PerfMap

public void EnablePerfMap(
    PerfMapType type);

public void DisablePerfMap();

Řídí generování map výkonu v cílovém procesu.

type : Označuje PerfMapType typ mapování výkonu, který se má povolit.

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.

EventPipeSessionConfiguration – třída

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

Představuje konfiguraci pro objekt .EventPipeSession

providers: PovoleníIEnumerable.EventPipeProvider
circularBufferSizeMB : Velikost v MB vyrovnávací paměti modulu runtime pro shromažďování událostí.
requestRundown : Pokud true, požadavek rundown události z modulu runtime.
requestStackwalk : Pokud true, zaznamená trasování zásobníku pro každou vygenerované události.
rundownKeyword : Maska klíčového slova používaná pro události rundownu.

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

    public Task StopAsync(
        CancellationToken cancellationToken);

    public void Dispose();
}

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

Metody zastavení

public void Stop();

public Task StopAsync(
    CancellationToken cancellationToken);

Zastaví danou EventPipe relaci.

cancellationToken (pro asynchronní přetížení): Token, který se má monitorovat pro žádosti o zrušení.

Dispose – metoda

public void Dispose();

Uvolní prostředky přidružené k nástroji EventPipeSession.

DiagnosticsClientConnector – třída

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

    public ValueTask DisposeAsync();

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

Představuje pomocníka, který vytvoří DiagnosticsClient z diagnostického portu a spravuje životnost základního připojení diagnostického serveru.

Instance : Připojeno DiagnosticsClient k cílovému modulu runtime.
DisposeAsync : Odstraní základní server nebo připojení asynchronně.
FromDiagnosticPort : Vytvoří nový DiagnosticsClientConnector ze zadaného diagnostického portu.

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

diagnosticPort : Řetězec portu diagnostiky (například naslouchací nebo připojovací port) pro připojení.
ct : Token pro monitorování žádostí o zrušení.

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.

WriteDumpFlags – výčet

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

Představuje další možnosti, které lze zadat při vyžádání výpisu paměti.

None : Žádné další chování.
LoggingEnabled : Během generování výpisu paměti povolte základní protokolování.
VerboseLoggingEnabled : Během generování výpisu paměti povolte podrobné protokolování.
CrashReportEnabled : Povolte generování zprávy o chybovém ukončení.

PerfMapType – výčet

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

Představuje typ chování mapování výkonu, které lze povolit.

None : Žádný výstup mapování výkonu.
All : Povolte všechny výstupy mapování výkonu podporované modulem runtime.
JitDump : Povolte výstup mapování výpisu stavu paměti JIT.
PerfMap : Povolte tradiční výstup mapování výkonu.

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.

ProfilerAlreadyActiveException

public class ProfilerAlreadyActiveException : ServerErrorException

Tato výjimka se vyvolá, když je profiler již načten do cílového modulu runtime a pokusí se o další připojení.

Váš názor

Byla tato stránka užitečná?

Last updated on 2025-12-18

Microsoft.Diagnostics.NETCore.Client API

DiagnosticsClient – třída

Konstruktor

Metody StartEventPipeSession

Metoda WriteDump

Metody ApplyStartupHook

Metody PerfMap

Metoda AttachProfiler

Metoda SetStartupProfiler

Metoda ResumeRuntime

SetEnvironmentVariable – metoda

GetProcessEnvironment

Metoda GetPublishedProcesses

EventPipeSessionConfiguration – třída

EventPipeProvider – třída

Konstruktor

Name – vlastnost

EventLevel – vlastnost

Vlastnost Klíčová slova

Argumenty – vlastnost

Poznámky

EventPipeSession – třída

EventStream – vlastnost

Metody zastavení

Dispose – metoda

DiagnosticsClientConnector – třída

DumpType – výčet

WriteDumpFlags – výčet

PerfMapType – výčet

Výjimky

Nepodporovaná výjimkaCommandException

Nepodporovaná výjimkaProtocolException

ServerNotAvailableException

Výjimka ServerErrorException

ProfilerAlreadyActiveException

Váš názor

Další materiály