Skip to content

Add crash report support to the CrashDump extension #8191

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Copilot wants to merge 7 commits into
base: main
Choose a base branch
from
Open

Add crash report support to the CrashDump extension #8191

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
fa259c4
Initial plan
Copilot May 13, 2026
b904e02
Add crash report support to crash dump extension
Copilot May 13, 2026
8882424
Merge branch 'main' into copilot/feature-generate-crash-report
Evangelink May 14, 2026
142367b
Fix CLI option ordering in HelpInfoAllExtensionsTests and tighten Cra…
May 14, 2026
a8755ad
Revert auxiliary CrashDump refactoring
May 14, 2026
e8b4818
Address PR review comments
May 14, 2026
d68feac
Address CrashDump review comments
Copilot May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions src/Platform/Microsoft.Testing.Extensions.CrashDump/CrashDumpCommandLineOptions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@ namespace Microsoft.Testing.Extensions.Diagnostics;
internal static class CrashDumpCommandLineOptions
{
public const string CrashDumpOptionName = "crashdump";
public const string CrashReportOptionName = "crashreport";
public const string CrashReportOnlyOptionName = "crashreport-only";
public const string CrashDumpFileNameOptionName = "crashdump-filename";
public const string CrashDumpTypeOptionName = "crashdump-type";
}
35 changes: 27 additions & 8 deletions src/Platform/Microsoft.Testing.Extensions.CrashDump/CrashDumpCommandLineProvider.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,14 @@ namespace Microsoft.Testing.Extensions.Diagnostics;
internal sealed class CrashDumpCommandLineProvider : ICommandLineOptionsProvider
{
private static readonly string[] DumpTypeOptions = ["Mini", "Heap", "Triage", "Full"];
private static readonly IReadOnlyCollection<CommandLineOption> CachedCommandLineOptions =
[
new(CrashDumpCommandLineOptions.CrashDumpOptionName, CrashDumpResources.CrashDumpOptionDescription, ArgumentArity.Zero, false),
new(CrashDumpCommandLineOptions.CrashReportOptionName, CrashDumpResources.CrashReportOptionDescription, ArgumentArity.Zero, false),
new(CrashDumpCommandLineOptions.CrashReportOnlyOptionName, CrashDumpResources.CrashReportOnlyOptionDescription, ArgumentArity.Zero, false),
new(CrashDumpCommandLineOptions.CrashDumpFileNameOptionName, CrashDumpResources.CrashDumpFileNameOptionDescription, ArgumentArity.ExactlyOne, false),
new(CrashDumpCommandLineOptions.CrashDumpTypeOptionName, CrashDumpResources.CrashDumpTypeOptionDescription, ArgumentArity.ExactlyOne, false)
];

public string Uid => nameof(CrashDumpCommandLineProvider);

Expand All @@ -22,13 +30,7 @@ internal sealed class CrashDumpCommandLineProvider : ICommandLineOptionsProvider

public Task<bool> IsEnabledAsync() => Task.FromResult(true);

public IReadOnlyCollection<CommandLineOption> GetCommandLineOptions()
=>
[
new CommandLineOption(CrashDumpCommandLineOptions.CrashDumpOptionName, CrashDumpResources.CrashDumpOptionDescription, ArgumentArity.Zero, false),
new CommandLineOption(CrashDumpCommandLineOptions.CrashDumpFileNameOptionName, CrashDumpResources.CrashDumpFileNameOptionDescription, ArgumentArity.ExactlyOne, false),
new CommandLineOption(CrashDumpCommandLineOptions.CrashDumpTypeOptionName, CrashDumpResources.CrashDumpTypeOptionDescription, ArgumentArity.ExactlyOne, false)
];
public IReadOnlyCollection<CommandLineOption> GetCommandLineOptions() => CachedCommandLineOptions;

public Task<ValidationResult> ValidateOptionArgumentsAsync(CommandLineOption commandOption, string[] arguments)
{
Expand All @@ -45,5 +47,22 @@ public Task<ValidationResult> ValidateOptionArgumentsAsync(CommandLineOption com
}

public Task<ValidationResult> ValidateCommandLineOptionsAsync(ICommandLineOptions commandLineOptions)
=> ValidationResult.ValidTask;
{
bool isCrashDumpSet = commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashDumpOptionName);
bool isCrashReportSet = commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOptionName);
bool isCrashReportOnlySet = commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOnlyOptionName);

