dotnet-debugging

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dotnet-debugging

.NET调试

Overview

概述

Windows user-mode debugging using WinDbg MCP tools. Applicable to any Windows application -- native, managed (.NET/CLR), or mixed-mode. Guides investigation of crash dumps, application hangs, high CPU, and memory pressure through structured command packs and report templates.

Platform: Windows only.

使用WinDbg MCP工具进行Windows用户模式调试。适用于任何Windows应用程序——原生、托管（.NET/CLR）或混合模式。通过结构化命令包和报告模板指导崩溃转储、应用挂起、高CPU和内存压力问题的排查。

平台：仅支持Windows

Routing Table

路由表

Topic	Keywords	Description	Companion File
MCP setup	MCP server, WinDbg, configuration	MCP server configuration	references/mcp-setup.md
MCP access	MCP access, tool IDs, dispatch	MCP access patterns	references/access-mcp.md
Common patterns	debug patterns, SOS, CLR	Common debugging patterns	references/common-patterns.md
Dump workflow	dump file, .dmp, crash dump	Dump file analysis workflow	references/dump-workflow.md
Live attach	live process, cdb, attach	Live process attach guide	references/live-attach.md
Symbols	symbol server, .symfix, PDB	Symbol configuration	references/symbols.md
Sanity check	verify, environment, baseline	Sanity check procedures	references/sanity-check.md
Scenario packs	command pack, triage, workflow	Scenario command packs	references/scenario-command-packs.md
Capture playbooks	capture, procdump, triggers	Capture playbooks	references/capture-playbooks.md
Report template	diagnostic report, evidence	Diagnostic report template	references/report-template.md
Crash triage	crash, exception, access violation	Crash triage	references/task-crash.md
Hang triage	hang, deadlock, freeze	Hang triage	references/task-hang.md
High-CPU triage	high CPU, runaway thread, spin	High-CPU triage	references/task-high-cpu.md
Memory triage	memory leak, heap, LOH	Memory leak triage	references/task-memory.md
Kernel debugging	kernel, BSOD, bugcheck	Kernel debugging	references/task-kernel.md
Unknown triage	unknown issue, general triage	Unknown issue triage	references/task-unknown.md

主题	关键词	描述	配套文件
MCP设置	MCP服务器、WinDbg、配置	MCP服务器配置	references/mcp-setup.md
MCP访问	MCP访问、工具ID、调度	MCP访问模式	references/access-mcp.md
常见模式	调试模式、SOS、CLR	常见调试模式	references/common-patterns.md
转储工作流	转储文件、.dmp、崩溃转储	转储文件分析工作流	references/dump-workflow.md
实时附加	实时进程、cdb、附加	实时进程附加指南	references/live-attach.md
符号	符号服务器、.symfix、PDB	符号配置	references/symbols.md
完整性检查	验证、环境、基线	完整性检查流程	references/sanity-check.md
场景包	命令包、分类、工作流	场景命令包	references/scenario-command-packs.md
捕获手册	捕获、procdump、触发器	捕获手册	references/capture-playbooks.md
报告模板	诊断报告、证据	诊断报告模板	references/report-template.md
崩溃分类	崩溃、异常、访问违规	崩溃分类	references/task-crash.md
挂起分类	挂起、死锁、冻结	挂起分类	references/task-hang.md
高CPU分类	高CPU、失控线程、自旋	高CPU分类	references/task-high-cpu.md
内存分类	内存泄漏、堆、LOH	内存泄漏分类	references/task-memory.md
内核调试	内核、BSOD、错误检查	内核调试	references/task-kernel.md
未知问题分类	未知问题、通用分类	未知问题分类	references/task-unknown.md

Scope

适用范围

Crash dump analysis (.dmp files) for any Windows process (native, .NET, or mixed-mode)
Live process attach via cdb debug server
Hang and deadlock diagnosis (thread analysis, lock detection)
High CPU triage (runaway thread identification)
Memory pressure and leak investigation via native heap analysis
Kernel dump triage (BSOD / bugcheck analysis)
COM/RPC wait chain and UI message pump analysis
Structured diagnostic reports with stack evidence

任何Windows进程（原生、.NET或混合模式）的崩溃转储分析（.dmp文件）
通过cdb调试服务器进行实时进程附加
挂起和死锁诊断（线程分析、锁检测）
高CPU问题分类（识别失控线程）
通过原生堆分析排查内存压力和泄漏问题
内核转储分类（BSOD/错误检查分析）
COM/RPC等待链和UI消息泵分析
包含堆栈证据的结构化诊断报告

Out of scope

不适用范围

.NET SDK diagnostic tools (dotnet-counters, dotnet-trace, dotnet-dump) -> [skill:dotnet-tooling]
GC tuning and managed memory optimization -> [skill:dotnet-tooling]
Performance benchmarking and regression detection -> [skill:dotnet-testing]
Application performance architecture patterns -> [skill:dotnet-tooling]
Application-level logging -> [skill:dotnet-devops]
Unit/integration test debugging -> [skill:dotnet-testing]

.NET SDK诊断工具（dotnet-counters、dotnet-trace、dotnet-dump）-> [skill:dotnet-tooling]
GC调优和托管内存优化 -> [skill:dotnet-tooling]
性能基准测试和回归检测 -> [skill:dotnet-testing]
应用性能架构模式 -> [skill:dotnet-tooling]
应用级日志 -> [skill:dotnet-devops]
单元/集成测试调试 -> [skill:dotnet-testing]

MCP Tool Contract

