Skip to content

Commit d037577

Browse files
mdh1418mdh1418
authored
[DiagnosticsClient] Update APIs (#50376)
1 parent 143639c commit d037577

File tree

1 file changed

+250
-12
lines changed

1 file changed

+250
-12
lines changed

‎docs/core/diagnostics/microsoft-diagnostics-netcore-client.md‎

Lines changed: 250 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,7 @@
11
---
22
title: Microsoft.Diagnostics.NETCore.Client API
33
description: In this article, you'll learn about the Microsoft.Diagnostics.NETCore.Client APIs.
4-
ms.date: 06/22/2021
4+
ms.date: 12/08/2025
55
author: tommcdon
66
ms.author: tommcdon
77
ms.topic: reference
@@ -14,7 +14,7 @@ This section describes the APIs of the diagnostics client library.
1414
## DiagnosticsClient class
1515

1616
```cs
17-
public DiagnosticsClient
17+
public sealed class DiagnosticsClient
1818
{
1919
public DiagnosticsClient(int processId);
2020

@@ -23,23 +23,52 @@ public DiagnosticsClient
2323
bool requestRundown = true,
2424
int circularBufferMB = 256);
2525

26+
public EventPipeSession StartEventPipeSession(
27+
EventPipeProvider provider,
28+
bool requestRundown = true,
29+
int circularBufferMB = 256);
30+
31+
public EventPipeSession StartEventPipeSession(
32+
EventPipeSessionConfiguration config);
33+
2634
public Task<EventPipeSession> StartEventPipeSessionAsync(
2735
IEnumerable<EventPipeProvider> providers,
2836
bool requestRundown,
2937
int circularBufferMB = 256,
3038
CancellationToken token = default);
3139

40+
public Task<EventPipeSession> StartEventPipeSessionAsync(
41+
EventPipeProvider provider,
42+
bool requestRundown,
43+
int circularBufferMB = 256,
44+
CancellationToken token = default);
45+
46+
public Task<EventPipeSession> StartEventPipeSessionAsync(
47+
EventPipeSessionConfiguration configuration,
48+
CancellationToken token);
49+
3250
public void WriteDump(
3351
DumpType dumpType,
3452
string dumpPath,
3553
bool logDumpGeneration = false);
3654

37-
public async Task WriteDumpAsync(
55+
public void WriteDump(
56+
DumpType dumpType,
57+
string dumpPath,
58+
WriteDumpFlags flags);
59+
60+
public Task WriteDumpAsync(
3861
DumpType dumpType,
3962
string dumpPath,
4063
bool logDumpGeneration,
4164
CancellationToken token);
4265

66+
public Task WriteDumpAsync(
67+
DumpType dumpType,
68+
string dumpPath,
69+
WriteDumpFlags flags,
70+
CancellationToken token);
71+
4372
public void AttachProfiler(
4473
TimeSpan attachTimeout,
4574
Guid profilerGuid,
@@ -58,6 +87,18 @@ public DiagnosticsClient
5887

5988
public Dictionary<string, string> GetProcessEnvironment();
6089

90+
public void ApplyStartupHook(
91+
string startupHookPath);
92+
93+
public Task ApplyStartupHookAsync(
94+
string startupHookPath,
95+
CancellationToken token);
96+
97+
public void EnablePerfMap(
98+
PerfMapType type);
99+
100+
public void DisablePerfMap();
101+
61102
public static IEnumerable<int> GetPublishedProcesses();
62103
}
63104
```
@@ -79,6 +120,7 @@ public EventPipeSession StartEventPipeSession(
79120
IEnumerable<EventPipeProvider> providers,
80121
bool requestRundown = true,
81122
int circularBufferMB = 256);
123+
82124
public Task<EventPipeSession> StartEventPipeSessionAsync(
83125
IEnumerable<EventPipeProvider> providers,
84126
bool requestRundown,
@@ -91,17 +133,41 @@ Starts an EventPipe tracing session using the given providers and settings.
91133
* `providers` : An `IEnumerable` of [`EventPipeProvider`](#eventpipeprovider-class)s to start tracing.
92134
* `requestRundown`: A `bool` specifying whether rundown provider events from the target app's runtime should be requested.
93135
* `circularBufferMB`: An `int` specifying the total size of circular buffer used by the target app's runtime on collecting events.
94-
* `token` (for the Async overload): The token to monitor for cancellation requests.
136+
* `token` (for the async overload): The token to monitor for cancellation requests.
95137

96138
```csharp
97-
public EventPipeSession StartEventPipeSession(EventPipeProvider provider, bool requestRundown = true, int circularBufferMB = 256)
98-
public Task<EventPipeSession> StartEventPipeSessionAsync(EventPipeProvider provider, bool requestRundown, int circularBufferMB = 256, CancellationToken token = default)
139+
public EventPipeSession StartEventPipeSession(
140+
EventPipeProvider provider,
141+
bool requestRundown = true,
142+
int circularBufferMB = 256);
143+
144+
public Task<EventPipeSession> StartEventPipeSessionAsync(
145+
EventPipeProvider provider,
146+
bool requestRundown,
147+
int circularBufferMB = 256,
148+
CancellationToken token = default);
99149
```
100150

151+
Starts an EventPipe tracing session using a single provider.
152+
101153
* `provider` : An [`EventPipeProvider`](#eventpipeprovider-class) to start tracing.
102154
* `requestRundown`: A `bool` specifying whether rundown provider events from the target app's runtime should be requested.
103155
* `circularBufferMB`: An `int` specifying the total size of circular buffer used by the target app's runtime on collecting events.
104-
* `token` (for the Async overload): The token to monitor for cancellation requests.
156+
* `token` (for the async overload): The token to monitor for cancellation requests.
157+
158+
```csharp
159+
public EventPipeSession StartEventPipeSession(
160+
EventPipeSessionConfiguration config);
161+
162+
public Task<EventPipeSession> StartEventPipeSessionAsync(
163+
EventPipeSessionConfiguration configuration,
164+
CancellationToken token);
165+
```
166+
167+
Starts an EventPipe tracing session using an [`EventPipeSessionConfiguration`](#eventpipesessionconfiguration-class).
168+
169+
* `config` / `configuration` : An `EventPipeSessionConfiguration` that defines the session.
170+
* `token` (for the async overload): The token to monitor for cancellation requests.
105171

106172
> [!NOTE]
107173
> Rundown events contain payloads that may be needed for post analysis, such as resolving method names of thread samples. Unless you know you do not want this, we recommend setting `requestRundown` to true. In large applications, this may take a while.
@@ -122,7 +188,10 @@ Request a dump for post-mortem debugging of the target application. The type of
122188
* `logDumpGeneration` : If set to `true`, the target application will write out diagnostic logs during dump generation.
123189

124190
```csharp
125-
public void WriteDump(DumpType dumpType, string dumpPath, WriteDumpFlags flags)
191+
public void WriteDump(
192+
DumpType dumpType,
193+
string dumpPath,
194+
WriteDumpFlags flags)
126195
```
127196

128197
Request a dump for post-mortem debugging of the target application. The type of the dump can be specified using the [`DumpType`](#dumptype-enum) enum.
@@ -132,7 +201,11 @@ Request a dump for post-mortem debugging of the target application. The type of
132201
* `flags` : logging and crash report flags. On runtimes less than 6.0, only LoggingEnabled is supported.
133202

134203
```csharp
135-
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, bool logDumpGeneration, CancellationToken token)
204+
public Task WriteDumpAsync(
205+
DumpType dumpType,
206+
string dumpPath,
207+
bool logDumpGeneration,
208+
CancellationToken token)
136209
```
137210

138211
Request a dump for post-mortem debugging of the target application. The type of the dump can be specified using the [`DumpType`](#dumptype-enum) enum.
@@ -143,7 +216,11 @@ Request a dump for post-mortem debugging of the target application. The type of
143216
* `token` : The token to monitor for cancellation requests.
144217

145218
```csharp
146-
public async Task WriteDumpAsync(DumpType dumpType, string dumpPath, WriteDumpFlags flags, CancellationToken token)
219+
public Task WriteDumpAsync(
220+
DumpType dumpType,
221+
string dumpPath,
222+
WriteDumpFlags flags,
223+
CancellationToken token)
147224
```
148225

149226
Request a dump for post-mortem debugging of the target application. The type of the dump can be specified using the [`DumpType`](#dumptype-enum) enum.
@@ -153,6 +230,35 @@ Request a dump for post-mortem debugging of the target application. The type of
153230
* `flags` : logging and crash report flags. On runtimes less than 6.0, only LoggingEnabled is supported.
154231
* `token` : The token to monitor for cancellation requests.
155232

233+
### ApplyStartupHook methods
234+
235+
```csharp
236+
public void ApplyStartupHook(
237+
string startupHookPath);
238+
239+
public Task ApplyStartupHookAsync(
240+
string startupHookPath,
241+
CancellationToken token);
242+
```
243+
244+
Loads the specified assembly with a `StartupHook` in the target process.
245+
246+
* `startupHookPath` : The path to the assembly containing the startup hook.
247+
* `token` (for the async overload): The token to monitor for cancellation requests.
248+
249+
### PerfMap methods
250+
251+
```csharp
252+
public void EnablePerfMap(
253+
PerfMapType type);
254+
255+
public void DisablePerfMap();
256+
```
257+
258+
Controls generation of perf maps in the target process.
259+
260+
* `type` : The [`PerfMapType`](#perfmaptype-enum) indicating the type of perf map to enable.
261+
156262
### AttachProfiler method
157263

158264
```csharp
@@ -220,6 +326,43 @@ public static IEnumerable<int> GetPublishedProcesses();
220326

221327
Get an `IEnumerable` of process IDs of all the active .NET processes that can be attached to.
222328

329+
## EventPipeSessionConfiguration class
330+
331+
```csharp
332+
public sealed class EventPipeSessionConfiguration
333+
{
334+
public EventPipeSessionConfiguration(
335+
IEnumerable<EventPipeProvider> providers,
336+
int circularBufferSizeMB = 256,
337+
bool requestRundown = true,
338+
bool requestStackwalk = true);
339+
340+
public EventPipeSessionConfiguration(
341+
IEnumerable<EventPipeProvider> providers,
342+
int circularBufferSizeMB,
343+
long rundownKeyword,
344+
bool requestStackwalk = true);
345+
346+
public bool RequestRundown { get; }
347+
348+
public int CircularBufferSizeInMB { get; }
349+
350+
public bool RequestStackwalk { get; }
351+
352+
public long RundownKeyword { get; }
353+
354+
public IReadOnlyCollection<EventPipeProvider> Providers { get; }
355+
}
356+
```
357+
358+
Represents the configuration for an `EventPipeSession`.
359+
360+
* `providers` : An `IEnumerable` of [`EventPipeProvider`](#eventpipeprovider-class)s to enable.
361+
* `circularBufferSizeMB` : The size in MB of the runtime's buffer for collecting events.
362+
* `requestRundown` : If `true`, request rundown events from the runtime.
363+
* `requestStackwalk` : If `true`, record a stack trace for every emitted event.
364+
* `rundownKeyword` : The keyword mask used for rundown events.
365+
223366
## EventPipeProvider class
224367

225368
```cs
@@ -305,28 +448,77 @@ This class is immutable, because EventPipe does not allow a provider's configura
305448
public class EventPipeSession : IDisposable
306449
{
307450
public Stream EventStream { get; }
451+
308452
public void Stop();
453+
454+
public Task StopAsync(
455+
CancellationToken cancellationToken);
456+
457+
public void Dispose();
309458
}
310459
```
311460

312461
This class represents an ongoing EventPipe session. It is immutable and acts as a handle to an EventPipe session of the given runtime.
313462

314-
## EventStream property
463+
### EventStream property
315464

316465
```csharp
317466
public Stream EventStream { get; }
318467
```
319468

320469
Gets a `Stream` that can be used to read the event stream.
321470

322-
## Stop method
471+
### Stop methods
323472

324473
```csharp
325474
public void Stop();
475+
476+
public Task StopAsync(
477+
CancellationToken cancellationToken);
326478
```
327479

328480
Stops the given `EventPipe` session.
329481

482+
* `cancellationToken` (for the async overload): The token to monitor for cancellation requests.
483+
484+
### Dispose method
485+
486+
```csharp
487+
public void Dispose();
488+
```
489+
490+
Releases resources associated with the `EventPipeSession`.
491+
492+
## DiagnosticsClientConnector class
493+
494+
```csharp
495+
public sealed class DiagnosticsClientConnector : IAsyncDisposable
496+
{
497+
public DiagnosticsClient Instance { get; }
498+
499+
public ValueTask DisposeAsync();
500+
501+
public static Task<DiagnosticsClientConnector> FromDiagnosticPort(
502+
string diagnosticPort,
503+
CancellationToken ct);
504+
}
505+
```
506+
507+
Represents a helper that creates a `DiagnosticsClient` from a diagnostic port and manages the lifetime of the underlying diagnostics server connection.
508+
509+
* `Instance` : The `DiagnosticsClient` connected to the target runtime.
510+
* `DisposeAsync` : Disposes the underlying server/connection asynchronously.
511+
* `FromDiagnosticPort` : Creates a new `DiagnosticsClientConnector` from the specified diagnostic port.
512+
513+
```csharp
514+
public static Task<DiagnosticsClientConnector> FromDiagnosticPort(
515+
string diagnosticPort,
516+
CancellationToken ct)
517+
```
518+
519+
* `diagnosticPort` : The diagnostic port string (for example, a listen or connect port) to connect through.
520+
* `ct` : The token to monitor for cancellation requests.
521+
330522
## DumpType enum
331523

332524
```csharp
@@ -346,6 +538,44 @@ Represents the type of dump that can be requested.
346538
* `Triage`: Include just the information necessary to capture stack traces for all existing traces for all existing threads in a process. Limited GC heap memory and information. Some content that is known to contain potentially sensitive information such as full module paths will be redacted. While this is intended to mitigate some cases of sensitive data exposure, there is no guarantee this redaction feature on its own is sufficient to comply with any particular law or standard regarding data privacy.
347539
* `Full`: Include all accessible memory in the process. The raw memory data is included at the end, so that the initial structures can be mapped directly without the raw memory information. This option can result in a very large dump file.
348540

541+
## WriteDumpFlags enum
542+
543+
```csharp
544+
public enum WriteDumpFlags
545+
{
546+
None = 0x00,
547+
LoggingEnabled = 0x01,
548+
VerboseLoggingEnabled = 0x02,
549+
CrashReportEnabled = 0x04
550+
}
551+
```
552+
553+
Represents additional options that can be specified when requesting a dump.
554+
555+
* `None` : No additional behavior.
556+
* `LoggingEnabled` : Enable basic logging during dump generation.
557+
* `VerboseLoggingEnabled` : Enable verbose logging during dump generation.
558+
* `CrashReportEnabled` : Enable generation of a crash report.
559+
560+
## PerfMapType enum
561+
562+
```csharp
563+
public enum PerfMapType
564+
{
565+
None = 0,
566+
All = 1,
567+
JitDump = 2,
568+
PerfMap = 3
569+
}
570+
```
571+
572+
Represents the type of perf map behavior that can be enabled.
573+
574+
* `None` : No perf map output.
575+
* `All` : Enable all perf map outputs supported by the runtime.
576+
* `JitDump` : Enable JIT dump perf map output.
577+
* `PerfMap` : Enable traditional perf map output.
578+
349579
## Exceptions
350580

351581
Exceptions that are thrown from the library are of type `DiagnosticsClientException` or a derived type.
@@ -385,3 +615,11 @@ public class ServerErrorException : DiagnosticsClientException
385615
```
386616

387617
This may be thrown when the runtime responds with an error to a given command.
618+
619+
### ProfilerAlreadyActiveException
620+
621+
```csharp
622+
public class ProfilerAlreadyActiveException : ServerErrorException
623+
```
624+
625+
This exception is thrown when a profiler is already loaded into the target runtime and another attach is attempted.

0 commit comments

Comments
 (0)