feat: Allow users to control Mechanism.Handled for captured exceptions

[vladbrincoveanu]

Closes #3383

Implements the approach agreed in this comment: SDK users get explicit control over Mechanism.Handled, and manually captured exceptions default to handled: true.

API changes

New overloads for explicit control:

• SentrySdk.CaptureException(Exception exception, bool handled)
• SentrySdk.CaptureException(Exception exception, Action<Scope> configureScope, bool handled)
• SentryClientExtensions.CaptureException(this ISentryClient client, Exception ex, bool handled)
• HubExtensions.CaptureException(this IHub hub, Exception ex, Action<Scope> configureScope, bool handled)

The existing signatures are kept, so this is source- and binary-compatible. handled is a required parameter rather than optional: an optional one would be permanently shadowed by the existing exact-match overloads, and replacing those signatures would be binary-breaking.

Behavior

• Explicit wins. Passing handled records that value, overriding any flag previously set on the exception (including via SetSentryMechanism).
• The existing overloads are untouched. They write nothing to Exception.Data, so there is no implicit precedence between a preset flag and a plain CaptureException(ex) call.
• The default moved into MainExceptionProcessor. Any exception no integration claimed is now marked handled: true, replacing the previous "thrown ⇒ true, never thrown ⇒ null" heuristic. This is what fixes the symptom Allow SDK users to control Mechanism.Handled for captured exceptions #3383 opens with: SentrySdk.CaptureException(new Exception()) reported Handled -- and now reports Handled: true, per the protocol docs ("exceptions captured using capture_exception are handled=true"), which are cited at the decision site. Thrown-and-caught exceptions reported Handled: true before and still do.
• CaptureExceptionInternal (the integration capture path) stamps handled: false, since integrations capture exceptions that user code did not handle.
• Terminal semantics are unchanged. See the discussion below on terminal control for user captures and on the WinUI integration, both are proposed as follow-ups rather than expanding this PR's scope.

Testing

Unit tests cover explicit true/false on every capture path, explicit values overriding preset flags, the untouched plain overloads, and the integration-path default. Verify snapshots updated: API approvals for all four target frameworks, the aggregate-exception mechanism snapshot, and the Sentry.DiagnosticSource / Sentry.EntityFramework integration snapshots, where constructed-and-captured exceptions now report Handled: true.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 74.64%. Comparing base (6516897) to head (3663ee5).

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #5449      +/-   ##
==========================================
+ Coverage   74.62%   74.64%   +0.02%     
==========================================
  Files         512      512              
  Lines       18672    18680       +8     
  Branches     3657     3658       +1     
==========================================
+ Hits        13934    13944      +10     
+ Misses       3865     3863       -2     
  Partials      873      873              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[vladbrincoveanu]

We have a warden failing check.
Could you please have a look @jamescrosswell ?
Warden cannot review this fork pull request because GitHub withholds repository secrets from fork workflows
Thanks.

[cursor]

Unhandled capture crashes sessions

High Severity

Public CaptureException with handled: false stamps only Mechanism.HandledKey and leaves Terminal unset. Session logic treats unhandled-with-unset-terminal as UnhandledTerminal, so a manual capture ends the session as Crashed and aborts the active transaction even though the process kept running.

Additional Locations (1)

• src/Sentry/HubExtensions.cs#L287-L297

 

^{Reviewed by Cursor Bugbot for commit 5e8b0b1. Configure here.}

[vladbrincoveanu]

Confirmed, this is the current behavior: handled: false stamps only Mechanism.HandledKey and leaves Terminal unset. A genuinely unhandled exception (e.g. AppDomain.UnhandledException) sets handled: false with no terminal flag, which counts as a Crash (see SentryEvent.HasUnhandledTerminalException).

Adding terminal control to the CaptureException signature (defaulting Terminal = false for user-parameter captures) would expand the API surface beyond what #3383 asks for, so I kept it out of this PR , but happy to open a follow-up issue for it, if you think the session-crash default is too surprising for manual captures. What do you think? @jamescrosswell

(The related WinUI issue CaptureExceptionInternal overwriting the platform-forwarded Handled flag, has since been fixed in 3663ee5; only the session-terminal question above remains open.)

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

There are 2 total unresolved issues (including 1 from previous review).

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit 1d662b6. Configure here.}