refactor: move handled before configureScope and guard disabled hub

Addresses review feedback on #5449:
- reorder the scope-callback overloads to (ex, handled, configureScope)
  so a long lambda stays the last argument
- skip the Exception.Data mutation when the hub is disabled, matching
  SentryClientExtensions.CaptureException
- note that the CaptureExceptionInternal fallback is defensive only

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: vladbrincoveanu

src/Sentry/HubExtensions.cs

@@ -271,8 +271,8 @@ public LockedScope(IHub hub)
 
     internal static SentryId CaptureExceptionInternal(this IHub hub, Exception ex)
     {
-        // Integrations stamp the flag via SetSentryMechanism before calling this (e.g. WinUI forwards the
-        // platform's Handled value); only default to unhandled when nothing was declared.
+        // Integrations always call `SetSentryMechanism` before calling this method (e.g. WinUI forwards the
+        // platform's Handled value), so this fallback is defensive only. In practice, it never executes.
         if (!ex.Data.Contains(Mechanism.HandledKey))
         {
             ex.Data[Mechanism.HandledKey] = false;
@@ -295,12 +295,17 @@ public static SentryId CaptureException(this IHub hub, Exception ex, Action<Scop
     /// </summary>
     /// <param name="hub">The Sentry hub.</param>
     /// <param name="ex">The exception.</param>
-    /// <param name="configureScope">The callback to configure the scope.</param>
     /// <param name="handled">Whether the exception was handled. Recorded on the exception, overriding any flag
     /// previously set on it, including one set via <see cref="SentryExceptionExtensions.SetSentryMechanism"/>.</param>
+    /// <param name="configureScope">The callback to configure the scope.</param>
     /// <returns>The Id of the event</returns>
-    public static SentryId CaptureException(this IHub hub, Exception ex, Action<Scope> configureScope, bool handled)
+    public static SentryId CaptureException(this IHub hub, Exception ex, bool handled, Action<Scope> configureScope)
     {
+        if (!hub.IsEnabled)
+        {
+            return SentryId.Empty;
+        }
+
         ex.Data[Mechanism.HandledKey] = handled;
         return hub.CaptureEvent(new SentryEvent(ex), configureScope);
     }

src/Sentry/SentrySdk.cs

@@ -555,13 +555,13 @@ public static SentryId CaptureException(Exception exception, Action<Scope> confi
     /// This allows modifying a scope without affecting other events.
     /// </remarks>
     /// <param name="exception">The exception.</param>
-    /// <param name="configureScope">The callback to configure the scope.</param>
     /// <param name="handled">Whether the exception was handled. Recorded on the exception, overriding any flag
     /// previously set on it, including one set via <see cref="SentryExceptionExtensions.SetSentryMechanism"/>.</param>
+    /// <param name="configureScope">The callback to configure the scope.</param>
     /// <returns>The Id of the event.</returns>
     [DebuggerStepThrough]
-    public static SentryId CaptureException(Exception exception, Action<Scope> configureScope, bool handled)
-        => CurrentHub.CaptureException(exception, configureScope, handled);
+    public static SentryId CaptureException(Exception exception, bool handled, Action<Scope> configureScope)
+        => CurrentHub.CaptureException(exception, handled, configureScope);
 
     /// <summary>
     /// Captures the message.

test/Sentry.Tests/ApiApprovalTests.Run.DotNet10_0.verified.txt

@@ -148,7 +148,7 @@ namespace Sentry
         public static void AddBreadcrumb(this Sentry.IHub hub, string message, string? category = null, string? type = null, System.Collections.Generic.IDictionary<string, string>? data = null, Sentry.BreadcrumbLevel level = 0) { }
         public static void AddBreadcrumb(this Sentry.IHub hub, Sentry.Infrastructure.ISystemClock? clock, string message, string? category = null, string? type = null, System.Collections.Generic.IDictionary<string, string>? data = null, Sentry.BreadcrumbLevel level = 0) { }
         public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, System.Action<Sentry.Scope> configureScope) { }
-        public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, System.Action<Sentry.Scope> configureScope, bool handled) { }
+        public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, bool handled, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureFeedback(this Sentry.IHub hub, Sentry.SentryFeedback feedback, System.Action<Sentry.Scope> configureScope, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureMessage(this Sentry.IHub hub, string message, System.Action<Sentry.Scope> configureScope, Sentry.SentryLevel level = 1) { }
         public static void LockScope(this Sentry.IHub hub) { }
@@ -981,7 +981,7 @@ namespace Sentry
         public static Sentry.SentryId CaptureException(System.Exception exception) { }
         public static Sentry.SentryId CaptureException(System.Exception exception, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureException(System.Exception exception, bool handled) { }
-        public static Sentry.SentryId CaptureException(System.Exception exception, System.Action<Sentry.Scope> configureScope, bool handled) { }
+        public static Sentry.SentryId CaptureException(System.Exception exception, bool handled, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, Sentry.Scope? scope = null, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, System.Action<Sentry.Scope> configureScope, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, out Sentry.CaptureFeedbackResult result, Sentry.Scope? scope = null, Sentry.SentryHint? hint = null) { }

test/Sentry.Tests/ApiApprovalTests.Run.DotNet8_0.verified.txt

@@ -148,7 +148,7 @@ namespace Sentry
         public static void AddBreadcrumb(this Sentry.IHub hub, string message, string? category = null, string? type = null, System.Collections.Generic.IDictionary<string, string>? data = null, Sentry.BreadcrumbLevel level = 0) { }
         public static void AddBreadcrumb(this Sentry.IHub hub, Sentry.Infrastructure.ISystemClock? clock, string message, string? category = null, string? type = null, System.Collections.Generic.IDictionary<string, string>? data = null, Sentry.BreadcrumbLevel level = 0) { }
         public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, System.Action<Sentry.Scope> configureScope) { }
-        public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, System.Action<Sentry.Scope> configureScope, bool handled) { }
+        public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, bool handled, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureFeedback(this Sentry.IHub hub, Sentry.SentryFeedback feedback, System.Action<Sentry.Scope> configureScope, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureMessage(this Sentry.IHub hub, string message, System.Action<Sentry.Scope> configureScope, Sentry.SentryLevel level = 1) { }
         public static void LockScope(this Sentry.IHub hub) { }
@@ -981,7 +981,7 @@ namespace Sentry
         public static Sentry.SentryId CaptureException(System.Exception exception) { }
         public static Sentry.SentryId CaptureException(System.Exception exception, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureException(System.Exception exception, bool handled) { }
-        public static Sentry.SentryId CaptureException(System.Exception exception, System.Action<Sentry.Scope> configureScope, bool handled) { }
+        public static Sentry.SentryId CaptureException(System.Exception exception, bool handled, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, Sentry.Scope? scope = null, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, System.Action<Sentry.Scope> configureScope, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, out Sentry.CaptureFeedbackResult result, Sentry.Scope? scope = null, Sentry.SentryHint? hint = null) { }

test/Sentry.Tests/ApiApprovalTests.Run.DotNet9_0.verified.txt

@@ -148,7 +148,7 @@ namespace Sentry
         public static void AddBreadcrumb(this Sentry.IHub hub, string message, string? category = null, string? type = null, System.Collections.Generic.IDictionary<string, string>? data = null, Sentry.BreadcrumbLevel level = 0) { }
         public static void AddBreadcrumb(this Sentry.IHub hub, Sentry.Infrastructure.ISystemClock? clock, string message, string? category = null, string? type = null, System.Collections.Generic.IDictionary<string, string>? data = null, Sentry.BreadcrumbLevel level = 0) { }
         public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, System.Action<Sentry.Scope> configureScope) { }
-        public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, System.Action<Sentry.Scope> configureScope, bool handled) { }
+        public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, bool handled, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureFeedback(this Sentry.IHub hub, Sentry.SentryFeedback feedback, System.Action<Sentry.Scope> configureScope, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureMessage(this Sentry.IHub hub, string message, System.Action<Sentry.Scope> configureScope, Sentry.SentryLevel level = 1) { }
         public static void LockScope(this Sentry.IHub hub) { }
@@ -981,7 +981,7 @@ namespace Sentry
         public static Sentry.SentryId CaptureException(System.Exception exception) { }
         public static Sentry.SentryId CaptureException(System.Exception exception, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureException(System.Exception exception, bool handled) { }
-        public static Sentry.SentryId CaptureException(System.Exception exception, System.Action<Sentry.Scope> configureScope, bool handled) { }
+        public static Sentry.SentryId CaptureException(System.Exception exception, bool handled, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, Sentry.Scope? scope = null, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, System.Action<Sentry.Scope> configureScope, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, out Sentry.CaptureFeedbackResult result, Sentry.Scope? scope = null, Sentry.SentryHint? hint = null) { }

test/Sentry.Tests/ApiApprovalTests.Run.Net4_8.verified.txt

@@ -136,7 +136,7 @@ namespace Sentry
         public static void AddBreadcrumb(this Sentry.IHub hub, string message, string? category = null, string? type = null, System.Collections.Generic.IDictionary<string, string>? data = null, Sentry.BreadcrumbLevel level = 0) { }
         public static void AddBreadcrumb(this Sentry.IHub hub, Sentry.Infrastructure.ISystemClock? clock, string message, string? category = null, string? type = null, System.Collections.Generic.IDictionary<string, string>? data = null, Sentry.BreadcrumbLevel level = 0) { }
         public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, System.Action<Sentry.Scope> configureScope) { }
-        public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, System.Action<Sentry.Scope> configureScope, bool handled) { }
+        public static Sentry.SentryId CaptureException(this Sentry.IHub hub, System.Exception ex, bool handled, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureFeedback(this Sentry.IHub hub, Sentry.SentryFeedback feedback, System.Action<Sentry.Scope> configureScope, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureMessage(this Sentry.IHub hub, string message, System.Action<Sentry.Scope> configureScope, Sentry.SentryLevel level = 1) { }
         public static void LockScope(this Sentry.IHub hub) { }
@@ -962,7 +962,7 @@ namespace Sentry
         public static Sentry.SentryId CaptureException(System.Exception exception) { }
         public static Sentry.SentryId CaptureException(System.Exception exception, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureException(System.Exception exception, bool handled) { }
-        public static Sentry.SentryId CaptureException(System.Exception exception, System.Action<Sentry.Scope> configureScope, bool handled) { }
+        public static Sentry.SentryId CaptureException(System.Exception exception, bool handled, System.Action<Sentry.Scope> configureScope) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, Sentry.Scope? scope = null, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, System.Action<Sentry.Scope> configureScope, Sentry.SentryHint? hint = null) { }
         public static Sentry.SentryId CaptureFeedback(Sentry.SentryFeedback feedback, out Sentry.CaptureFeedbackResult result, Sentry.Scope? scope = null, Sentry.SentryHint? hint = null) { }

test/Sentry.Tests/HubExtensionsTests.cs

@@ -96,7 +96,7 @@ public void CaptureException_ScopeCallback_ExplicitHandled_RecordsFlagOnExceptio
         var ex = new Exception();
 
         // Act
-        _ = Sut.CaptureException(ex, _ => { }, handled);
+        _ = Sut.CaptureException(ex, handled, _ => { });
 
         // Assert
         Assert.Equal(handled, ex.Data[Mechanism.HandledKey]);
@@ -112,12 +112,28 @@ public void CaptureException_ScopeCallback_ExplicitHandled_OverridesFlagSetBySet
         ex.SetSentryMechanism("SomeMechanism", handled: true);
 
         // Act
-        _ = Sut.CaptureException(ex, _ => { }, handled: false);
+        _ = Sut.CaptureException(ex, handled: false, _ => { });
 
         // Assert
         Assert.Equal(false, ex.Data[Mechanism.HandledKey]);
     }
 
+    [Fact]
+    public void CaptureException_ScopeCallback_ExplicitHandled_DisabledHub_DoesNotRecordFlagOnException()
+    {
+        // Arrange
+        _ = Sut.IsEnabled.Returns(false);
+        var ex = new Exception();
+
+        // Act
+        var id = Sut.CaptureException(ex, handled: false, _ => { });
+
+        // Assert
+        Assert.Equal(SentryId.Empty, id);
+        Assert.False(ex.Data.Contains(Mechanism.HandledKey));
+        _ = Sut.DidNotReceive().CaptureEvent(Arg.Any<SentryEvent>(), Arg.Any<Action<Scope>>());
+    }
+
     [Fact]
     public void CaptureExceptionInternal_NoPresetFlag_DefaultsToUnhandled()
     {

test/Sentry.Tests/SentrySdkTests.cs

@@ -740,7 +740,7 @@ public void CaptureException_WithConfiguredScope_ExplicitHandled_SetsMechanismHa
             });
         });
 
-        SentrySdk.CaptureException(new Exception("test"), s => s.SetTag("scope-callback", "ran"), handled);
+        SentrySdk.CaptureException(new Exception("test"), handled, s => s.SetTag("scope-callback", "ran"));
 
         Assert.NotNull(captured);
         Assert.Equal(handled, Assert.Single(captured.SentryExceptions!).Mechanism!.Handled);