Files
dotnet-runtime/eng/testing/debug-dump-template.md
Adeel Mujahid ce99c5658c Use ProductVersion in how-to-debug-dump (#59848)
* Use ProductVersion in how-to-debug-dump
2021-10-01 10:05:14 -07:00

5.4 KiB

Get the Helix payload

Runfo helps get information about helix test runs and azure devops builds. We will use it to download the payload and symbols (recommended version 0.6.4 or later):

dotnet tool install --global runfo
dotnet tool update --global runfo

If prompted, open a new command prompt to pick up the updated PATH. Windows:

:: assumes %WOUTDIR% does not exist
runfo get-helix-payload -j %JOBID% -w %WORKITEM% -o %WOUTDIR%

Linux and macOS:

# assumes %LOUTDIR% does not exist
runfo get-helix-payload -j %JOBID% -w %WORKITEM% -o %LOUTDIR%

Any dump files published by helix will be downloaded.

NOTE: if the helix job is an internal job, you need to pass down a helix authentication token using the --helix-token argument.

Now extract the files:

Windows:

for /f %i in ('dir /s/b %WOUTDIR%\*zip') do tar -xf %i -C %WOUTDIR%

Linux and macOS

# obtain `unzip` if necessary; eg `sudo apt-get install unzip` or `sudo dnf install unzip`
find %LOUTDIR% -name '*zip' -exec unzip -d %LOUTDIR% {} \;

Now use the dotnet-sos global tool to install the SOS debugging extension.

dotnet tool install --global dotnet-sos
dotnet tool update --global dotnet-sos

If prompted, open a new command prompt to pick up the updated PATH.

:: Install only one: the one matching your dump
dotnet sos install --architecture Arm
dotnet sos install --architecture Arm64
dotnet sos install --architecture x86
dotnet sos install --architecture x64

Now choose a section below based on your OS.

If it's a Windows dump on Windows...

... and you want to debug with WinDbg

Install or update WinDbg if necessary (external, internal). If you don't have a recent WinDbg you may have to do .update sos.

Open WinDbg and open the dump with File>Open Dump.

<win-path-to-dump>
!setclrpath %WOUTDIR%\shared\Microsoft.NETCore.App\%PRODUCTVERSION%
.sympath+ %WOUTDIR%\shared\Microsoft.NETCore.App\%PRODUCTVERSION%

Now you can use regular SOS commands like !dumpstack, !pe, etc.

... and you want to debug with Visual Studio

Currently this is not possible because mscordbi.dll is not signed.

... and you want to debug with dotnet-dump

Install the dotnet-dump global tool.

dotnet tool install --global dotnet-dump
dotnet tool update --global dotnet-dump

If prompted, open a new command prompt to pick up the updated PATH.

dotnet-dump analyze ^
  <win-path-to-dump> ^
  --command "setclrpath %WOUTDIR%\shared\Microsoft.NETCore.App\%PRODUCTVERSION%" ^
  "setsymbolserver -directory %WOUTDIR%\shared\Microsoft.NETCore.App\%PRODUCTVERSION%"

Now you can use regular SOS commands like dumpstack, pe, etc. If you are debugging a 32 bit dump using 64 bit dotnet, you will get an error SOS does not support the current target architecture. In that case replace dotnet-dump with the 32 bit version:

dotnet tool uninstall --global dotnet-dump
"C:\Program Files (x86)\dotnet\dotnet.exe" tool install --global dotnet-dump

If it's a Linux dump on Windows...

Download the Cross DAC Binaries, open it and choose the flavor that matches the dump you are to debug, and copy those files to %WOUTDIR%\shared\Microsoft.NETCore.App\%PRODUCTVERSION%.

Now you can debug with WinDbg or dotnet-dump as if it was a Windows dump. See above.


If it's a Linux dump on Linux...

... and you want to debug with LLDB

Install or update LLDB if necessary (instructions here)

Load the dump:

lldb --core <lin-path-to-dump> \
  %LOUTDIR%/shared/Microsoft.NETCore.App/%PRODUCTVERSION%/dotnet \
  -o "setclrpath %LOUTDIR%/shared/Microsoft.NETCore.App/%PRODUCTVERSION%" \
  -o "setsymbolserver -directory %LOUTDIR%/shared/Microsoft.NETCore.App/%PRODUCTVERSION%"

If you want to load native symbols

loadsymbols

... and you want to debug with dotnet-dump

Install the dotnet-dump global tool.

dotnet tool install --global dotnet-dump
dotnet tool update --global dotnet-dump

If prompted, open a new command prompt to pick up the updated PATH.

dotnet-dump analyze \
  <lin-path-to-dump> \
  --command "setclrpath %LOUTDIR%/shared/Microsoft.NETCore.App/%PRODUCTVERSION%" \
  "setsymbolserver -directory %LOUTDIR%/shared/Microsoft.NETCore.App/%PRODUCTVERSION%"

If it's a macOS dump

Instructions for debugging dumps on macOS are essentially the same as Linux with one exception: dotnet-dump cannot analyze macOS system dumps yet: you must use lldb for those. As of .NET 6, createdump on macOS will start generating native Mach-O core files. dotnet-dump and ClrMD are still being worked on to handle these dumps.


Other Helpful Information