Added overloads to Capture methods to replace WithScope (#1412)

* replaced withscope with overloads

* added remarks

* restored 'WithScope'

* renamed 'configureScope' to 'scope'

* added obsolete attribute

* added tests

* obsolete message fix

* updated CHANGELOG.md

* updated CHANGELOG.md

* added ApiApprovalTests results

* added 2.1 ApiApproval

* fixed ambiguous test

* added test

* renamed 'scope' callback to 'configureScope'

* added obsolete info text

* updated the ApiApprovals

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ## Features
 
+- SentrySDK.WithScope is now obsolete in favour of overloads of CaptureEvent, CaptureMessage, CaptureException ([#1412](https://github.com/getsentry/sentry-dotnet/pull/1412))
 - Add Sentry to global usings when ImplicitUsings is enabled (`<ImplicitUsings>true</ImplicitUsings>`) ([#1398](https://github.com/getsentry/sentry-dotnet/pull/1398))
 
 ### Fixes

samples/Sentry.Samples.Console.Customized/Program.cs

@@ -131,16 +131,14 @@ await SentrySdk.ConfigureScopeAsync(async scope =>
             });
 
             // Configures a scope which is only valid within the callback
-            SentrySdk.WithScope(s =>
+            SentrySdk.CaptureMessage("Fatal message!", s =>
             {
                 s.Level = SentryLevel.Fatal;
                 s.TransactionName = "main";
                 s.Environment = "SpecialEnvironment";
 
                 // Add a file attachment for upload
                 s.AddAttachment(typeof(Program).Assembly.Location);
-
-                SentrySdk.CaptureMessage("Fatal message!");
             });
 
             var eventId = SentrySdk.CaptureMessage("Some warning!", SentryLevel.Warning);

src/Sentry/Extensibility/DisabledHub.cs

@@ -118,6 +118,11 @@ public void BindClient(ISentryClient client)
         /// </summary>
         public SentryId CaptureEvent(SentryEvent evt, Scope? scope = null) => SentryId.Empty;
 
+        /// <summary>
+        /// No-Op.
+        /// </summary>
+        public SentryId CaptureEvent(SentryEvent evt, Action<Scope> configureScope) => SentryId.Empty;
+
         /// <summary>
         /// No-Op.
         /// </summary>

src/Sentry/Extensibility/HubAdapter.cs

@@ -66,6 +66,8 @@ public IDisposable PushScope<TState>(TState state)
         /// <summary>
         /// Forwards the call to <see cref="SentrySdk"/>.
         /// </summary>
+        [Obsolete("This method is deprecated in favor of overloads of CaptureEvent, CaptureMessage and CaptureException " +
+                  "that provide a callback to a configurable scope.")]
         [DebuggerStepThrough]
         public void WithScope(Action<Scope> scopeCallback)
             => SentrySdk.WithScope(scopeCallback);
@@ -189,6 +191,14 @@ public SentryId CaptureException(Exception exception)
         public SentryId CaptureEvent(SentryEvent evt, Scope? scope)
             => SentrySdk.CaptureEvent(evt, scope);
 
+        /// <summary>
+        /// Forwards the call to <see cref="SentrySdk"/>.
+        /// </summary>
+        [DebuggerStepThrough]
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public SentryId CaptureEvent(SentryEvent evt, Action<Scope> configureScope)
+            => SentrySdk.CaptureEvent(evt, configureScope);
+
         /// <summary>
         /// Forwards the call to <see cref="SentrySdk"/>.
         /// </summary>

src/Sentry/HubExtensions.cs

@@ -157,5 +157,40 @@ public LockedScope(IHub hub)
 
             public void Dispose() => _scope.Dispose();
         }
+
+        /// <summary>
+        /// Captures the exception with a configurable scope callback.
+        /// </summary>
+        /// <param name="hub">The Sentry hub.</param>
+        /// <param name="ex">The exception.</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)
+            => !hub.IsEnabled
+                ? new SentryId()
+                : hub.CaptureEvent(new SentryEvent(ex), configureScope);
+
+        /// <summary>
+        /// Captures a message with a configurable scope callback.
+        /// </summary>
+        /// <param name="hub">The Sentry hub.</param>
+        /// <param name="message">The message to send.</param>
+        /// <param name="configureScope">The callback to configure the scope.</param>
+        /// <param name="level">The message level.</param>
+        /// <returns>The Id of the event</returns>
+        public static SentryId CaptureMessage(
+            this IHub hub,
+            string message,
+            Action<Scope> configureScope,
+            SentryLevel level = SentryLevel.Info)
+            => !hub.IsEnabled || string.IsNullOrWhiteSpace(message)
+                ? new SentryId()
+                : hub.CaptureEvent(
+                    new SentryEvent
+                    {
+                        Message = message,
+                        Level = level
+                    },
+                    configureScope);
     }
 }

src/Sentry/IHub.cs

@@ -69,5 +69,16 @@ ITransaction StartTransaction(
         /// Ends the currently active session.
         /// </summary>
         void EndSession(SessionEndStatus status = SessionEndStatus.Exited);
+
+        /// <summary>
+        /// Captures an event with a configurable scope.
+        /// </summary>
+        /// <remarks>
+        /// This allows modifying a scope without affecting other events.
+        /// </remarks>
+        /// <param name="evt">The event to be captured.</param>
+        /// <param name="configureScope">The callback to configure the scope.</param>
+        /// <returns></returns>
+        public SentryId CaptureEvent(SentryEvent evt, Action<Scope> configureScope);
     }
 }

src/Sentry/Internal/Hub.cs

@@ -271,6 +271,22 @@ public void EndSession(SessionEndStatus status = SessionEndStatus.Exited) =>
             return null;
         }
 
