[API Proposal]: Programmatic crash dump control: ExceptionHandling.WriteCrashDump / EnableDumpOnCrash

[xen2]

Background and motivation

Today the runtime's crash dump generation (createdump) can only be controlled with environment variables (DOTNET_DbgEnableMiniDump, DOTNET_DbgMiniDumpType, DOTNET_DbgMiniDumpName) set before the process starts — the createdump command line is prebuilt at startup so the crash handler does no work. This leaves several scenarios uncovered:

• A user-launched application cannot arm crash dumps for itself (Enable minidump creation directly from application #56135): a GUI app started from the shell has no cooperative parent to set the variables, and SetEnvironmentVariable at runtime is a no-op for this purpose.
• An application cannot write a dump of itself on demand without the diagnostics IPC. The IPC route (DiagnosticsClient.WriteDump) requires a second process and a healthy diagnostics server in the target — the very thing that may be broken during a crash — and the resulting dump has no crash context (no exception stream on Windows, no crashing-thread information on Linux).
• Applications work around this in unsupported ways. The common workaround for capturing native crashes — a vectored exception handler in managed code calling MiniDumpWriteDump — is explicitly unsupported ([API Proposal]: Calling UnmanagedCallersOnly method regardless of GC mode #119142) and now crashes under a debugger on .NET 10 (Regression in net10.0: vectored exception handler crashes under the debugger #133066).
• After the dump, nothing user-visible happens. For interactive apps the crashed process is dead (and if it is a GUI app, cannot render); showing a crash-report UI or uploading the dump requires a fresh process, which today means shipping a separate pre-spawned monitor.

In the discussion on #101560, @noahfalk suggested splitting this into two complementary APIs (comment):

• New BCL CreateDump() style API - flexible programatic control for dump creation at any point
• New BCL ConfigureDumpOnCrash() style API - more limited options but covers more failure types

This proposal is exactly that pair, on the class that already hosts the crash-handling APIs (ExceptionHandling.SetUnhandledExceptionHandler / the upcoming SetFatalErrorHandler, #129543):

1. WriteCrashDump — write a dump of the current process on demand, by launching createdump directly (no IPC). When the calling thread has an exception in flight (e.g. inside an AppDomain.UnhandledException handler), the dump records that exception and thread as the crash, so debuggers and analysis tools open it at the failure point.
2. EnableDumpOnCrash / DisableDumpOnCrash — enable/disable/reconfigure the runtime's own on-crash dump at any time from managed code, overriding the environment. Because no managed code needs to run after the failure, this covers crash types no managed handler can (native threads, stack overflow, runtime corruption). An overload also specifies a program (e.g. a crash reporter) that createdump launches once the dump has been written, from a fresh process, closing the "show UI / upload from a dead process" gap.

API Proposal

namespace System.Runtime.ExceptionServices;

public static partial class ExceptionHandling
{
    // existing: SetUnhandledExceptionHandler, RaiseAppDomainUnhandledExceptionEvent

    /// Writes a dump of the current process by launching createdump directly (no diagnostics IPC);
    /// blocks until the dump is written. When the calling thread has an exception in flight, the
    /// dump records it as the crash (exception stream on Windows).
    public static void WriteCrashDump(string path, CrashDumpType type = CrashDumpType.WithHeap);

    /// Enables/changes the dump the runtime writes when the process crashes, overriding
    /// the DOTNET_DbgEnableMiniDump* environment variables. Callable at any time; last call wins.
    public static void EnableDumpOnCrash(CrashDumpType type = CrashDumpType.WithHeap,
        string? pathTemplate = null);

    /// Same, with a program createdump launches once the crash dump has been written. %f in the
    /// arguments is replaced with the dump path (plus the usual %p/%e/%h/%t specifiers).
    public static void EnableDumpOnCrash(CrashDumpType type, string? pathTemplate,
        string launchProgram, params string[]? launchArguments);

    /// Disables dump on process crash
    public static void DisableDumpOnCrash();
}

public enum CrashDumpType
{
    Normal = 1,     // same values as the existing DumpType in
    WithHeap = 2,   // Microsoft.Diagnostics.NETCore.Client and DOTNET_DbgMiniDumpType
    Triage = 3,
    Full = 4,
}

Note: I hesitated between a single ConfigureDumpOnCrash and EnableDumpOnCrash with overloads plus DisableDumpOnCrash. I didn't like the former much because it needs an enabled flag (or a nullable CrashDumpType? with null meaning disabled), which makes contradictory calls representable (e.g. disabled but with a launch program) and gives disabling an unclear call site (ConfigureDumpOnCrash(false, ...) / ConfigureDumpOnCrash(null)), while EnableDumpOnCrash/DisableDumpOnCrash are self-describing.

Semantics:

• pathTemplate/path support the existing dump name specifiers (%p pid, %e executable name, %h hostname, %t timestamp).
• EnableDumpOnCrash does all its work at call time, in a healthy context; nothing is added to what the crash handler does today.
• The launch program can only be configured through the API, never from the environment — with the environment variables alone, a crash still only ever runs createdump itself. This avoids turning the knob into arbitrary-code-execution-on-crash for anyone who can set environment variables (the concern that applied to the env-var shape of Register a custom crash handler #95461). Precedents for the mechanism: Linux core_pattern pipes (but system-global, root-only) and Windows WerRegisterRuntimeExceptionModule (but native-DLL-only, Windows-only); this is the portable, per-process, in-app-registered equivalent.
• The launched program only starts once the dump has been fully written, runs in a fresh process, and is not waited on.
• Errors: WriteCrashDump throws IOException if the dump could not be written; all of these methods throw PlatformNotSupportedException where unsupported (NativeAOT, Mono, iOS/tvOS/wasm initially).

API Usage

// Game engine editor (user-launched GUI app, cannot use DOTNET_DbgEnableMiniDump):
// arm the runtime dumper and have it start our crash reporter after writing the dump.
ExceptionHandling.EnableDumpOnCrash(
    CrashDumpType.WithHeap,
    Path.Combine(crashDir, "editor-%p-%t.dmp"),
    "crashreporter.exe",
    "--dump", "%f", "--pid", "%p");

// On-demand dump with the in-flight exception recorded, e.g. before showing an error dialog:
AppDomain.CurrentDomain.UnhandledException += (s, e) =>
{
    ExceptionHandling.WriteCrashDump(Path.Combine(crashDir, "managed-%p-%t.dmp"), CrashDumpType.Normal);
    // ... report/upload, then let the process die
};

// CI/tools can turn dumps off for intentionally-crashing child scenarios:
ExceptionHandling.DisableDumpOnCrash();

Composition with SetFatalErrorHandler (#129543), once it ships: for fatal errors (native-thread faults, FailFast, runtime errors), EnableDumpOnCrash alone already produces the dump and launches the reporter with no managed code running after the failure — no handler needed. A fatal error handler adds value when the app wants to write the dump at a moment of its choosing or capture app-specific state first:

// Illustrative only — #129543 is in progress, and whether managed code may run in the fatal
// error handler is one of the open questions below (the alternative is a native function
// pointer exposing the same operation, see Open questions).
[UnmanagedCallersOnly]
static int OnFatalError(nint context)
{
    ExceptionHandling.WriteCrashDump(fatalDumpPath, CrashDumpType.WithHeap);
    // ... spawn/notify the reporter with fatalDumpPath ...
    return RunDefaultHandler;
}
ExceptionHandling.SetFatalErrorHandler(&OnFatalError);

Alternative Designs

• runtimeconfig.json knobs for the arming half (the direction once suggested on Enable minidump creation directly from application #56135): solves the build-time case but not per-user dump paths (%LOCALAPPDATA%-style) or runtime decisions; could still be added later on top of the same internals.
• A parameter object for the launch pair (CrashDumpLaunch { Program, Arguments }) instead of an overload: more extensible but more verbose/heavier; ProcessStartInfo is not reusable (wrong assembly, and most of its surface (environment, redirects) would not be honored).

Open Questions

• Is calling the managed WriteCrashDump from a SetFatalErrorHandler callback (native, possibly corrupted process) supported? Otherwise another option is to expose a native function pointer (as in [WIP]: Wire on-demand in-proc crash report generation into the fatal error handler API- #131414 #131959 for crash log function).
• While a fatal error handler is active, should on-demand dumps (this API and the diagnostics IPC dump command used by dotnet-dump collect) attach the stored crash context? (Offered in [API Proposal]: Overriding the default behavior in case of unhandled exceptions and fatal errors. #101560; natural follow-up.)

Risks

• The launch feature can execute on crash; it's API only and should never be configurable from env variable due to security risks.

[dotnet-policy-service]

Tagging subscribers to this area: @steveisok, @tommcdon, @dotnet/dotnet-diag
See info in area-owners.md if you want to be subscribed.

[dotnet-policy-service]

Tagging subscribers to this area: @steveisok, @dotnet/area-system-diagnostics
See info in area-owners.md if you want to be subscribed.

[noahfalk]

@tarekgh @dotnet/area-system-diagnostics - I'm planning to look at this more closely but just trying to give a heads up to anyone interested on the BCL team. I'm not sure if 'ExceptionHandling' is right place for the API... It seems like it probably belongs in System.Diagnostics somewhere.

@xen2 - thanks for putting this together! I didn't get a chance to dig into it yet but I will, hopefully this week.

[noahfalk]

Is calling the managed WriteCrashDump from a SetFatalErrorHandler callback (native, possibly corrupted process) supported?

It doesn't appear to be part of the original design, but I think its very reasonable to propose it as an addition. @lateralusX also proposed it in his reply. I've been catching up on more discussion around the error handling feature myself since I hadn't been too involved previously. My original suggestion for a separate enable dump on crash API was based on the limitations of a managed callback, but since the feature already includes the SetFatalErrorHandler native callback that seems like a more integrated place to attach the crash handling. I also saw you wanted the capability to run a 2nd crash handler process after the dump was collected so the functionality is also growing a bit beyond just an env var alternative.

While a fatal error handler is active, should on-demand dumps (this API and the diagnostics IPC dump command used by dotnet-dump collect) attach the stored crash context?

That seems like desirable behavior if it didn't introduce too much complexity into the implementation or create reliability risks. I struggle to think of a situation where someone requests a dump after a fatal error occurs and they wouldn't want the crash context included.

In terms of how to move this forward for the dump writing part I just had some minor suggestions on API shape. Ultimately the API review may have yet other opinions that I am happy to defer to. This is just me trying to anticipate a bit:

Managed dump writing API

namespace System.Diagnostics;

public static class MemoryDump
{
    /// Writes a dump of the current process by launching createdump directly (no diagnostics IPC);
    /// blocks until the dump is written. When the calling thread has an exception in flight, the
    /// dump records it as the crash (exception stream on Windows).
    /// May throw NotSupportedException when an application doesn't include memory dump writing
    /// capability, either because the runtime doesn't support it (example Mono) or because the
    /// application form factor didn't bundle it.
    public static void Write(string path, MemoryDumpKind kind);
}

public enum MemoryDumpKind
{
    Normal = 1,     // same values as the existing DumpType in
    Heap = 2,       // Microsoft.Diagnostics.NETCore.Client and DOTNET_DbgMiniDumpType
    Triage = 3,
    Full = 4,
}

I included a few minor adjustments to the API shape in there:

• Moved to System.Diagnostics since dumps need not be connected to any Exception
• Named 'MemoryDump' instead of 'CrashDump' since the dump can be written in a non-crashing state
• Changed 'WithHeap' -> 'Heap' to match the style of the other names.
• 'CrashDumpType' -> 'MemoryDumpKind'. Getting rid of 'crash' was the main part but swapping 'Type' to 'Kind' I think aligns a little better with naming convention elsewhere. It seems fine to me either way. BCL API review is probably much better than I on these little naming choice details so we can use whatever they suggest.
• Simplified the method to 'Write' since MemoryDump was now in the type name.
• Removed heap as the default dump kind. With 'Normal' as one of the named options it seemed odd to have a default that wasn't Normal. Given the significant size differences and capability differences between some of the options it also seemed better to force callers to consider what they want.
• Added note about throwing NotSupportedException. Given the potentially large size and complexity of the native code needed to produce the memory dumps I expect we'll always have some apps/runtime implementations that don't include it. The exact situations where that occurs might evolve over time but we don't need to anticipate the reasons, just the possibility.

FatalErrorHandler extension

For the error handling part we could shift this to be an extension to the existing FatalErrorHandler feature rather than a managed API. The managed API is easier to use if its functionality is exactly what you want, but the FatalErrorHandler native callback seems more likely to handle variations in behavior that makes it useful for a broader set of .NET developers.

struct FatalErrorInfo
{
    // An entry point for writing a memory dump.
    // There is no mechanism to report errors at the moment other than observing if the file is present.
    // We could add a BOOL or some other error return type but I don't know how useful it would wind up
    // being as its not clear what you could do about it.
    // For runtimes that don't support dump writing the function does nothing
    // TBD - any other configuration we want here?
    void (DOTNET_CALLCONV *pfnWriteMemoryDump)(char8_t* dumpPath, MemoryDumpKind kind);

    // TBD: do we want this?
    // TRUE if calling pfnWriteMemoryDump is actually going to do something. Maybe the fatal error handler
    // wants to distinguish "expected crash dump failed to be written" vs. "this app doesn't support crash
    // dumps"
    bool isMemoryDumpSupported;
};

enum MemoryDumpKind
{
    Normal = 1,
    Heap = 2,
    Triage = 3,
    Full = 4,
}

Logistically it might be easier to narrow this issue to only cover the managed MemoryDump.Write API. @lateralusX @AaronRobinsonMSFT - for the native part of this suggestion do you think it makes sense to fold it back into the proposal at #101560 or keep it as a distinct separate addition? It felt pretty well aligned to me.

[lateralusX]

I don't think the proposals are conflicting but covers different scenarios. If the original need was to do something in responses to a fatal error (when runtime is terminating), then it should be done along the lines of #129543 and #131959, extending capabilities in the callback API to generate this kind out diagnostic output data, callable from native fatal error handler.

Personally, I believe it would be a good start to get the fatal error handler API merged with the on-demand in-proc crash reporter callbacks. Once that lands, extend the DiagnosticDataConfig with a version that support calls to createdump + all needed arguments (much more flexibility than going through env vars and different calls can have different args). Then it's up to the implementor of the native fatal error handler to control exactly how things will be configured and called. There is no need to enable crash reporting through env vars, when a native fatal error handler gets registered it will be called when runtime hits a fatal error. Since everything happens in native code, it has also less conflict with current runtime state (that could be corrupted) and running createdump is mainly packaging up the arguments and run the external process, implemented through the call to DiagnosticDataFunc. The complete logic will be controlled by the custom fatal error handler, so it's free to do whatever needed in response to the fatal error, including terminating the process when done.

@xen2, do you believe going down the path of a fatal error handler + ability to call createdump through the DiagnosticDataFunc callback would give you the functionality you need? Since you programmatically call the DiagnosticDataFunc with a specific CreateDumpConfig, you don't rely on any env variables, and you will be free to pass along needed arguments specific to that call. That would give you much more control than going over env variables and there is no need to enable/disable the functionality, it's always available while being inside the fatal error handler callback. If you think that would cover you use case, then we should focus on that first and put this API proposal on hold.