if (isCrashReportOnlySet && (isCrashDumpSet || isCrashReportSet))
{
return ValidationResult.InvalidTask(CrashDumpResources.CrashReportOnlyCannotBeCombinedErrorMessage);
}

if (isCrashReportSet && !isCrashDumpSet)
{
return ValidationResult.InvalidTask(CrashDumpResources.CrashReportRequiresCrashDumpErrorMessage);
}

// No problem found
return ValidationResult.ValidTask;
}
}
86 changes: 62 additions & 24 deletions src/Platform/Microsoft.Testing.Extensions.CrashDump/CrashDumpEnvironmentVariableProvider.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
// Copyright (c) Microsoft Corporation. All rights reserved.
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT license. See LICENSE file in the project root for full license information.

using Microsoft.Testing.Extensions.Diagnostics.Resources;
Expand All @@ -18,7 +18,9 @@ internal sealed class CrashDumpEnvironmentVariableProvider : ITestHostEnvironmen
private const string MiniDumpNameVariable = "DbgMiniDumpName";
private const string CreateDumpDiagnosticsVariable = "CreateDumpDiagnostics";
private const string CreateDumpVerboseDiagnosticsVariable = "CreateDumpVerboseDiagnostics";
private const string EnableMiniDumpValue = "1";
private const string EnableCrashReportVariable = "EnableCrashReport";
private const string EnableCrashReportOnlyVariable = "EnableCrashReportOnly";
private const string EnabledValue = "1";

private static readonly string[] Prefixes = ["DOTNET_", "COMPlus_"];
private readonly IConfiguration _configuration;
Expand Down Expand Up @@ -54,15 +56,46 @@ public CrashDumpEnvironmentVariableProvider(

/// <inheritdoc />
public Task<bool> IsEnabledAsync()
=> Task.FromResult(_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashDumpOptionName) && _crashDumpGeneratorConfiguration.Enable);
=> Task.FromResult(
(_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashDumpOptionName) ||
_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOptionName) ||
_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOnlyOptionName)) &&
_crashDumpGeneratorConfiguration.Enable);

public Task UpdateAsync(IEnvironmentVariables environmentVariables)
{
bool crashDumpEnabled = _commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashDumpOptionName);
bool crashReportEnabled = _commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOptionName);
bool crashReportOnlyEnabled = _commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOnlyOptionName);

if (crashDumpEnabled || crashReportEnabled || crashReportOnlyEnabled)
{
foreach (string prefix in Prefixes)
{
environmentVariables.SetVariable(new($"{prefix}{EnableMiniDumpVariable}", EnabledValue, false, true));
}
}

foreach (string prefix in Prefixes)
{
environmentVariables.SetVariable(new($"{prefix}{EnableMiniDumpVariable}", EnableMiniDumpValue, false, true));
environmentVariables.SetVariable(new($"{prefix}{CreateDumpDiagnosticsVariable}", EnableMiniDumpValue, false, true));
environmentVariables.SetVariable(new($"{prefix}{CreateDumpVerboseDiagnosticsVariable}", EnableMiniDumpValue, false, true));
environmentVariables.SetVariable(new($"{prefix}{CreateDumpDiagnosticsVariable}", EnabledValue, false, true));
environmentVariables.SetVariable(new($"{prefix}{CreateDumpVerboseDiagnosticsVariable}", EnabledValue, false, true));
}

if (crashReportEnabled)
{
foreach (string prefix in Prefixes)
{
environmentVariables.SetVariable(new($"{prefix}{EnableCrashReportVariable}", EnabledValue, false, true));
}
}
Comment on lines +85 to +91

