🔥 Handling Global Exceptions in .NET MAUI and Sending to Sentry

In mobile app development, unhandled exceptions can lead to unexpected crashes that hurt user experience. Logging those errors helps us catch bugs in production. This article covers how to:

• Hook into global exception handlers in .NET MAUI

• Send those exceptions to Sentry

• Optionally use Sentry’s auto-capture features for a cleaner setup

🧠 Why Capture Unhandled Exceptions?

Errors can happen anywhere — network failures, background tasks, null references, etc. If they go unobserved, your app might crash and you won’t know why. That’s why we hook into:

• AppDomain.CurrentDomain.UnhandledException for synchronous errors

• TaskScheduler.UnobservedTaskException for background tasks

🛠️ Setting Up in .NET MAUI

In your MauiProgram.cs, hook into the global exception handlers early:

public static MauiApp CreateMauiApp()
{
    var builder = MauiApp.CreateBuilder();
    builder
        .UseMauiApp<App>()
        .ConfigureFonts(fonts => { /* your font config */ });

    // Attach global handlers
    AppDomain.CurrentDomain.UnhandledException += CurrentDomain_UnhandledException;
    TaskScheduler.UnobservedTaskException += TaskScheduler_UnobservedTaskException;

    return builder.Build();
}

Then implement the handlers:

private static void CurrentDomain_UnhandledException(object sender, UnhandledExceptionEventArgs e)
{
    try
    {
        if (e.ExceptionObject is Exception ex)
        {
            SentrySdk.CaptureException(ex);
        }
    }
    catch (Exception innerEx)
    {
        SentrySdk.CaptureException(innerEx);
    }
}

private static void TaskScheduler_UnobservedTaskException(object? sender, UnobservedTaskExceptionEventArgs e)
{
    try
    {
        e.SetObserved(); // Prevents app crash
        SentrySdk.CaptureException(e.Exception);
    }
    catch (Exception ex)
    {
        SentrySdk.CaptureException(ex);
    }
}

✅ Easier Way: Use Sentry’s MAUI Integration

Sentry offers a Sentry.Maui package that captures exceptions automatically, without manual hooks.

https://sentry.io/welcome/

Install via NuGet:

dotnet add package Sentry.Maui

🧰 Initialize Sentry

In MauiProgram.cs, initialize Sentry at the very start:

                .UseSentry(options =>
                {
                    // The DSN is the only required setting.
                    options.Dsn = ""; 

                    options.AutoSessionTracking = true;
                    options.AttachStacktrace = true;
                    options.CaptureFailedRequests = true;
                    options.SampleRate = 1.0F;
                    options.Release = $"AppName@{AppInfo.VersionString}-@{AppInfo.BuildString}";

#if DEBUG
                    options.Debug = false;
                    options.Environment = "Debug";
                    options.TracesSampleRate = 1.0;
#else
                    options.Debug = false;
                    options.Environment = "Production";
                    options.TracesSampleRate = 0.1;
#endif

                })

Now Sentry will automatically capture:

• Unhandled exceptions

• Unobserved tasks

• App lifecycle events

• Device context info

🧪 Optional: Manual Logging

Even with automatic capture, you can still manually log exceptions or messages:

try
{
    // risky code
}
catch (Exception ex)
{
    SentrySdk.CaptureException(ex);
}

Or add breadcrumbs to help trace what led to the crash:

SentrySdk.AddBreadcrumb("User tapped the purchase button");

🏁 Final Thoughts

By handling global exceptions and integrating with Sentry, you’ll get better visibility into crashes and bugs. Use the manual setup if you want fine-grained control or Sentry.Maui for a plug-and-play solution.

Happy debugging! 🔍