本文适用于：✔️ 版本 3.0.47001 及更高版本
注意
macOS 的 dotnet-dump 仅在 .NET 5 及更高版本中受支持。
安装
可采用两种方法来下载和安装 dotnet-dump：
dotnet 全局工具：
若要安装最新版
dotnet-dumpNuGet 包，请使用 dotnet tool install 命令：dotnet tool install --global dotnet-dump直接下载：
下载与平台相匹配的工具可执行文件：
(OS) 平台 Windows操作系统 x86 | x64 | 手臂 | Arm-x64 Linux的 x64 | 手臂 | Arm64 | musl-x64 | musl-Arm64
注意
若要在 x86 应用上使用 dotnet-dump，需要使用相应的 x86 版本的工具。
摘要
dotnet-dump [-h|--help] [--version] <command>
说明
dotnet-dump 全局工具是在未涉及任何本机调试器的情况下收集和分析 Windows、Linux 和 macOS 转储的方法。 在 lldb 无法正常运行的平台（如 Alpine Linux）上，此工具非常重要。 借助 dotnet-dump 工具，可以运行 SOS 命令来分析崩溃和垃圾回收器 (GC)，但它不是本机调试器，因此不支持显示本机堆栈帧之类的操作。
选项
--version显示 dotnet-dump 实用工具的版本。
-h|--help显示命令行帮助。
命令
| 命令 |
|---|
| dotnet-dump 收集 |
| dotnet-dump 分析 |
| dotnet-dump ps |
dotnet-dump 收集
从进程捕获转储。
摘要
dotnet-dump collect [-h|--help] [-p|--process-id] [-n|--name] [--type] [-o|--output] [--diag] [--crashreport]
选项
-h|--help显示命令行帮助。
-p|--process-id <PID>指定从中收集转储的进程的 ID 号。
-n|--name <name>指定从中收集转储的进程的名称。
--type <Full|Heap|Mini>指定转储类型，它确定从进程收集的信息的类型。 有三种类型：
-
Full- 最大的转储，包含所有内存（包括模块映像）。 -
Heap- 大型且相对全面的转储，其中包含模块列表、线程列表、所有堆栈、异常信息、句柄信息和除映射图像以外的所有内存。 -
Mini- 小型转储，其中包含模块列表、线程列表、异常信息和所有堆栈。
如果未指定，则
Full为默认类型。-
-o|--output <output_dump_path>应在其中写入收集的转储的完整路径和文件名。 确保运行 dotnet 进程的用户对指定目录具有写入权限。
如果未指定：
- 在 Windows 上默认为 .\dump_YYYYMMDD_HHMMSS.dmp 。
- 在 Linux 和 macOS 上默认为 ./core_YYYYMMDD_HHMMSS。
YYYYMMDD 为年/月/日，HHMMSS 为小时/分钟/秒。
--diag启用转储收集诊断日志记录。
--crashreport启用故障报告生成。
注意
在 Linux 和 macOS 上，此命令需要目标应用程序和 dotnet-dump 使用同一 TMPDIR 环境变量。 否则，该命令将超时。
注意
若要使用 dotnet-dump 收集转储，需要以与运行目标进程的用户相同的用户身份或以根身份运行。 否则，该工具将无法与目标进程建立连接。
注意
收集完整或堆转储可能会导致 OS 在目标进程的大量虚拟内存中分页。 如果目标进程在具有强制内存限制的容器中运行，则增加的内存使用量可能会导致 OS 在超出限制时终止容器。 我们建议进行测试，以确保内存限制设置得足够高。 另一种选择是在转储收集之前暂时更改或删除限制（如果环境支持这样做）。
dotnet-dump 分析
启动交互式 shell 以了解转储。 shell 接受各种 SOS 命令。
摘要
dotnet-dump analyze <dump_path> [-h|--help] [-c|--command]
自变量
<dump_path>指定要分析的转储文件的路径。
选项
-c|--command <debug_command>在启动时运行该命令。 此参数的多个实例可用于调用链接命令。 命令将按命令行上提供的顺序运行。 如果希望 dotnet 转储在命令后退出，则上一个命令应为“exit”。
分析 SOS 命令
| 命令 | 函数 |
|---|---|
analyzeoom |
显示对 GC 堆进行分配请求时发生的最后 OOM 的信息。 |
clrmodules |
列出进程中的托管模块。 |
clrstack |
仅提供托管代码的堆栈跟踪。 |
clrthreads |
列出正在运行的托管线程。 |
clru |
显示托管方法的批注反汇编。 |
d 或 readmemory |
转储内存内容。 |
dbgout |
启用/禁用 (-off) 内部 SOS 日志记录。 |
dso |
显示在当前堆栈的边界内找到的所有托管对象。 |
dumpalc |
显示有关指定对象加载到的可回收 AssemblyLoadContext 的详细信息。 |
dumparray |
显示有关托管数组的详细信息。 |
dumpasync |
显示有关垃圾回收堆上异步状态机的信息。 |
dumpassembly |
显示有关程序集的详细信息。 |
dumpclass |
显示有关指定地址处的 EEClass 结构的信息。 |
dumpconcurrentdictionary |
显示并发字典内容。 |
dumpconcurrentqueue |
显示并发队列内容。 |
dumpdelegate |
显示有关委托的信息。 |
dumpdomain |
显示有关所有 AppDomain 或指定 AppDomain 中的所有程序集的信息。 |
dumpgcdata |
显示有关 GC 数据的信息。 |
dumpgen |
显示指定代系的堆内容。 |
dumpheap |
显示有关垃圾回收堆的信息和有关对象的收集统计信息。 |
dumpil |
显示与托管方法关联的公共中间语言（CIL）。 |
dumplog |
将内存中压力日志的内容写入到指定文件。 |
dumpmd |
显示有关指定地址处的 MethodDesc 结构的信息。 |
dumpmodule |
显示有关指定地址处的模块的信息。 |
dumpmt |
显示有关指定地址处的方法表的信息。 |
dumpobj |
显示有关指定地址处的对象的信息。 |
dumpruntimetypes |
查找 GC 堆中的所有 System.RuntimeType 对象，并输出它们引用的类型名称和 MethodTable。 |
dumpsig |
转储由 <sigaddr> <moduleaddr> 指定的方法或字段的签名。 |
dumpsigelem |
转储签名对象的单个元素。 |
dumpstackobjects |
显示在当前堆栈的边界内找到的所有托管对象。 |
dumpvc |
显示有关值类的字段的信息。 |
eeheap |
显示有关内部运行时数据结构所使用的进程内存的信息。 |
eestack |
对进程中的所有线程运行 dumpstack 命令。 |
eeversion |
显示有关运行时和 SOS 版本的信息。 |
ehinfo |
显示 JIT 方法中的异常处理块。 |
exit 或 quit |
退出交互模式。 |
finalizequeue |
显示所有已进行终结注册的对象。 |
findappdomain |
尝试解析 GC 对象的 AppDomain。 |
gchandles |
显示有关进程中的垃圾回收器句柄的统计信息。 |
gcheapstat |
显示有关垃圾回收器的统计信息。 |
gcinfo |
显示方法的 JIT GC 编码。 |
gcroot |
显示有关对指定地址处的对象的引用（或根）的信息。 |
gcwhere |
显示指定地址在 GC 堆中的位置。 |
histclear |
释放由 Hist 命令系列使用的任何资源。 |
histinit |
从保存在调试对象中的压力日志初始化 SOS 结构。 |
histobj |
检查所有压力日志的重定位记录，并显示可能已将地址作为自变量传入的垃圾回收重定位链。 |
histobjfind |
显示在指定地址处引用对象的所有日志项。 |
histroot |
显示与指定根的提升和重定位相关的信息。 |
histstats |
显示压力日志统计信息。 |
ip2md |
显示已 JIT 编译的代码中指定地址处的 MethodDesc 结构。 |
listnearobj |
显示指定地址前后的对象。 |
logopen |
启用控制台文件日志记录。 |
logclose |
禁用控制台文件日志记录。 |
logging |
启用/禁用内部 SOS 日志记录。 |
lm 或 modules |
显示进程中的本机模块。 |
name2ee |
显示指定模块中的指定类型或方法的 MethodTable 和 EEClass 结构。 |
objsize |
显示指定对象的大小。 |
parallelstacks |
显示与 Visual Studio“并行堆栈”面板类似的合并线程堆栈。 |
pathto |
显示从 <root> 到 <target> 的 GC 路径。 |
pe 或 printexception |
显示从指定地址处的 Exception 类派生的任何对象的字段并设置这些字段的格式。 |
r 或 registers |
显示线程的寄存器。 |
runtimes |
列出目标中的运行时或更改默认运行时。 |
setclrpath |
使用 setclrpath <path> 设置加载 coreclr dac/dbi 文件的路径。 |
setsymbolserver |
启用符号服务器支持。 |
sos |
执行各种 coreclr 调试命令。 使用语法 sos <command-name> <args>。 有关详细信息，请参阅“soshelp”。 |
soshelp 或 help |
显示所有可用命令。 |
soshelp <command> 或 help <command> |
执行指定的命令。 |
syncblk |
显示 SyncBlock 持有者信息。 |
taskstate |
以人类可读格式显示任务状态。 |
threadpool |
显示有关运行时线程池的信息。 |
threadpoolqueue |
显示排队的线程池工作项。 |
threadstate |
整齐输出线程状态的含义。 |
threads <threadid> 或 setthread <threadid> |
设置或显示 SOS 命令的当前线程 ID。 |
timerinfo |
显示有关正在运行的计时器的信息。 |
token2ee |
显示指定令牌和模块的 MethodTable 结构和 MethodDesc 结构。 |
traverseheap |
以 CLR 探查器能够理解的格式将堆信息写入文件。 |
verifyheap |
检查 GC 堆是否有损坏的迹象。 |
verifyobj |
检查作为自变量传递的对象是否有损坏迹象。 |
注意
可以在适用于 .NET 的 SOS 调试扩展中找到其他详细信息。
dotnet-dump ps
列出可以从中收集转储的 dotnet 进程。
dotnet-dump 版本 6.0.320703 及更高版本还显示每个进程的启动命令行参数（如果可用）。
摘要
dotnet-dump ps [-h|--help]
示例
假设使用命令 dotnet run --configuration Release 启动长时间运行的应用。 在另一个窗口中，运行 dotnet-dump ps 命令。 你将看到如下输出。 命令行参数（如果有）显示在 dotnet-dump 版本 6.0.320703 及更高版本中。
> dotnet-dump ps
21932 dotnet C:\Program Files\dotnet\dotnet.exe run --configuration Release
36656 dotnet C:\Program Files\dotnet\dotnet.exe
使用 dotnet-dump
第一步是收集转储。 如果已生成核心转储，则可以跳过此步骤。 操作系统或 .NET Core 运行时的内置转储生成功能均可以创建核心转储。
$ dotnet-dump collect --process-id 1902
Writing minidump to file ./core_20190226_135837
Written 98983936 bytes (24166 pages) to core file
Complete
现在，使用 analyze 命令分析核心转储：
$ dotnet-dump analyze ./core_20190226_135850
Loading core dump: ./core_20190226_135850
Ready to process analysis commands. Type 'help' to list available commands or 'help [command]' to get detailed help on a command.
Type 'quit' or 'exit' to exit the session.
>
此操作会显示一个交互式会话，该会话接受以下类似命令：
> clrstack
OS Thread Id: 0x573d (0)
Child SP IP Call Site
00007FFD28B42C58 00007fb22c1a8ed9 [HelperMethodFrame_PROTECTOBJ: 00007ffd28b42c58] System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo) [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.Program.Foo4(System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.Program.Foo2(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.Program.Foo1(Int32, System.String) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.Program.Main(System.String[]) [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]
00007FFD28B43210 00007fb22aa9cedf [GCFrame: 00007ffd28b43210]
00007FFD28B43610 00007fb22aa9cedf [GCFrame: 00007ffd28b43610]
查看已终止应用的未经处理的异常：
> pe -lines
Exception object: 00007fb18c038590
Exception type: System.Reflection.TargetInvocationException
Message: Exception has been thrown by the target of an invocation.
InnerException: System.Exception, Use !PrintException 00007FB18C038368 to see more.
StackTrace (generated):
SP IP Function
00007FFD28B42DD0 0000000000000000 System.Private.CoreLib.dll!System.RuntimeMethodHandle.InvokeMethod(System.Object, System.Object[], System.Signature, Boolean, Boolean)
00007FFD28B42DD0 00007FB1B1334F67 System.Private.CoreLib.dll!System.Reflection.RuntimeMethodInfo.Invoke(System.Object, System.Reflection.BindingFlags, System.Reflection.Binder, System.Object[], System.Globalization.CultureInfo)+0xa7 [/root/coreclr/src/mscorlib/src/System/Reflection/RuntimeMethodInfo.cs @ 472]
00007FFD28B42E20 00007FB1B18D33ED SymbolTestApp.dll!SymbolTestApp.Program.Foo4(System.String)+0x15d [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 54]
00007FFD28B42ED0 00007FB1B18D2FC4 SymbolTestApp.dll!SymbolTestApp.Program.Foo2(Int32, System.String)+0x34 [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 29]
00007FFD28B42F00 00007FB1B18D2F5A SymbolTestApp.dll!SymbolTestApp.Program.Foo1(Int32, System.String)+0x3a [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 24]
00007FFD28B42F30 00007FB1B18D168E SymbolTestApp.dll!SymbolTestApp.Program.Main(System.String[])+0x6e [/home/mikem/builds/SymbolTestApp/SymbolTestApp/SymbolTestApp.cs @ 19]
StackTraceString: <none>
HResult: 80131604
排查转储集合问题
转储集合要求进程能够调用 ptrace。 如果收集转储时遇到问题，则运行的环境可能配置为了限制此类调用。 请参阅转储：常见问题解答，了解常见问题的故障排除提示和潜在解决方案。