if (crashReportOnlyEnabled)
{
foreach (string prefix in Prefixes)
{
environmentVariables.SetVariable(new($"{prefix}{EnableCrashReportOnlyVariable}", EnabledValue, false, true));
}
}
Comment on lines +85 to +99
Copy link
Copy Markdown
Member

@Evangelink Evangelink May 14, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done in e8b4818. Renamed EnableMiniDumpValue to the neutral EnabledValue since it's now also used for DOTNET_EnableCrashReport and DOTNET_EnableCrashReportOnly.


string miniDumpTypeValue = "4";
Expand Down Expand Up @@ -133,31 +166,24 @@ public Task<ValidationResult> ValidateTestHostEnvironmentVariablesAsync(IReadOnl
return ValidationResult.InvalidTask(CrashDumpResources.CrashDumpNotSupportedInNonNetCoreErrorMessage);
#else
StringBuilder errors = new();
foreach (string prefix in Prefixes)
if (_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashDumpOptionName) ||
_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOptionName) ||
_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOnlyOptionName))
{
if (!environmentVariables.TryGetVariable($"{prefix}{EnableMiniDumpVariable}", out OwnedEnvironmentVariable? enableMiniDump)
|| enableMiniDump.Value != EnableMiniDumpValue)
{
AddError(errors, $"{prefix}{EnableMiniDumpVariable}", EnableMiniDumpValue, enableMiniDump?.Value);
}
ValidateBothPrefixes(EnableMiniDumpVariable, EnabledValue);
}

foreach (string prefix in Prefixes)
ValidateBothPrefixes(CreateDumpDiagnosticsVariable, EnabledValue);
ValidateBothPrefixes(CreateDumpVerboseDiagnosticsVariable, EnabledValue);

if (_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOptionName))
{
if (!environmentVariables.TryGetVariable($"{prefix}{CreateDumpDiagnosticsVariable}", out OwnedEnvironmentVariable? enableMiniDump)
|| enableMiniDump.Value != EnableMiniDumpValue)
{
AddError(errors, $"{prefix}{CreateDumpDiagnosticsVariable}", EnableMiniDumpValue, enableMiniDump?.Value);
}
ValidateBothPrefixes(EnableCrashReportVariable, EnabledValue);
}

foreach (string prefix in Prefixes)
if (_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOnlyOptionName))
{
if (!environmentVariables.TryGetVariable($"{prefix}{CreateDumpVerboseDiagnosticsVariable}", out OwnedEnvironmentVariable? enableMiniDump)
|| enableMiniDump.Value != EnableMiniDumpValue)
{
AddError(errors, $"{prefix}{CreateDumpVerboseDiagnosticsVariable}", EnableMiniDumpValue, enableMiniDump?.Value);
}
ValidateBothPrefixes(EnableCrashReportOnlyVariable, EnabledValue);
}

foreach (string prefix in Prefixes)
Expand Down Expand Up @@ -199,6 +225,18 @@ static void AddError(StringBuilder errors, string variableName, string? expected
string actualValueString = actualValue ?? "<null>";
errors.AppendLine(string.Format(CultureInfo.InvariantCulture, CrashDumpResources.CrashDumpInvalidEnvironmentVariableValueErrorMessage, variableName, expectedValue, actualValueString));
}

void ValidateBothPrefixes(string variableName, string expectedValue)
{
foreach (string prefix in Prefixes)
{
if (!environmentVariables.TryGetVariable($"{prefix}{variableName}", out OwnedEnvironmentVariable? variable)
|| variable.Value != expectedValue)
{
AddError(errors, $"{prefix}{variableName}", expectedValue, variable?.Value);
}
}
}
#endif
}
}
53 changes: 44 additions & 9 deletions src/Platform/Microsoft.Testing.Extensions.CrashDump/CrashDumpProcessLifetimeHandler.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ namespace Microsoft.Testing.Extensions.Diagnostics;