+        public SentryId CaptureEvent(SentryEvent evt, Action<Scope> configureScope)
+        {
+            try
+            {
+                var clonedScope = ScopeManager.GetCurrent().Key.Clone();
+                configureScope(clonedScope);
+
+                return CaptureEvent(evt, clonedScope);
+            }
+            catch (Exception e)
+            {
+                _options.LogError("Failure to capture event: {0}", e, evt.EventId);
+                return SentryId.Empty;
+            }
+        }
+
         public SentryId CaptureEvent(SentryEvent evt, Scope? scope = null)
         {
             try

src/Sentry/SentrySdk.cs

@@ -234,6 +234,8 @@ public static void AddBreadcrumb(
         /// </remarks>
         /// <see href="https://docs.sentry.io/platforms/dotnet/enriching-events/scopes/#local-scopes"/>
         /// <param name="scopeCallback">The callback to run with the one time scope.</param>
+        [Obsolete("This method is deprecated in favor of overloads of CaptureEvent, CaptureMessage and CaptureException " +
+                  "that provide a callback to a configurable scope.")]
         [DebuggerStepThrough]
         public static void WithScope(Action<Scope> scopeCallback)
             => _hub.WithScope(scopeCallback);
@@ -275,6 +277,20 @@ public static SentryId CaptureEvent(SentryEvent evt)
         public static SentryId CaptureEvent(SentryEvent evt, Scope? scope)
             => _hub.CaptureEvent(evt, scope);
 
+        /// <summary>
+        /// Captures an event with a configurable scope.
+        /// </summary>
+        /// <remarks>
+        /// This allows modifying a scope without affecting other events.
+        /// </remarks>
+        /// <param name="evt">The event.</param>
+        /// <param name="configureScope">The callback to configure the scope.</param>
+        /// <returns>The Id of the event.</returns>
+        [DebuggerStepThrough]
+        [EditorBrowsable(EditorBrowsableState.Never)]
+        public static SentryId CaptureEvent(SentryEvent evt, Action<Scope> configureScope)
+            => _hub.CaptureEvent(evt, configureScope);
+
         /// <summary>
         /// Captures the exception.
         /// </summary>
@@ -284,6 +300,19 @@ public static SentryId CaptureEvent(SentryEvent evt, Scope? scope)
         public static SentryId CaptureException(Exception exception)
             => _hub.CaptureException(exception);
 
+        /// <summary>
+        /// Captures the exception with a configurable scope.
+        /// </summary>
+        /// <remarks>
+        /// 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>
+        /// <returns>The Id of the even.t</returns>
+        [DebuggerStepThrough]
+        public static SentryId CaptureException(Exception exception, Action<Scope> configureScope)
+            => _hub.CaptureException(exception, configureScope);
+
         /// <summary>
         /// Captures the message.
         /// </summary>
@@ -294,6 +323,20 @@ public static SentryId CaptureException(Exception exception)
         public static SentryId CaptureMessage(string message, SentryLevel level = SentryLevel.Info)
             => _hub.CaptureMessage(message, level);
 
+        /// <summary>
+        /// Captures the message with a configurable scope.
+        /// </summary>
+        /// <remarks>
+        /// This allows modifying a scope without affecting other events.
+        /// </remarks>
+        /// <param name="message">The message to send.</param>
+        /// <param name="configureScope">The callback to configure the scope.</param>
+        /// <param name="level">The message level.</param>
+        /// <returns>The Id of the event.</returns>
+        [DebuggerStepThrough]
+        public static SentryId CaptureMessage(string message, Action<Scope> configureScope, SentryLevel level = SentryLevel.Info)
+            => _hub.CaptureMessage(message, configureScope, level);
+
         /// <summary>
         /// Captures a user feedback.
         /// </summary>

test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.Core3_1.verified.txt

@@ -119,6 +119,8 @@ 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 CaptureMessage(this Sentry.IHub hub, string message, System.Action<Sentry.Scope> configureScope, Sentry.SentryLevel level = 1) { }
         public static void LockScope(this Sentry.IHub hub) { }
         public static System.IDisposable PushAndLockScope(this Sentry.IHub hub) { }
         public static Sentry.ITransaction StartTransaction(this Sentry.IHub hub, Sentry.ITransactionContext context) { }
@@ -164,6 +166,7 @@ namespace Sentry
     {
         Sentry.SentryId LastEventId { get; }
         void BindException(System.Exception exception, Sentry.ISpan span);
+        Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, System.Action<Sentry.Scope> configureScope);
         void EndSession(Sentry.SessionEndStatus status = 0);
         Sentry.ISpan? GetSpan();
         Sentry.SentryTraceHeader? GetTraceHeader();
@@ -514,8 +517,11 @@ namespace Sentry
         public static void BindException(System.Exception exception, Sentry.ISpan span) { }
         public static Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt) { }
         public static Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, Sentry.Scope? scope) { }
