dotnet-debugging

dotnet-debugging

概述

使用 WinDbg MCP 工具（Windows）、dotnet-dump 和配合 SOS 的 lldb（Linux/macOS）进行 Windows 和 Linux/macOS 调试。适用于任何应用程序——本机应用程序、托管应用程序（.NET/CLR）或混合模式应用程序。包含 Docker 和 Kubernetes 容器诊断模式。通过结构化命令包和报告模板，指导排查崩溃转储、应用程序挂起、高 CPU 占用和内存压力问题。

**平台：**Windows（WinDbg MCP、cdb）、Linux/macOS（dotnet-dump、配合 SOS 的 lldb、createdump、dotnet-monitor）。

路由表

主题	关键词	说明	配套文件
MCP 设置	MCP server、WinDbg、configuration	MCP 服务配置	references/mcp-setup.md
MCP 访问	MCP access、tool IDs、dispatch	MCP 访问模式	references/access-mcp.md
常见模式	debug patterns、SOS、CLR	常见调试模式	references/common-patterns.md
转储工作流	dump file、.dmp、crash dump	转储文件分析工作流	references/dump-workflow.md
实时附加	live process、cdb、attach	实时进程附加指南	references/live-attach.md
符号	symbol server、.symfix、PDB	符号配置	references/symbols.md
基本检查	verify、environment、baseline	基本检查流程	references/sanity-check.md
场景命令包	command pack、triage、workflow	场景命令包	references/scenario-command-packs.md
捕获操作手册	capture、procdump、triggers	捕获操作手册	references/capture-playbooks.md
报告模板	diagnostic report、evidence	诊断报告模板	references/report-template.md
崩溃分诊	crash、exception、access violation	崩溃分诊	references/task-crash.md
挂起分诊	hang、deadlock、freeze	挂起分诊	references/task-hang.md
高 CPU 占用分诊	high CPU、runaway thread、spin	高 CPU 占用分诊	references/task-high-cpu.md
内存分诊	memory leak、heap、LOH	内存泄漏分诊	references/task-memory.md
内核调试	kernel、BSOD、bugcheck	内核调试	references/task-kernel.md
未知问题分诊	unknown issue、general triage	未知问题分诊	references/task-unknown.md
Linux 调试	dotnet-dump、lldb、createdump、container	Linux/macOS 调试、dotnet-dump、lldb SOS、容器	references/linux-debugging.md

范围

• 在 Windows、Linux 和 macOS 上分析崩溃转储（.dmp 文件）
• 实时进程附加（Windows 上使用 cdb，Linux/macOS 上使用 lldb）
• 挂起和死锁诊断（线程分析、锁检测、等待链）
• 高 CPU 占用分诊（识别失控线程）
• 内存压力和泄漏排查（托管堆、本机堆）
• 内核转储分诊（BSOD / bugcheck 分析，Windows）
• 容器诊断（在 Docker/Kubernetes 中使用 dotnet-dump、sidecar 模式）
• 生产环境诊断（dotnet-monitor REST API、基于触发器的采集）
• 跨平台 SOS 命令（WinDbg、dotnet-dump、lldb）
• 包含堆栈证据的结构化诊断报告

与 dotnet-tooling 的边界

这两项技能使用了部分相同的工具（dotnet-dump、dotnet-counters、dotnet-trace），但用途不同：

场景	使用此技能（调试）	使用 dotnet-tooling
调查崩溃转储（.dmp）	是	否
“我的应用为什么崩溃／挂起／内存不足？”	是	否
将调试器附加到正在运行的进程	是	否
“如何分析应用的性能？”	否	是（性能分析）
“如何降低 GC 压力？”	否	是（gc-memory）
收集转储以供后续分析	是	否
运行 dotnet-counters 监控指标	否	是（性能分析）
使用 dotnet-dump 分析转储	是	否
反编译程序集以了解其行为	否	是（ilspy-decompile）

一般来说：如果出了故障（崩溃、挂起、死锁、内存不足），请使用此技能。如果运行缓慢或需要优化，请使用 dotnet-tooling。

不在范围内

• 性能分析（使用 dotnet-counters、dotnet-trace 进行优化）→ dotnet-tooling
• GC 调优和托管内存优化 → dotnet-tooling
• 程序集反编译（ILSpy）→ dotnet-tooling
• 性能基准测试和回归检测 → dotnet-testing
• 应用级日志记录和可观测性 → dotnet-devops
• 单元测试／集成测试调试 → dotnet-testing

MCP 工具契约

这些工具 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	关闭转储会话

诊断工作流

前置步骤：符号

开始分析前，请配置符号，以获取有意义的堆栈信息：

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

如果符号不正确，堆栈中显示的将是原始地址，而不是函数名称。

崩溃转储分析

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

挂起／死锁诊断

1. 附加到进程或打开转储，然后加载 SOS
2. 列出所有线程：!threads，使用 !syncblk（同步块表）找出正在等待的线程
3. 检测死锁：!dlk（SOS 死锁检测）
4. 检查线程堆栈：对特定线程 N 使用 ~Ns !clrstack
5. 检查等待原因：使用 !waitchain 检查 COM/RPC 链，使用 !mda 获取 MDA 诊断信息

高 CPU 占用初步排查

1. 附加到正在运行的进程，或间隔 10-30 秒收集多个转储
2. 使用 !runaway 找出占用 CPU 时间最多的线程
3. 检查热点线程堆栈：~Ns kb（原生堆栈）、~Ns !clrstack（托管堆栈）
4. 查找紧密循环、被阻塞的终结器线程或过度 GC

内存压力调查

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

报告模板

## 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]

防护原则

• 如果没有被调用方一侧的证据，不要声称确定无疑。
• 除非锁/等待证据足以支持，否则不要称之为死锁。
• 保护用户隐私：报告中不要包含环境块里的机密信息。

交叉引用：dotnet-tooling，用于 .NET SDK 诊断工具（references/profiling.md）以及 GC/内存调优（references/gc-memory.md）。

参考资料

• WinDbg MCP -- 用于集成 WinDbg 的 MCP 服务
• WinDbg Documentation -- Microsoft 调试器文档