internal sealed class CrashDumpProcessLifetimeHandler : ITestHostProcessLifetimeHandler, IDataProducer, IOutputDeviceDataProducer
{
private const string CrashReportFileExtension = ".crashreport.json";
private const string CrashReportFileSearchPattern = "*" + CrashReportFileExtension;

private readonly ICommandLineOptions _commandLineOptions;
private readonly IMessageBus _messageBus;
private readonly IOutputDevice _outputDisplay;
Expand Down Expand Up @@ -46,8 +49,11 @@ public CrashDumpProcessLifetimeHandler(
public Type[] DataTypesProduced => [typeof(FileArtifact)];

public Task<bool> IsEnabledAsync()
=> Task.FromResult(_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashDumpOptionName)
&& _netCoreCrashDumpGeneratorConfiguration.Enable);
=> Task.FromResult(
(_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashDumpOptionName) ||
_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOptionName) ||
_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOnlyOptionName)) &&
_netCoreCrashDumpGeneratorConfiguration.Enable);

public Task BeforeTestHostProcessStartAsync(CancellationToken _) => Task.CompletedTask;

Expand All @@ -63,22 +69,51 @@ public async Task OnTestHostProcessExitedAsync(ITestHostProcessInformation testH
}

ApplicationStateGuard.Ensure(_netCoreCrashDumpGeneratorConfiguration.DumpFileNamePattern is not null);
await _outputDisplay.DisplayAsync(this, new ErrorMessageOutputDeviceData(string.Format(CultureInfo.InvariantCulture, CrashDumpResources.CrashDumpProcessCrashedDumpFileCreated, testHostProcessInformation.PID)), cancellationToken).ConfigureAwait(false);
bool generateDump = _commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashDumpOptionName);
bool generateCrashReport = _commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOptionName) ||
_commandLineOptions.IsOptionSet(CrashDumpCommandLineOptions.CrashReportOnlyOptionName);

string processCrashedMessage = generateDump && generateCrashReport
? string.Format(CultureInfo.InvariantCulture, CrashDumpResources.CrashDumpProcessCrashedDumpAndReportFileCreated, testHostProcessInformation.PID)
: generateCrashReport
? string.Format(CultureInfo.InvariantCulture, CrashDumpResources.CrashDumpProcessCrashedReportFileCreated, testHostProcessInformation.PID)
: string.Format(CultureInfo.InvariantCulture, CrashDumpResources.CrashDumpProcessCrashedDumpFileCreated, testHostProcessInformation.PID);
await _outputDisplay.DisplayAsync(this, new ErrorMessageOutputDeviceData(processCrashedMessage), cancellationToken).ConfigureAwait(false);

// TODO: Crash dump supports more placeholders that we don't handle here.
// See "Dump name formatting" in:
// https://github.com/dotnet/runtime/blob/82742628310076fff22d7e7ee216a74384352056/docs/design/coreclr/botr/xplat-minidump-generation.md
string expectedDumpFile = _netCoreCrashDumpGeneratorConfiguration.DumpFileNamePattern.Replace("%p", testHostProcessInformation.PID.ToString(CultureInfo.InvariantCulture));
if (File.Exists(expectedDumpFile))
if (generateDump)
{
await _messageBus.PublishAsync(this, new FileArtifact(new FileInfo(expectedDumpFile), CrashDumpResources.CrashDumpArtifactDisplayName, CrashDumpResources.CrashDumpArtifactDescription)).ConfigureAwait(false);
if (File.Exists(expectedDumpFile))
{
await _messageBus.PublishAsync(this, new FileArtifact(new FileInfo(expectedDumpFile), CrashDumpResources.CrashDumpArtifactDisplayName, CrashDumpResources.CrashDumpArtifactDescription)).ConfigureAwait(false);
}
else
{
await _outputDisplay.DisplayAsync(this, new ErrorMessageOutputDeviceData(string.Format(CultureInfo.InvariantCulture, CrashDumpResources.CannotFindExpectedCrashDumpFile, expectedDumpFile)), cancellationToken).ConfigureAwait(false);
foreach (string dumpFile in Directory.GetFiles(Path.GetDirectoryName(expectedDumpFile)!, "*.dmp"))
{
await _messageBus.PublishAsync(this, new FileArtifact(new FileInfo(dumpFile), CrashDumpResources.CrashDumpDisplayName, CrashDumpResources.CrashDumpArtifactDescription)).ConfigureAwait(false);
}
}
}
else

