A dump is a file that contains a snapshot of the process at the time it was created and can be useful for examining the state of your application. Dumps can be used to debug your .NET application when it is difficult to attach a debugger to it such as production or CI environments. Using dumps allows you to capture the state of the problematic process and examine it without having to stop the application.
Dumps can be collected in a variety of ways depending on which platform you are running your app on.
Dumps may contain sensitive information because they can contain the full memory of the running process. Handle them with any security restrictions and guidances in mind.
For frequently asked questions about dump collection, analysis, and other caveats, see Dumps: FAQ.
Collect dumps on crash
You can use environment variables to configure your application to collect a dump upon a crash. This is helpful when you want to get an understanding of why a crash happened. For example, capturing a dump when an exception is thrown helps you identify an issue by examining the state of the app when it crashed.
The following table shows the environment variables you can configure for collecting dumps on a crash.
|Environment variable||Description||Default value|
||If set to 1, enable core dump generation.||0|
||Type of dump to be collected. For more information, see the table below||2 (
||Path to a file to write the dump to. Ensure that the user under which the dotnet process is running has write permissions to the specified directory.||
||If set to 1, enables diagnostic logging of dump process.||0|
||(Requires .NET 6 or later) If set to 1, the runtime generates a JSON-formatted crash report that includes information about the threads and stack frames of the crashing application. The crash report name is the dump path or name with .crashreport.json appended.|
||(Requires .NET 7 or later) If set to 1, enables verbose diagnostic logging of the dump process.||0|
||(Requires .NET 7 or later) The path of the file to which the diagnostic messages should be written. If unset, the diagnostic messages are written to the console of the crashing application.|
.NET 7 standardizes on the prefix
DOTNET_ instead of
COMPlus_ for these environment variables. However, the
COMPlus_ prefix will continue to work. If you're using a previous version of the .NET runtime, you should still use the
COMPlus_ prefix for environment variables.
Starting in .NET 5,
DOTNET_MiniDumpName may also include formatting template specifiers that will be filled in dynamically:
|%%||A single % character|
|%p||PID of dumped process|
|%e||The process executable filename|
|%h||Host name return by
|%t||Time of dump, expressed as seconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC)|
The following table shows all the values you can use for
DOTNET_DbgMiniDumpType. For example, setting
DOTNET_DbgMiniDumpType to 1 means
MiniDumpNormal type dump will be collected on a crash.
||A small dump containing module lists, thread lists, exception information, and all stacks.|
||A large and relatively comprehensive dump containing module lists, thread lists, all stacks, exception information, handle information, and all memory except for mapped images.|
||The largest dump containing all memory including the module images.|
Collect dumps at a specific point in time
You may want to collect a dump when the app hasn't crashed yet. For example, if you want to examine the state of an application that seems to be in a deadlock, configuring the environment variables to collect dumps on crash will not be helpful because the app is still running.
To collect dump at your own request, you can use
dotnet-dump, which is a CLI tool for collecting and analyzing dumps. For more information on how to use it to collect dumps with
dotnet-dump, see Dump collection and analysis utility.
Visual Studio version 16.8 and later allows you to open Linux dumps generated on .NET Core 3.1.7 or later.
Learn more about how you can leverage dumps to help diagnosing problems in your .NET application.
Submit and view feedback for