MCP工具契约

These tool IDs are the WinDbg MCP server's exported names (single-underscore

mcp_...

), not the

mcp__...

dispatch prefix used by some hosts.

Operation	Purpose
`mcp_mcp-windbg_open_windbg_remote`	Attach to a live debug server
`mcp_mcp-windbg_open_windbg_dump`	Open a saved dump file
`mcp_mcp-windbg_run_windbg_cmd`	Execute debugger commands
`mcp_mcp-windbg_close_windbg_remote`	Detach from live session
`mcp_mcp-windbg_close_windbg_dump`	Close dump session

这些工具ID是WinDbg MCP服务器的导出名称（单下划线

mcp_...

），而非某些主机使用的

mcp__...

调度前缀。

操作	用途
`mcp_mcp-windbg_open_windbg_remote`	附加到实时调试服务器
`mcp_mcp-windbg_open_windbg_dump`	打开已保存的转储文件
`mcp_mcp-windbg_run_windbg_cmd`	执行调试器命令
`mcp_mcp-windbg_close_windbg_remote`	从实时会话分离
`mcp_mcp-windbg_close_windbg_dump`	关闭转储会话

Diagnostic Workflow

诊断工作流

Preflight: Symbols

预检：符号

Before any analysis, configure symbols to get meaningful stacks:

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

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

在进行任何分析之前，配置符号以获取有意义的堆栈：

设置Microsoft符号服务器：
```
.symfix
```
（将
```
srv*
```
设置为Microsoft公共符号）
添加应用符号：
```
.sympath+ C:\path\to\your\pdbs
```
重新加载模块：
```
.reload /f
```
验证：
```
lm
```
（列出模块——检查“deferred”（延迟加载）与“loaded”（已加载）状态）

如果没有正确的符号，堆栈将显示原始地址而非函数名称。

Crash Dump Analysis

崩溃转储分析

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

打开转储：使用转储文件路径执行
```
mcp_mcp-windbg_open_windbg_dump
```
为托管代码加载SOS：
```
.loadby sos clr
```
（适用于.NET Framework）或
```
.loadby sos coreclr
```
（适用于.NET Core）
获取异常上下文：
```
!pe
```
（打印异常）、
```
!analyze -v
```
（自动分析）
检查线程：
```
~*e !clrstack
```
（所有托管堆栈）、
```
!threads
```
（线程列表）
检查托管堆：
```
!dumpheap -stat
```
（堆摘要）、
```
!gcroot <addr>
```
（对象根）

Hang / Deadlock Diagnosis

挂起/死锁诊断

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

附加或打开转储，加载SOS
列出所有线程：
```
!threads
```
，使用
```
!syncblk
```
（同步块表）识别等待线程
检测死锁：
```
!dlk
```
（SOS死锁检测）
检查线程堆栈：针对特定线程N执行
```
~Ns !clrstack
```
检查等待原因：
```
!waitchain
```
用于COM/RPC链，
```
!mda
```
用于MDA诊断

High CPU Triage

高CPU问题分类

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

附加到实时进程或每隔10-30秒收集多个转储
使用
```
!runaway
```
识别消耗CPU最多的线程
检查热点线程堆栈：
```
~Ns kb
```
（原生堆栈）、
```
~Ns !clrstack
```
（托管堆栈）
查找紧密循环、阻塞的终结器线程或过度GC

Memory Pressure Investigation

内存压力排查

Open dump, load SOS

Managed heap:

!dumpheap -stat

(type statistics),

!dumpheap -type <TypeName>

(filter)

Find leaked objects:
```
!gcroot <address>
```
(trace GC roots to pinned or static references)
Native heap:
```
!heap -s
```
(heap summary),
```
!heap -l
```
(leak detection)
LOH fragmentation:
```
!eeheap -gc
```
(GC heap segments)

打开转储，加载SOS
托管堆：
```
!dumpheap -stat
```
（类型统计）、
```
!dumpheap -type <TypeName>
```
（过滤）
查找泄漏对象：
```
!gcroot <address>
```
（跟踪GC根到固定或静态引用）
原生堆：
```
!heap -s
```
（堆摘要）、
```
!heap -l
```
（泄漏检测）
LOH碎片：
```
!eeheap -gc
```
（GC堆段）

Report Template

报告模板

undefined

undefined

Diagnostic Report

诊断报告

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

症状： [崩溃/挂起/高CPU/内存泄漏] 进程： [名称、PID、位数] 转储类型： [完整/小型/实时附加]

Evidence

证据

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

异常：[类型和消息，或无]
故障线程：[ID、托管/原生、堆栈摘要]
关键堆栈：[包含module!function的精简调用栈]

Root Cause

根本原因

[Concise analysis backed by stack/heap evidence]

[由堆栈/堆证据支持的简洁分析]

Recommendations

建议

[Numbered action items]

undefined

[编号的操作项]

undefined

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: [skill:dotnet-tooling] for .NET SDK diagnostic tools (

references/profiling.md

) and GC/memory tuning (

references/gc-memory.md

若无被调用方侧证据，请勿声称结论确定
除非有锁/等待证据支持，否则不要称之为死锁
保护用户隐私：请勿在报告中包含环境块中的机密信息

交叉引用：有关.NET SDK诊断工具（

references/profiling.md

）和GC/内存调优（

references/gc-memory.md

），请参考[skill:dotnet-tooling]。

References

参考资料

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

WinDbg MCP —— 用于WinDbg集成的MCP服务器
WinDbg文档 —— Microsoft调试器文档