if (generateCrashReport)
{
await _outputDisplay.DisplayAsync(this, new ErrorMessageOutputDeviceData(string.Format(CultureInfo.InvariantCulture, CrashDumpResources.CannotFindExpectedCrashDumpFile, expectedDumpFile)), cancellationToken).ConfigureAwait(false);
foreach (string dumpFile in Directory.GetFiles(Path.GetDirectoryName(expectedDumpFile)!, "*.dmp"))
string expectedCrashReportFile = $"{expectedDumpFile}{CrashReportFileExtension}";
if (File.Exists(expectedCrashReportFile))
{
await _messageBus.PublishAsync(this, new FileArtifact(new FileInfo(expectedCrashReportFile), CrashDumpResources.CrashReportArtifactDisplayName, CrashDumpResources.CrashReportArtifactDescription)).ConfigureAwait(false);
}
else
{
await _messageBus.PublishAsync(this, new FileArtifact(new FileInfo(dumpFile), CrashDumpResources.CrashDumpDisplayName, CrashDumpResources.CrashDumpArtifactDescription)).ConfigureAwait(false);
await _outputDisplay.DisplayAsync(this, new ErrorMessageOutputDeviceData(string.Format(CultureInfo.InvariantCulture, CrashDumpResources.CannotFindExpectedCrashReportFile, expectedCrashReportFile, CrashReportFileSearchPattern)), cancellationToken).ConfigureAwait(false);
foreach (string crashReportFile in Directory.GetFiles(Path.GetDirectoryName(expectedCrashReportFile)!, CrashReportFileSearchPattern))
{
await _messageBus.PublishAsync(this, new FileArtifact(new FileInfo(crashReportFile), CrashDumpResources.CrashReportArtifactDisplayName, CrashDumpResources.CrashReportArtifactDescription)).ConfigureAwait(false);
}
}
}
}
Expand Down
4 changes: 3 additions & 1 deletion src/Platform/Microsoft.Testing.Extensions.CrashDump/PACKAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Microsoft.Testing.Extensions.CrashDump

Microsoft.Testing.Extensions.CrashDump is an extension for [Microsoft.Testing.Platform](https://www.nuget.org/packages/Microsoft.Testing.Platform) that captures a crash dump of the test host process when an unhandled exception or crash occurs.
Microsoft.Testing.Extensions.CrashDump is an extension for [Microsoft.Testing.Platform](https://www.nuget.org/packages/Microsoft.Testing.Platform) that captures a crash dump or crash report for the test host process when an unhandled exception or crash occurs.

Microsoft.Testing.Platform is open source. You can find `Microsoft.Testing.Extensions.CrashDump` code in the [microsoft/testfx](https://github.com/microsoft/testfx) GitHub repository.

Expand All @@ -15,11 +15,13 @@ dotnet add package Microsoft.Testing.Extensions.CrashDump
This package extends Microsoft.Testing.Platform with:

- **Crash dump collection**: automatically captures a memory dump when the test process crashes
- **Crash report collection**: optionally emits a lightweight JSON crash report to help diagnose crashes without uploading a full dump
- **Post-mortem debugging**: collected dumps can be analyzed with tools like Visual Studio, WinDbg, or `dotnet-dump`
- **Cross-platform**: supported on Windows, Linux, and macOS. Note that dumps collected on macOS can only be analyzed on macOS
- **Runtime behavior**: supported for .NET 6+; on .NET Framework this extension is ignored

Enable crash dump collection via the `--crashdump` command line option.
Add `--crashreport` to generate a dump and crash report together, or use `--crashreport-only` to generate only the crash report.

## Related packages

Expand Down
Loading
Loading