fix(maui)!: options set in UseSentry now take precedence over appsettings.json

[jamescrosswell]

Summary

In MAUI, a setting in appsettings.json overrode the same setting passed to UseSentry(options => ...). ASP.NET Core does the reverse: configuration supplies the defaults and the callback overrides them.

SentryMauiOptionsSetup did two jobs. It bound the Sentry section, and it applied the settings MAUI forces: global mode, the debug logger, the SDK and screenshot event processors, and Native.AttachScreenshot. It was registered after the callback, so the binding ran last.

The issue suggests registering that setup before the callback. That would break the forced half, which reads Debug and AttachScreenshot after the callback has set them. For example, UseSentry(o => o.AttachScreenshot = true) would never add the screenshot processor. So this PR splits the class instead:

• SentryMauiConfigurationOptionsSetup binds the Sentry section. It is registered before the callback.
• SentryMauiOptionsSetup keeps the forced settings and still runs after it.

Precedence is now: Sentry configuration section → UseSentry callback → settings MAUI forces.

For reviewers

There's a bit of a blurb on what's going on in this comment:

• fix(maui)!: options set in UseSentry now take precedence over appsettings.json #5658 (comment)

Notes

• This breaks MAUI apps that rely on appsettings.json overriding the callback, hence the !. The stack lands on version7.
• Services.Configure<SentryMauiOptions>(...) registered before UseSentry still runs before the configuration binding, as it did before. Only the callback has moved.
• UseSentry_DebugTrueInConfiguration_ConsoleAndTracingDiagnosticsLogger checks the split: a setting from configuration still has to reach the forced settings.

Closes #5657

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
⚠️ Please upload report for BASE (version7@378d9e4). Learn more about missing BASE report.

Additional details and impacted files

@@             Coverage Diff             @@
##             version7    #5658   +/-   ##
===========================================
  Coverage            ?   75.09%           
===========================================
  Files               ?      520           
  Lines               ?    18880           
  Branches            ?     3658           
===========================================
  Hits                ?    14177           
  Misses              ?     3840           
  Partials            ?      863           

☔ 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.

[jamescrosswell]

How the MAUI options pieces fit together

This is for review: it explains why SentryMauiConfigurationOptionsSetup and SentryMauiOptionsSetup are separate classes.

UseSentry doesn't build any options. It registers steps with DI, and OptionsFactory<T> runs IConfigureOptions<T> registrations in the order they were added, each one overwriting the last. So the registration order decides which values win. The options are built once, during MauiApp.Build(), when SentryMauiInitializer reads IOptions<SentryMauiOptions>.Value to initialize the SDK.

sequenceDiagram
    participant App as MauiProgram
    participant UseSentry
    participant Init as MauiApp.Build<br/>(SentryMauiInitializer)
    participant Factory as Options factory

    App->>UseSentry: UseSentry(callback)
    Note over UseSentry: Registers, in this order:<br/>1. SentryMauiConfigurationOptionsSetup<br/>2. the callback (services.Configure)<br/>3. SentryMauiOptionsSetup
    App->>Init: Build()
    Init->>Factory: IOptions.Value
    Note over Factory: new SentryMauiOptions()<br/>constructor defaults
    Factory->>Factory: SentryMauiConfigurationOptionsSetup<br/>binds the "Sentry" section
    Factory->>Factory: the UseSentry callback
    Factory->>Factory: SentryMauiOptionsSetup<br/>forced settings
    Factory-->>Init: options
    Init->>Init: SentrySdk.Init(options)

Loading

• Constructor defaults: new SentryMauiOptions() sets MAUI defaults the app can still change (AutoSessionTracking, DetectStartupTime, CacheDirectoryPath).
• SentryMauiConfigurationOptionsSetup: binds the Sentry section through BindableSentryMauiOptions, and only applies keys that are present. It has to run before the callback so the callback wins.
• The UseSentry callback: registered with services.Configure, so it's just another step.
• SentryMauiOptionsSetup: forces IsGlobalModeEnabled, and acts on the final values: the debug logger when Debug is set, the screenshot processor and Native.AttachScreenshot when AttachScreenshot is set, plus the SDK event processor and the network status listener. It has to run after the callback, because it reads what the callback set.

Precedence: constructor defaults → Sentry configuration section → callback → forced settings.

Before this PR both jobs lived in SentryMauiOptionsSetup, which was registered after the callback, so configuration overrode the callback. A single registration can only run at one point, so the two jobs had to be split.

Two existing behaviours this PR doesn't change:

• builder.Services.Configure<SentryMauiOptions>(...) outside UseSentry also runs by registration position. If it's registered before UseSentry, it runs before the configuration step, which is how the test fixture sets its DSN. If it's registered after, it runs after the forced settings.
• UseSentry also runs the callback once, straight away, on a throwaway SentryMauiOptions, to collect event binders that integrations add (for example CommunityToolkit.Mvvm). So the callback runs twice.

[ric-oliv]

Looks great! ❤️