傾印收集和分析公用程式 (dotnet-dump)
本文適用於： ✔️ dotnet-dump 3.0.47001 版與更新版本
注意
只有 .NET 5 和更新版本支援 dotnet-dump macOS。
安裝
有兩種方法可下載並安裝 dotnet-dump：
dotnet 全域工具：
若要安裝最新版的
dotnet-dumpNuGet 套件，請使用 dotnet tool install 命令：dotnet tool install --global dotnet-dump直接下載：
下載適用於您平台的工具可執行檔：
OS 平台 Windows x86 | x64 | Arm | Arm-x64 Linux x64 | Arm | Arm64 | musl-x64 | musl-Arm64
注意
若要在 x86 應用程式上使用 dotnet-dump，就需要對應的 x86 版工具。
概要
dotnet-dump [-h|--help] [--version] <command>
描述
dotnet-dump 全域工具可用來在 Windows、Linux 和 macOS 上收集及分析傾印，而且不需要任何原生偵錯工具。 此工具在 Alpine Linux 這類平台上很重要，因為這些平台沒有功能完整的 lldb。 dotnet-dump 工具可讓您執行 SOS 命令來分析損毀和記憶體回收行程 (GC)，但不是原生偵錯工具，因此不支援顯示原生堆疊框架這類作業。
選項。
--version顯示 dotnet-dump 公用程式的版本。
-h|--help顯示命令列說明。
命令
| Command |
|---|
| dotnet-dump collect |
| dotnet-dump analyze |
| dotnet-dump ps |
dotnet-dump collect
從處理序擷取傾印。
概要
dotnet-dump collect [-h|--help] [-p|--process-id] [-n|--name] [--type] [-o|--output] [--diag] [--crashreport]
選項。
-h|--help顯示命令列說明。
-p|--process-id <PID>指定要從中收集傾印的處理序識別碼。
-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 收集傾印，其執行身分必須與執行目標處理序的使用者或根使用者相同。 否則，此工具將無法與目標處理序建立連線。
dotnet-dump analyze
啟動互動式殼層以探索傾印。 殼層接受各種 SOS 命令。
概要
dotnet-dump analyze <dump_path> [-h|--help] [-c|--command]
引數
<dump_path>指定要分析之傾印檔案的路徑。
選項。
-c|--command <debug_command>在啟動時執行命令。 此參數的多個執行個體用以鏈結命令。 命令會依照命令行上提供的順序執行。 如果您想要在命令之後結束 dotnet 傾印，則最後一個命令應該是 'exit'。
分析 SOS 命令
| Command | 函式 |
|---|---|
analyzeoom |
顯示在 GC 堆積的配置要求上，最後發生之 OOM 的資訊。 |
clrmodules |
列出處理序中的受控模組。 |
clrstack |
僅提供 Managed 程式碼的堆疊追蹤。 |
clrthreads |
列出正在執行的受控執行緒。 |
clru |
顯示受控方法的已加註釋反組解碼。 |
d 或 readmemory |
傾印記憶體內容。 |
dbgout |
啟用/停用 (-off) 內部 SOS 記錄。 |
dso |
顯示可在目前堆疊界限內找到的所有 Managed 物件。 |
dumpalc |
顯示指定物件要載入其中的可收集 AssemblyLoadContext 其詳細資料。 |
dumparray |
顯示受控陣列的詳細資料。 |
dumpasync |
顯示記憶體回收堆積上非同步狀態機器的資訊。 |
dumpassembly |
顯示組件的詳細資料。 |
dumpclass |
顯示指定位址的 EEClass 結構資訊。 |
dumpconcurrentdictionary |
顯示並行字典內容。 |
dumpconcurrentqueue |
顯示並行佇列內容。 |
dumpdelegate |
顯示委派的資訊。 |
dumpdomain |
顯示所有 AppDomain 中所有組件或指定組件的資訊。 |
dumpgcdata |
顯示 GC 資料的資訊。 |
dumpgen |
顯示指定世代的堆積內容。 |
dumpheap |
顯示記憶體回收堆積的資訊，以及物件的收集統計資料。 |
dumpil |
顯示與 Managed 方法相關聯的通用中繼語言 （CIL）。 |
dumplog |
將記憶體中壓力記錄檔的內容寫入指定的檔案。 |
dumpmd |
顯示指定位址的 MethodDesc 結構資訊。 |
dumpmodule |
顯示指定位址的模組資訊。 |
dumpmt |
顯示指定位址的方法資料表資訊。 |
dumpobj |
顯示指定位址的物件資訊。 |
dumpruntimetypes |
尋找 GC 堆積中的所有 System.RuntimeType 物件，並列印其參考的類型名稱和 MethodTable。 |
dumpsig |
傾印 <sigaddr> <moduleaddr> 所指定方法或欄位的特徵標記。 |
dumpsigelem |
傾印特徵標記物件的單一元素。 |
dumpstackobjects |
顯示可在目前堆疊界限內找到的所有 Managed 物件。 |
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 命令的目前執行緒識別碼。 |
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 Runtime 的內建傾印產生功能都可以建立核心傾印。
$ 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。 如果您在收集傾印時遇到問題，您執行的環境可能已設定為限制這類呼叫。 請參閱我們的傾印：常見問題集，以取得常見問題的疑難排解祕訣和潛在解決方案。