+        public static Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, System.Action<Sentry.Scope> configureScope) { }
         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 CaptureMessage(string message, Sentry.SentryLevel level = 1) { }
+        public static Sentry.SentryId CaptureMessage(string message, System.Action<Sentry.Scope> configureScope, Sentry.SentryLevel level = 1) { }
         public static void CaptureSession(Sentry.SessionUpdate sessionUpdate) { }
         public static void CaptureTransaction(Sentry.Transaction transaction) { }
         public static void CaptureUserFeedback(Sentry.UserFeedback userFeedback) { }
@@ -541,6 +547,8 @@ namespace Sentry
         public static Sentry.ITransaction StartTransaction(string name, string operation) { }
         public static Sentry.ITransaction StartTransaction(string name, string operation, Sentry.SentryTraceHeader traceHeader) { }
         public static Sentry.ITransaction StartTransaction(string name, string operation, string? description) { }
+        [System.Obsolete("This method is deprecated in favor of overloads of CaptureEvent, CaptureMessage a" +
+            "nd CaptureException that provide a callback to a configurable scope.")]
         public static void WithScope(System.Action<Sentry.Scope> scopeCallback) { }
     }
     public sealed class SentryStackFrame : Sentry.IJsonSerializable
@@ -916,6 +924,7 @@ namespace Sentry.Extensibility
         public void BindClient(Sentry.ISentryClient client) { }
         public void BindException(System.Exception exception, Sentry.ISpan span) { }
         public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, Sentry.Scope? scope = null) { }
+        public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, System.Action<Sentry.Scope> configureScope) { }
         public void CaptureSession(Sentry.SessionUpdate sessionUpdate) { }
         public void CaptureTransaction(Sentry.Transaction transaction) { }
         public void CaptureUserFeedback(Sentry.UserFeedback userFeedback) { }
@@ -951,6 +960,7 @@ namespace Sentry.Extensibility
         public void BindException(System.Exception exception, Sentry.ISpan span) { }
         public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt) { }
         public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, Sentry.Scope? scope) { }
+        public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, System.Action<Sentry.Scope> configureScope) { }
         public Sentry.SentryId CaptureException(System.Exception exception) { }
         public void CaptureSession(Sentry.SessionUpdate sessionUpdate) { }
         public void CaptureTransaction(Sentry.Transaction transaction) { }
@@ -967,6 +977,8 @@ namespace Sentry.Extensibility
         public void ResumeSession() { }
         public void StartSession() { }
         public Sentry.ITransaction StartTransaction(Sentry.ITransactionContext context, System.Collections.Generic.IReadOnlyDictionary<string, object?> customSamplingContext) { }
