dotnet-diagnostics-core 0.24.0

dotnet-diagnostics-core

The transport-agnostic .NET diagnostics engine behind the dotnet-diagnostics-mcp MCP server and the dotnet-diagnostics-cli. It attaches to a live .NET process over the runtime diagnostic IPC socket and turns raw EventPipe / ClrMD / TraceEvent streams into structured results. Those normal paths require no target code changes or prior instrumentation. The explicit exception is MethodParameterCaptureUseCases: it performs a privileged dynamic attach of vendored dotnet-monitor profilers plus a startup hook and temporarily ReJIT-instruments an allowlist of methods; hosts must expose that sensitive capability only behind an explicit authorization policy.

This package exists so other hosts can call the same engine in-process, without shelling out to a tool. The first such consumer is the BenchmarkDotNet diagnoser (dotnet-diagnostics-benchmarkdotnet).

dotnet add package dotnet-diagnostics-core

Target framework: net10.0. Platform: the engine attaches over the diagnostic IPC socket; live ClrMD memory readers (heap/thread snapshots, method bytes, module bytes) additionally need CAP_SYS_PTRACE on Linux and the same UID as the target. Process dumps write through diagnostic IPC and do not require that kernel capability. See the repo docs for the deployment matrix.

Supported public surface (Pattern B — curated facade)

⚠️ Pre-1.0 / unstable. While this package is versioned 0.x it carries no SemVer API stability guarantee. Only the entry points listed below are intended for external use; every other public type is an implementation detail that will be internalized incrementally and may change or disappear without a major-version bump. Depend on the facade, not on the plumbing.

The supported entry points are the static use-case classes; each method returns a DiagnosticResult<T> envelope (success payload, DiagnosticError, and NextActionHints):

Supporting types that are part of the facade because the use-cases return or accept them:

• DiagnosticResult / DiagnosticResult<T>, DiagnosticError, NextActionHint — the result envelope.
• The per-collector snapshot/result records returned by the use-cases (e.g. CounterSnapshot, GcSummary, ContentionSnapshot, …).

Example

using DotnetDiagnostics.Core.UseCases;

// Snapshot EventCounters for ~5s from a target PID.
DiagnosticResult<CounterSnapshot> result =
    await EventCollectionUseCases.SnapshotCounters(processId: pid, durationSeconds: 5);

if (result.IsSuccess)
{
    foreach (var hint in result.Hints)
        Console.WriteLine(hint.Message);
}

Not in scope for this package

• The MCP tool surface, HTTP transport and bearer auth live in dotnet-diagnostics-mcp.
• The one-shot / REPL command line lives in dotnet-diagnostics-cli.

License

MIT — see the repository.