Rules for `--blame`, `--blame-crash`, and `--blame-hang-timeout` in dotnet test

The --blame flag is only valid for VSTest projects, while Microsoft Testing Platform (MTP) requires --blame-crash and --blame-hang-timeout with specific extension packages, and SDK versions 8/9 require a -- separator before MTP arguments that becomes optional in SDK 10+.

The dotnet/skills repository maintains strict validation rules for crash and hang dump collection across .NET test platforms. Understanding when to use --blame, --blame-crash, and --blame-hang-timeout depends on whether your project runs on the classic VSTest runner or the newer Microsoft Testing Platform (MTP), as well as your .NET SDK version. These rules are enforced in the automated evaluation suites and documented in the run-tests skill files.

Understanding the Two Test Runners

The .NET ecosystem supports two distinct test runners with incompatible flag sets. VSTest (the classic runner backed by Microsoft.NET.Testest.Sdk) accepts --blame, --blame-crash, and --blame-hang-timeout directly as part of its command line. Microsoft Testing Platform (MTP)—the newer extensible runner introduced in .NET 8/9 and default on .NET 10+—replaces these with extension-driven flags and has specific separator requirements based on SDK version.

According to the validation scenarios in tests/dotnet-test/run-tests/eval.yaml, the critical distinction is that VSTest flags never require a -- separator, while MTP flags on SDK 8/9 must follow one. The SDK version determines whether the separator is mandatory or optional.

Why --blame Is Invalid for Microsoft Testing Platform

The --blame flag is VSTest-specific and tells the VSTest host to generate a crash dump when the test process crashes. MTP replaces this behavior with two separate, extension-driven flags.

As explicitly documented in plugins/dotnet-test/skills/run-tests/SKILL.md (lines 59-64), you must not use --blame for MTP projects. Instead, MTP requires:

• --blame-crash – collects a crash dump (requires Microsoft.Testing.Extensions.CrashDump)
• --blame-hang-timeout <duration> – aborts hanging tests after the specified timespan (requires Microsoft.Testing.Extensions.HangDump)

The same prohibition appears in the test validation YAML at tests/dotnet-test/run-tests/eval.yaml (lines 58-63), where using --blame with MTP triggers a validation failure.

SDK Version Separator Rules

The syntax for passing arguments to dotnet test changes based on your SDK version when using MTP.

SDK 8 or 9: MTP arguments must follow a -- separator. This is strictly enforced by the validation suite in tests/dotnet-test/run-tests/eval.yaml (lines 99-105), which checks that flags like --blame-crash appear after the separator.

SDK 10+: The global.json "runner" setting ("test": { "runner": "Microsoft.Testing.Platform" }) signals that the SDK understands MTP arguments natively. Consequently, the separator is omitted. The validation in tests/dotnet-test/run-tests/eval.yaml (lines 29-35) confirms that SDK 10+ passes arguments directly without the -- separator.

Required Extension Packages for MTP

Unlike VSTest, MTP requires explicit package references to enable crash and hang dump functionality. If a flag is reported as "unrecognized," the skill's troubleshooting table in plugins/dotnet-test/skills/run-tests/SKILL.md (lines 278-283) advises adding the missing package.

Flag	Required Extension Package
--blame-crash	Microsoft.Testing.Extensions.CrashDump
--blame-hang-timeout	Microsoft.Testing.Extensions.HangDump
--report-trx	Microsoft.Testing.Extensions.TrxReport

Add these as <PackageReference> items in your project file when targeting MTP.

Implementation Examples

VSTest Configuration (Any SDK)

For VSTest projects, pass flags directly without separator concerns:

dotnet test --logger trx
dotnet test --blame
dotnet test --blame-crash
dotnet test --blame-hang-timeout 5min

MTP on SDK 8 and 9 (Separator Required)

When using the Microsoft Testing Platform on SDK 8 or 9, place all MTP-specific arguments after the -- separator:

dotnet test --project MyTests.csproj -- \
    --report-trx \
    --blame-crash \
    --blame-hang-timeout 5min

MTP on SDK 10 and Later (No Separator)

For SDK 10 and above, pass arguments directly to dotnet test without the separator:

dotnet test --project MyTests.csproj \
    --report-trx \
    --blame-crash \
    --blame-hang-timeout 5min

Detecting the Test Runner and SDK Version

Before selecting flags, determine which runner your project uses. Check for TestingPlatformDotnetTestSupport in the .csproj or Directory.Build.props file, or look for a "test": { "runner": "Microsoft.Testing.Platform" } entry in global.json.

Verify your SDK version with dotnet --version or check the sdk.version property in global.json. This detection step prevents the "unrecognized option" errors that occur when using VSTest flags on MTP projects or omitting the separator on SDK 8/9.

Summary

• VSTest supports --blame, --blame-crash, and --blame-hang-timeout directly without separators.
• MTP requires --blame-crash and --blame-hang-timeout but explicitly prohibits --blame according to plugins/dotnet-test/skills/run-tests/SKILL.md.
• SDK 8/9 requires a -- separator before MTP arguments, while SDK 10+ passes them directly.
• Extension packages (Microsoft.Testing.Extensions.CrashDump, Microsoft.Testing.Extensions.HangDump) are mandatory for MTP crash and hang dump functionality.
• The validation rules in tests/dotnet-test/run-tests/eval.yaml enforce these separator and flag-selection requirements across both SDK generations.

Frequently Asked Questions

Can I use --blame with Microsoft Testing Platform?

No. The --blame flag is specific to VSTest and is explicitly forbidden for MTP projects according to plugins/dotnet-test/skills/run-tests/SKILL.md (lines 59-64). For MTP, use --blame-crash with the Microsoft.Testing.Extensions.CrashDump package instead.

Why do I get "unrecognized option" errors with --blame-hang-timeout on MTP?

This error indicates the Microsoft.Testing.Extensions.HangDump package is missing from your project references. Unlike VSTest, MTP requires explicit extension packages for hang dump functionality. Add the package reference and rebuild before running the tests.

When should I use the -- separator with dotnet test?

Use the -- separator only when running Microsoft Testing Platform on SDK 8 or 9. This separator tells the SDK to pass subsequent arguments to the MTP runner rather than the dotnet test command itself. On SDK 10 and later, the separator is not required when the global.json specifies the Microsoft Testing Platform runner.

How do I migrate VSTest --blame flags to MTP?

According to plugins/dotnet-test-migration/skills/migrate-vstest-to-mtp/SKILL.md, map VSTest's --blame to MTP's --crashdump, VSTest's --blame-crash to MTP's --crashdump, and VSTest's --blame-hang-timeout to MTP's --hangdump-timeout with the corresponding extension packages. Remove the --blame flag entirely, as it has no equivalent in the new platform.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}