Write the 7.x section of the .NET migration guide #5710

The 7.0 project's Definition of Done requires a migration guide on docs.sentry.io that covers every breaking change, with the code a 6.x user has to change. docs/platforms/dotnet/common/migration/index.mdx in getsentry/sentry-docs has no 7.x section yet. #5698, #5700 and #5632 all point at it, but no issue owns it.

Several PR descriptions already have before/after snippets that can be copied: #5573 (Serilog), #5585 (NLog), #5592 (log4net), #5595 (Microsoft.Extensions.Logging), #5632 (TraceIgnoreStatusCodes) and #5669 (Envelope).

The section should merge when 7.0.0 ships. Before it does, check git log origin/main..origin/version7 for anything merged after this issue was written.

Entries

Target frameworks

• .NET 11 is supported (#5529, feat: add support for .NET 11 RC 1 #5566). Mobile targets (-android, -ios, -maccatalyst, -windows) move to net10.0 and net11.0, so the net9.0 mobile targets are dropped. Non-mobile targets keep net8.0 and net9.0 and add net11.0.
• On net11.0, the minimum Android API level rises from 21 to 24 and the minimum Mac Catalyst version from 15.0 to 17.0. Apps on net10.0 are unaffected.

Logging integrations no longer initialize the SDK (#5245)

Details are in #5706.

• Serilog, NLog, log4net and Microsoft.Extensions.Logging need Sentry initialized first, with SentrySdk.Init or UseSentry. The old DSN entry points fail with a migration message.
• Serilog: ApplySerilogScopeToEvents() is now UseSerilog(), and Log.CloseAndFlush() no longer disposes the SDK. Dispose the handle that SentrySdk.Init returns instead.
• NLog: the dsn, release, environment, initializeSdk, shutdownTimeoutSeconds and flushTimeoutSeconds attributes are gone, and the flush timeout is now SentryOptions.FlushTimeout (2 seconds instead of 15).
• log4net: Environment is gone, and closing the repository no longer flushes Sentry.
• Microsoft.Extensions.Logging: Logging:Sentry accepts only logging settings, SentryLoggingOptions no longer derives from SentryOptions, the host options derive from the new SentryHostOptions, and AddSentry<TOptions> requires TOptions : SentryHostOptions.
• Generic-host apps initialize Sentry with the API from Add a non-logging way to initialise Sentry in generic host apps #5572 (docs in Document how to initialize Sentry in generic host apps for v7.0.0 #5707).
  • When replacing Logging.AddSentry() with UseSentry, keep UseSentry after ClearProviders(). In 6.x both were calls on the logging builder, and the usual order put ClearProviders() first. UseSentry goes on the host builder, so it's easy to call it first. Then ClearProviders() removes Sentry's ILogger integration without an error or a warning. See #5755.

Logs and metrics

• SentryOptions.EnableLogs is removed (feat!: EnableLogs moves from SentryOptions to ASP.NET Core, MAUI and Blazor, where logs are opt-in #5642). It stays on the ASP.NET Core, MAUI and Blazor options. Serilog's enableLogs parameter is removed, and NLog's is obsolete and ignored. Details are in Document the logging changes for v7.0.0 #5698.
• An app that calls UseSentry and also Logging.AddSentry() now ignores options passed to Logging.AddSentry() in code (fix!: apps that call both UseSentry and Logging.AddSentry() no longer capture each error, breadcrumb and log twice #5694). Move them to the host's options and remove the call.
• SentryOptions.EnableMetrics is removed (feat!: remove SentryOptions.EnableMetrics #5690). To drop metrics, return null from SetBeforeSendMetric.

Tracing

• TraceIgnoreStatusCodes defaults to [301, (305, 399), (401, 404)] (feat!: don't trace 301, 305-399 or 401-404 responses by default #5632). Details are in Document TraceIgnoreStatusCodes and its new default for v7.0.0 #5708.
• The OTLP exporter no longer sets up a propagator, and the defaultTextMapPropagator parameter of AddSentryOtlpExporter and UseOtlp is removed (#5319). Details are in Document changes to OTel propagator for v7.0.0 #5546.
• The minimum OpenTelemetry version is 1.12.0 (feat(otel): raise the OpenTelemetry floor to 1.12.0 #5560).

Release, environment and SDK name (#5671)

Details are in #5709.

• Scope.Release and Scope.Distribution are removed, and Release and Distribution move from IEventLike to ITransactionData. Set them on SentryOptions, or on an individual event, transaction or check-in.
• SentryOptions.ApplyDefaultTags is removed. DefaultTags are still applied.
• An environment set on the scope now applies to logs, metrics, sessions and check-ins too.
• sdk.name names the integration that initialized Sentry, so Serilog and NLog events no longer report their own SDK name, and Blazor WebAssembly reports sentry.dotnet.aspnetcore.blazor.webassembly.
• On Android, iOS and Mac Catalyst, SENTRY_RELEASE takes precedence over the release derived from the app package.
• More apps now report the .NET host environment when they don't set Environment (feat!: set the Sentry environment from the host environment in every ASP.NET Core UseSentry overload, Blazor WebAssembly and Google Cloud Functions #5703): Blazor WebAssembly, Google Cloud Functions, and apps that use the ISentryBuilder overloads of ASP.NET Core's UseSentry, which gRPC apps do. They report development, staging or a custom environment name where they used to report production, or debug with a debugger attached. Update saved searches and alerts that filter on the old value, or set Environment (or SENTRY_ENVIRONMENT) to keep it.

MAUI

• Options set in UseSentry now take precedence over appsettings.json (fix(maui)!: options set in UseSentry now take precedence over appsettings.json #5658). The order is the Sentry configuration section, then the UseSentry callback, then the settings MAUI forces.

Removed or internal APIs

• iOS and Mac Catalyst: SentryOptions.Native.EnableAppHangTrackingV2 is removed; use EnableAppHangTracking. SentryOptions.Native.AddInAppExclude(string) is removed; it had no effect (feat!: remove obsolete iOS options EnableAppHangTrackingV2 and AddInAppExclude #5654).
• SentryOptions.ScopeObserver, EnableScopeSync and CrashedLastRun are internal (feat!: SentryOptions.ScopeObserver, EnableScopeSync and CrashedLastRun are now internal #5631). An EnableScopeSync key in configuration is ignored.
• Envelope.FromEvent, FromFeedback and FromTransaction take the logger as their last parameter (feat!: Envelope.FromEvent, FromFeedback and FromTransaction now take the logger as their last parameter #5669).
• Breadcrumbs with the "critical" level are no longer read as Fatal (feat!: stop deserializing "critical" breadcrumb level #5630). This only affects envelopes cached by 5.x and never sent.