+        [System.Obsolete("This method is deprecated in favor of overloads of CaptureEvent, CaptureMessage a" +
+            "nd CaptureException that provide a callback to a configurable scope.")]
         public void WithScope(System.Action<Sentry.Scope> scopeCallback) { }
     }
     public interface IDiagnosticLogger

test/Sentry.DiagnosticSource.Tests/ApiApprovalTests.Run.DotNet5_0.verified.txt

@@ -119,6 +119,8 @@ 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 CaptureMessage(this Sentry.IHub hub, string message, System.Action<Sentry.Scope> configureScope, Sentry.SentryLevel level = 1) { }
         public static void LockScope(this Sentry.IHub hub) { }
         public static System.IDisposable PushAndLockScope(this Sentry.IHub hub) { }
         public static Sentry.ITransaction StartTransaction(this Sentry.IHub hub, Sentry.ITransactionContext context) { }
@@ -164,6 +166,7 @@ namespace Sentry
     {
         Sentry.SentryId LastEventId { get; }
         void BindException(System.Exception exception, Sentry.ISpan span);
+        Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, System.Action<Sentry.Scope> configureScope);
         void EndSession(Sentry.SessionEndStatus status = 0);
         Sentry.ISpan? GetSpan();
         Sentry.SentryTraceHeader? GetTraceHeader();
@@ -514,8 +517,11 @@ namespace Sentry
         public static void BindException(System.Exception exception, Sentry.ISpan span) { }
         public static Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt) { }
         public static Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, Sentry.Scope? scope) { }
+        public static Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, System.Action<Sentry.Scope> configureScope) { }
         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 CaptureMessage(string message, Sentry.SentryLevel level = 1) { }
+        public static Sentry.SentryId CaptureMessage(string message, System.Action<Sentry.Scope> configureScope, Sentry.SentryLevel level = 1) { }
         public static void CaptureSession(Sentry.SessionUpdate sessionUpdate) { }
         public static void CaptureTransaction(Sentry.Transaction transaction) { }
         public static void CaptureUserFeedback(Sentry.UserFeedback userFeedback) { }
@@ -541,6 +547,8 @@ namespace Sentry
         public static Sentry.ITransaction StartTransaction(string name, string operation) { }
         public static Sentry.ITransaction StartTransaction(string name, string operation, Sentry.SentryTraceHeader traceHeader) { }
         public static Sentry.ITransaction StartTransaction(string name, string operation, string? description) { }
+        [System.Obsolete("This method is deprecated in favor of overloads of CaptureEvent, CaptureMessage a" +
+            "nd CaptureException that provide a callback to a configurable scope.")]
         public static void WithScope(System.Action<Sentry.Scope> scopeCallback) { }
     }
     public sealed class SentryStackFrame : Sentry.IJsonSerializable
@@ -916,6 +924,7 @@ namespace Sentry.Extensibility
         public void BindClient(Sentry.ISentryClient client) { }
         public void BindException(System.Exception exception, Sentry.ISpan span) { }
         public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, Sentry.Scope? scope = null) { }
+        public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, System.Action<Sentry.Scope> configureScope) { }
         public void CaptureSession(Sentry.SessionUpdate sessionUpdate) { }
         public void CaptureTransaction(Sentry.Transaction transaction) { }
         public void CaptureUserFeedback(Sentry.UserFeedback userFeedback) { }
@@ -951,6 +960,7 @@ namespace Sentry.Extensibility
         public void BindException(System.Exception exception, Sentry.ISpan span) { }
         public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt) { }
         public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, Sentry.Scope? scope) { }
+        public Sentry.SentryId CaptureEvent(Sentry.SentryEvent evt, System.Action<Sentry.Scope> configureScope) { }
         public Sentry.SentryId CaptureException(System.Exception exception) { }
         public void CaptureSession(Sentry.SessionUpdate sessionUpdate) { }
         public void CaptureTransaction(Sentry.Transaction transaction) { }
@@ -967,6 +977,8 @@ namespace Sentry.Extensibility
         public void ResumeSession() { }
         public void StartSession() { }
         public Sentry.ITransaction StartTransaction(Sentry.ITransactionContext context, System.Collections.Generic.IReadOnlyDictionary<string, object?> customSamplingContext) { }
+        [System.Obsolete("This method is deprecated in favor of overloads of CaptureEvent, CaptureMessage a" +
+            "nd CaptureException that provide a callback to a configurable scope.")]
         public void WithScope(System.Action<Sentry.Scope> scopeCallback) { }
     }
     public interface IDiagnosticLogger