.NET Maui and breadcrumbs in background task

[jenscski]

Hello,

Part of our .NET Maui application is work done in the background, with no direct connection to the UI.

I'm unable to report anything to sentry.io without the default breadcrumbs.

Is there a way to achieve this?

[jenscski]

It looks like the breadcrumbs on Maui is global, so any navigation in the UI also affects reporting from an background task.

Is there a way to reset the breadcrumbs for each task?

[mattjohnsonpint]

Ok. I think I understand your question now. I'll do some research and get back to this shortly. Thanks.

[mattjohnsonpint]

Some background first:

In MAUI applications, we force the IsGlobalMode option to true (you can't change it). This has the effect of there being only one global scope for the entire application. This is what we recommend for client-based applications in general (both mobile and desktop, and not just MAUI), because there are many situations where one thread needs to include breadcrumbs, tags, and other information set from another thread. For example, a UI thread might click a button that uses a background thread to call an API that authenticates the user. The resulting user id would be set in context on the scope, and available both to the background thread and to the original UI thread and other threads of the application. Without global mode, only the background thread would have that information and then it would be lost. There are many other use cases, so global mode is essential for client apps. Additionally, it is quite possible that a background thread could be impacted by a crash on the UI thread or vice versa - especially on mobile apps. They tend to crash the entire app, not just one thread.

Global mode is specifically designed for the effect that you are describing - all breadcrumbs from anywhere in the application are presented on each and every event - even if they've been sent on prior events or are from a part of the application other than the one where the event occurred. This is by design.

Now getting to your use case - you have a background task that is completely disconnected from the UI and you don't want breadcrumbs and other details from the UI to be reported on events from the background task. One might think at first that this would be handled by disabling global mode. However that applies to the entire application and thus you would lose all benefits I previously described. Also I don't currently allow it disabled for MAUI (you can set it false, but internally we flip it back to true before it takes any effect).

Really what you need instead is a way to keep global mode enabled, but to create a separate and independent detached scope for your background thread. This is currently possible because the Scope object has a public constructor - but it is not something we have specifically designed for. You may find some quirks. In particular, only CaptureEvent will take a detached scope, so the helper methods CaptureException, CaptureMessage, etc. can't be used - though you can get the same effect through CaptureEvent. There are likely other quirks that I haven't thought about.

Here's how you would put this together in a MAUI app:

First, you'll need some class to act as the worker that is going to operate the background task.

using Microsoft.Extensions.Options;
using Sentry.Maui;

namespace Sentry.Samples.Maui;

public class MyWorker
{
    private readonly SentryMauiOptions _options;

    public MyWorker(IOptions<SentryMauiOptions> options)
    {
        _options = options.Value;
    }

    public async Task DoWorkAsync()
    {
        // Here a completely new scope is created - detached from any current scope.
        // No information is copied over from the current scope.  It is starting clean.
        var scope = new Scope(_options);

        try
        {
            // You'll need to add breadcrumbs and other items directly on that scope
            scope.AddBreadcrumb("Doing a thing");
            await Task.Delay(100);
            scope.AddBreadcrumb("Doing another thing");
            await Task.Delay(100);

            throw new Exception("Something went wrong!");
        }
        catch (Exception ex)
        {
            // When you capture events, pass the scope in as a parameter.
            SentrySdk.CaptureEvent(new SentryEvent(ex), scope);
        }
    }
}

You can see that I've injected IOptions<SentryMauiOptions> - this is already registered by default. But you will need to register the worker itself, as well as any page that it might be called from (in MauiProgram.CreateMauiApp):

    builder.Services.AddSingleton<MyWorker>();
    builder.Services.AddTransient<MainPage>();

Inject into your page (or wherever it will be used) and use like so:

    private readonly MyWorker _worker;

    public MainPage(MyWorker worker)
    {
        _worker = worker;
        InitializeComponent();
    }

    private void OnButtonClicked(object sender, EventArgs e)
    {
        // Run it as background task
        Task.Run(() => _worker.DoWorkAsync());
    }

Keep in mind that any context, tags, user info, or other details from the main scope won't be on the new one unless you copy them over manually yourself.

We'll consider making this scenario better supported in a future release - but this should be sufficient for now.

[jenscski]

Thanks for an detailed answer, and solution