Meziantou.Framework.Diagnostics.MemoryDump 1.0.0

Meziantou.Framework.Diagnostics.MemoryDump

Create a memory dump of the current process on Windows, Linux, and macOS, without installing dotnet-dump or any other tool.

Usage

using Meziantou.Framework.Diagnostics;

// Full dump (default)
MemoryDump.Write("app.dmp");

// Smaller dump containing the managed heap
await MemoryDump.WriteAsync("app.dmp", MemoryDumpType.WithHeap, cancellationToken);

You can open the dump with Visual Studio, WinDbg, dotnet-dump analyze, or lldb with the SOS extension.

A typical use is to dump the process when it detects a problem it cannot explain, such as thread pool starvation or a request that never completes:

if (queueDelay > TimeSpan.FromSeconds(5))
{
    MemoryDump.Write(Path.Combine(dumpDirectory, $"starvation-{DateTime.UtcNow:yyyyMMddHHmmss}.dmp"));
}

Dump types

The types match the DumpType enum of Microsoft.Diagnostics.NETCore.Client and the --normal, --withheap, --triage, and --full options of createdump.

How it works

• Windows: captures a snapshot of the process with PssCaptureSnapshot, then writes it with MiniDumpWriteDump from dbghelp.dll, as Windows Error Reporting does. A process cannot suspend itself, so dumping the live process directly can fail when its memory changes while it is read.
• Linux and macOS: runs the createdump tool shipped with the .NET runtime, looked up in the runtime directory, then in the application directory (self-contained and single-file apps).

Calls are serialized: when several threads request a dump at the same time, the dumps are written one after the other.

Remarks

• A memory dump may contain sensitive data such as credentials, tokens, or connection strings. Store and share it accordingly.

• A full dump is as large as the memory used by the process, often hundreds of megabytes.

• The process is suspended while the dump is written.

• A process in a bad state (e.g. out of memory) may not be able to dump itself.

• On Linux, when Yama restricts ptrace (kernel.yama.ptrace_scope = 1, the default on Ubuntu), createdump is not allowed to attach to its parent process. MemoryDump calls prctl(PR_SET_PTRACER, PR_SET_PTRACER_ANY) before starting createdump and resets it with prctl(PR_SET_PTRACER, 0) afterward. This overrides any value set by the application. With ptrace_scope = 2, the process needs the CAP_SYS_PTRACE capability, and with ptrace_scope = 3, no dump can be created.

• In a container, ptrace may be blocked by the seccomp profile or require the SYS_PTRACE capability.

• On macOS, createdump can only attach to a process signed with the com.apple.security.get-task-allow entitlement. The dotnet host has it, so dotnet app.dll works. The app host generated by the SDK (./app) is signed without entitlements. Re-sign it to allow dumps:

  
  <plist version="1.0">
  <dict>
      <key>com.apple.security.get-task-allow</key>
      <true/>
  </dict>
  </plist>
  

  codesign --force --sign - --entitlements entitlements.plist ./app