Dotnet Debugging

dotnet-debugging

Overview

Windows and Linux/macOS debugging using WinDbg MCP tools (Windows), dotnet-dump, and lldb with SOS (Linux/macOS). Applicable to any application -- native, managed (.NET/CLR), or mixed-mode. Includes container diagnostic patterns for Docker and Kubernetes. Guides investigation of crash dumps, application hangs, high CPU, and memory pressure through structured command packs and report templates.

Platforms: Windows (WinDbg MCP, cdb), Linux/macOS (dotnet-dump, lldb with SOS, createdump, dotnet-monitor).

Routing Table

Scope

• Crash dump analysis (.dmp files) on Windows, Linux, and macOS
• Live process attach (cdb on Windows, lldb on Linux/macOS)
• Hang and deadlock diagnosis (thread analysis, lock detection, wait chains)
• High CPU triage (runaway thread identification)
• Memory pressure and leak investigation (managed heap, native heap)
• Kernel dump triage (BSOD / bugcheck analysis, Windows)
• Container diagnostics (dotnet-dump in Docker/Kubernetes, sidecar patterns)
• Production diagnostics (dotnet-monitor REST API, trigger-based collection)
• SOS commands across all platforms (WinDbg, dotnet-dump, lldb)
• Structured diagnostic reports with stack evidence

Boundary with dotnet-tooling

Both skills use overlapping tools (dotnet-dump, dotnet-counters, dotnet-trace) but for different purposes:

Rule of thumb: if something is broken (crash, hang, deadlock, OOM), route here. If something is slow or needs optimization, route to dotnet-tooling.

Out of scope

• Performance profiling (dotnet-counters, dotnet-trace for optimization) -> dotnet-tooling
• GC tuning and managed memory optimization -> dotnet-tooling
• Assembly decompilation (ILSpy) -> dotnet-tooling
• Performance benchmarking and regression detection -> dotnet-testing
• Application-level logging and observability -> dotnet-devops
• Unit/integration test debugging -> dotnet-testing

MCP Tool Contract

These tool IDs are the WinDbg MCP server's exported names (single-underscore mcp_...), not the mcp__... dispatch prefix used by some hosts.

Diagnostic Workflow

Preflight: Symbols

Before any analysis, configure symbols to get meaningful stacks:

1. Set Microsoft symbol server: .symfix (sets srv* to Microsoft public symbols)
2. Add application symbols: .sympath+ C:\path\to\your\pdbs
3. Reload modules: .reload /f
4. Verify: lm (list modules -- check for "deferred" vs "loaded" status)

Without correct symbols, stacks show raw addresses instead of function names.

Crash Dump Analysis

1. Open dump: mcp_mcp-windbg_open_windbg_dump with dump file path
2. Load SOS for managed code: .loadby sos clr (Framework) or .loadby sos coreclr (.NET Core)
3. Get exception context: !pe (print exception), !analyze -v (automatic analysis)
4. Inspect threads: ~*e !clrstack (all managed stacks), !threads (thread list)
5. Check managed heap: !dumpheap -stat (heap summary), !gcroot <addr> (object roots)

Hang / Deadlock Diagnosis

1. Attach or open dump, load SOS
2. List all threads: !threads, identify waiting threads with !syncblk (sync block table)
3. Detect deadlocks: !dlk (SOS deadlock detection)
4. Inspect thread stacks: ~Ns !clrstack for specific thread N
5. Check wait reasons: !waitchain for COM/RPC chains, !mda for MDA diagnostics

High CPU Triage

1. Attach to live process or collect multiple dumps 10-30 seconds apart
2. Use !runaway to identify threads consuming the most CPU time
3. Inspect hot thread stacks: ~Ns kb (native stack), ~Ns !clrstack (managed stack)
4. Look for tight loops, blocked finalizer threads, or excessive GC

Memory Pressure Investigation

1. Open dump, load SOS
2. Managed heap: !dumpheap -stat (type statistics), !dumpheap -type <TypeName> (filter)
3. Find leaked objects: !gcroot <address> (trace GC roots to pinned or static references)
4. Native heap: !heap -s (heap summary), !heap -l (leak detection)
5. LOH fragmentation: !eeheap -gc (GC heap segments)

Report Template

Copy code
## Diagnostic Report

**Symptom:** [crash/hang/high-cpu/memory-leak]
**Process:** [name, PID, bitness]
**Dump type:** [full/mini/live-attach]

### Evidence
- Exception: [type and message, or N/A]
- Faulting thread: [ID, managed/native, stack summary]
- Key stacks: [condensed callstack with module!function]

### Root Cause
[Concise analysis backed by stack/heap evidence]

### Recommendations
[Numbered action items]

Guardrails

• Do not claim certainty without callee-side evidence
• Do not call it a deadlock unless lock/wait evidence supports it
• Preserve user privacy: do not include secrets from environment blocks in reports

Cross-references: dotnet-tooling for .NET SDK diagnostic tools (references/profiling.md) and GC/memory tuning (references/gc-memory.md).

References

• WinDbg MCP -- MCP server for WinDbg integration
• WinDbg Documentation -- Microsoft debugger documentation