docs(dotnet): Add 6.x to 7.x migration guide

docs/platforms/dotnet/common/migration/index.mdx

@@ -7,6 +7,14 @@ sidebar_section: configuration
 
 Upgrading includes both breaking changes and new features.
 
+<PlatformSection notSupported={["dotnet.xamarin"]}>
+
+## Migrating to 7.x
+
+See the <PlatformLink to="/migration/v6-to-v7/">6.x to 7.x migration guide</PlatformLink> for every change, or use the <PlatformLink to="/migration/v6-to-v7/interactive/">interactive migration checklist</PlatformLink> to track your progress.
+
+</PlatformSection>
+
 ## Migrating to 6.x
 
 ### .NET Target Framework Changes

docs/platforms/dotnet/common/migration/v6-to-v7/index.mdx

@@ -0,0 +1,125 @@
+---
+title: Migrate from 6.x to 7.x
+sidebar_order: 1
+description: "Learn how to migrate your app from version 6.x to 7.x of the Sentry SDK for .NET."
+notSupported:
+  - dotnet.xamarin
+---
+
+<Include name="dotnet-v7-agent-migration" />
+
+<Include name="dotnet-v7-migration-overview" />
+
+<Alert title="Prefer a checklist?" level="info">
+
+The [Interactive 7.x Migration Guide](./interactive/) lets you check off completed migration steps.
+
+</Alert>
+
+## Versions and Packages
+
+### Supported .NET Versions and Platforms
+
+<Include name="migration/dotnet-v7/supported-net-versions-and-platforms" />
+
+### Update All Sentry Packages Together
+
+<Include name="migration/dotnet-v7/update-all-sentry-packages-together" />
+
+## Initializing Sentry
+
+### Logging Integrations No Longer Initialize Sentry
+
+<Include name="migration/dotnet-v7/logging-integrations-no-longer-initialize-sentry" />
+
+### Generic Host Apps Call UseSentry
+
+<Include name="migration/dotnet-v7/generic-host-apps-call-usesentry" />
+
+### Logging Options Only Set Log Levels
+
+<Include name="migration/dotnet-v7/logging-options-only-set-log-levels" />
+
+### IHub Is Registered Only by UseSentry
+
+<Include name="migration/dotnet-v7/ihub-is-registered-only-by-usesentry" />
+
+### Remove Redundant Logging.AddSentry Calls
+
+<Include name="migration/dotnet-v7/remove-redundant-loggingaddsentry-calls" />
+
+### Move SDK Settings Out of the Serilog Sink
+
+<Include name="migration/dotnet-v7/move-sdk-settings-out-of-the-serilog-sink" />
+
+### Move SDK Settings Out of the NLog Target
+
+<Include name="migration/dotnet-v7/move-sdk-settings-out-of-the-nlog-target" />
+
+### Move SDK Settings Out of the log4net Appender
+
+<Include name="migration/dotnet-v7/move-sdk-settings-out-of-the-log4net-appender" />
+
+## Logs and Metrics
+
+### EnableLogs Moves to Host Options
+
+<Include name="migration/dotnet-v7/enablelogs-moves-to-host-options" />
+
+### Logging Integrations Send Logs
+
+<Include name="migration/dotnet-v7/logging-integrations-send-logs" />
+
+### Logging Frameworks No Longer Close Sentry
+
+<Include name="migration/dotnet-v7/logging-frameworks-no-longer-close-sentry" />
+
+### EnableMetrics Is Removed
+
+<Include name="migration/dotnet-v7/enablemetrics-is-removed" />
+
+## Tracing and OpenTelemetry
+
+### Some Requests Are No Longer Traced
+
+<Include name="migration/dotnet-v7/some-requests-are-no-longer-traced" />
+
+### The OpenTelemetry Exporter No Longer Sets a Propagator
+
+<Include name="migration/dotnet-v7/the-opentelemetry-exporter-no-longer-sets-a-propagator" />
+
+## Release, Environment and SDK Name
+
+### Release and Distribution Are Set on Options
+
+<Include name="migration/dotnet-v7/release-and-distribution-are-set-on-options" />
+
+### More Apps Report the Host Environment
+
+<Include name="migration/dotnet-v7/more-apps-report-the-host-environment" />
+
+### SDK Name, Release and Scope Environment
+
+<Include name="migration/dotnet-v7/sdk-name-release-and-scope-environment" />
+
+## Integrations
+
+### UseSentry Overrides appsettings.json in MAUI
+
+<Include name="migration/dotnet-v7/usesentry-overrides-appsettingsjson-in-maui" />
+
+### Hangfire Sends Recurring Job Schedules
+
+<Include name="migration/dotnet-v7/hangfire-sends-recurring-job-schedules" />
+
+## Removed and Internal APIs
+
+### Other Removed and Internal APIs
+
+<Include name="migration/dotnet-v7/other-removed-and-internal-apis" />
+
+## Optional Cleanup
+
+### Call UseSentry on WebApplicationBuilder
+
+<Include name="migration/dotnet-v7/call-usesentry-on-webapplicationbuilder" />

docs/platforms/dotnet/common/migration/v6-to-v7/interactive.mdx

@@ -0,0 +1,25 @@
+---
+title: Interactive 7.x Migration Guide
+sidebar_order: 2
+description: "Migrate from version 6.x to 7.x of the Sentry SDK for .NET with an interactive checklist."
+notSupported:
+  - dotnet.xamarin
+---
+
+<Include name="dotnet-v7-agent-migration" />
+
+<Include name="dotnet-v7-migration-overview" />
+
+This checklist covers the 7.x migration. Some steps only apply to specific integrations, platforms or configuration options. Check off a step after you complete it or confirm that it doesn't apply to your app. This browser saves your progress.
+
+For details about each change, see the [migration guide](../).
+
+<Alert level="warning">
+
+The compiler won't catch every change. Read through the steps before upgrading, including the changes to logs, tracing and the reported environment.
+
+</Alert>
+
+## Your Migration Steps
+
+<MigrationGuide migration="dotnet-v7" />

includes/dotnet-v7-agent-migration.mdx

@@ -0,0 +1,5 @@
+<AgentMigrationCallout
+  guideUrl="migration/v6-to-v7.md"
+  prompt="Upgrade this project from the Sentry SDK for .NET 6.x to 7.x. Inspect its Sentry NuGet packages, target frameworks, hosting model, logging integrations and how it initializes Sentry. Apply every migration step that applies to this project. Initialize Sentry once with UseSentry or SentrySdk.Init, and move the DSN and other SDK settings out of the logging integrations and the Logging:Sentry configuration section. Preserve the intended telemetry behavior, including the logs the app sends, the requests it traces and the environment it reports. Verify the migration with dotnet build and the project's existing tests, then run the app once and confirm that Sentry initializes, for example with Debug enabled, because a build alone doesn't catch a logging integration that sends nothing. Summarize the changes and any remaining manual steps."
+  description="Copy this prompt into your AI agent to migrate to 7.x."
+/>

includes/dotnet-v7-migration-overview.mdx

@@ -0,0 +1,21 @@
+<Alert level="warning" title="Release candidate">
+
+There is no stable 7.0 release of the Sentry SDK for .NET yet. The current release candidate is `7.0.0-rc.2`. Until 7.0.0 ships, use that version wherever this guide says `7.0.0`. The rest of the .NET docs still describe 6.x until then, so where they differ from this guide, follow this guide. If you run into problems, [open an issue on GitHub](https://github.com/getsentry/sentry-dotnet/issues).
+
+The release candidate's `net11.0` builds depend on the .NET 11 release candidate versions of `Microsoft.Extensions.Http`, `Microsoft.Extensions.Logging.Configuration` and `Microsoft.Extensions.Configuration.Binder`. A .NET 11 app that references 10.0.x of one of these packages directly fails to restore with error NU1605. Remove that reference, or update it to the same .NET 11 release candidate version.
+
+</Alert>
+
+Version 7 of the Sentry SDK for .NET adds support for .NET 11 and moves SDK initialization out of the logging integrations. The biggest changes are:
+
+- **One place to initialize Sentry.** The Serilog, NLog, log4net and `Microsoft.Extensions.Logging` integrations no longer start the SDK. Call `UseSentry` or `SentrySdk.Init` first, and move the DSN and other SDK settings there.
+- **`UseSentry` for generic host apps.** Worker services, Azure Functions isolated worker apps and other apps on the .NET Generic Host can now call `UseSentry` from the new `Sentry.Extensions.Hosting` package.
+- **Logs.** Version 7 removes `SentryOptions.EnableLogs`. Structured logs are now enabled automatically if you add the Serilog, NLog or log4net integrations, so check the volume and content of your logs after upgrading if you use any of these integrations.
+- **Platforms.** Android, iOS, Mac Catalyst and MAUI apps need .NET 10 or later.
+- **Defaults.** The SDK traces fewer incoming requests, and more apps report the host environment instead of `production`.
+
+Upgrade to the latest 6.x release first, which is 6.12.1, and fix its obsolete warnings. Some APIs that 7.0 removes, such as `EnableMetrics` and the iOS option `EnableAppHangTrackingV2`, are already obsolete in 6.x.
+
+The `Sentry.OpenTelemetry` package is now obsolete. Code using this integration, such as `AddSentry()` on the tracer provider builder with `options.UseOpenTelemetry()`, still compiles on 7.0, but you will get warnings. The package will not see any future improvements or bug fixes, and it will be removed in a future version. Its replacement is the OTLP exporter from `Sentry.OpenTelemetry.Exporter`, with `AddSentryOtlpExporter` and `UseOtlp`. See [OpenTelemetry (OTLP)](/platforms/dotnet/tracing/instrumentation/opentelemetry-otlp/).
+
+The compiler catches most of the changes. A few only show up at runtime or in your data. A logging integration sends nothing until you initialize Sentry. An app that calls `SentrySdk.Init` and injects `IHub` fails when the container resolves the service. The new defaults change log volume, traced requests and the reported environment. Read the behavior changes before you upgrade.

includes/migration/dotnet-v7/call-usesentry-on-webapplicationbuilder.mdx

@@ -0,0 +1,54 @@
+---
+id: call-usesentry-on-webapplicationbuilder
+title: "Call UseSentry on WebApplicationBuilder"
+phase: cleanup
+category: rename
+severity: informational
+frameworks: all
+platformCategory: all
+order: 10
+---
+
+ASP.NET Core apps can now call `UseSentry` on `WebApplicationBuilder` and keep chaining. `builder.WebHost.UseSentry()` still works, so this change is optional.
+
+In 6.x, `UseSentry` was only available on the web host:
+
+```csharp {filename:Program.cs}
+var builder = WebApplication.CreateBuilder(args);
+builder.WebHost.UseSentry(options => options.Dsn = "___PUBLIC_DSN___");
+```
+
+In 7.x, call it on the builder:
+
+```csharp {filename:Program.cs}
+var builder = WebApplication.CreateBuilder(args);
+builder.UseSentry(options => options.Dsn = "___PUBLIC_DSN___");
+```
+
+A helper declared in the `Microsoft.Extensions.Hosting` namespace needs a static call instead. The `AddServiceDefaults` method that .NET Aspire templates generate is one example. Inside that namespace, `web.UseSentry()` binds to the generic host overload from `Sentry.Extensions.Hosting`, even for a `WebApplicationBuilder`. The app then misses request data, the middleware and the transactions for incoming requests. Call the ASP.NET Core overload as a static method:
+
+```csharp {filename:Extensions.cs}
+using Microsoft.AspNetCore.Builder;
+
+namespace Microsoft.Extensions.Hosting;
+
+public static class Extensions
+{
+    public static TBuilder AddServiceDefaults<TBuilder>(this TBuilder builder)
+        where TBuilder : IHostApplicationBuilder
+    {
+        if (builder is WebApplicationBuilder web)
+        {
+            SentryWebApplicationBuilderExtensions.UseSentry(web);
+        }
+        else
+        {
+            builder.UseSentry();
+        }
+
+        return builder;
+    }
+}
+```
+
+When `UseSentry` from `Sentry.Extensions.Hosting` runs in an ASP.NET Core app, the SDK logs a warning through `ILogger` when the host starts.

includes/migration/dotnet-v7/enablelogs-moves-to-host-options.mdx

@@ -0,0 +1,46 @@
+---
+id: enablelogs-moves-to-host-options
+title: "EnableLogs Moves to Host Options"
+phase: code-changes
+category: removed-api
+severity: action-required
+frameworks: all
+platformCategory: all
+order: 90
+---
+
+Version 7 removes `SentryOptions.EnableLogs`, so setting it in `SentrySdk.Init` fails to compile with error CS1061. Remove the line. Logs sent with `SentrySdk.Logger` or through the logging integrations don't need it.
+
+In 6.x, `SentrySdk.Init` turned logs on:
+
+```csharp {filename:Program.cs}
+SentrySdk.Init(options =>
+{
+    options.Dsn = "___PUBLIC_DSN___";
+    options.EnableLogs = true;
+});
+```
+
+In 7.x, logs need no option:
+
+```csharp {filename:Program.cs}
+SentrySdk.Init(options =>
+{
+    options.Dsn = "___PUBLIC_DSN___";
+});
+```
+
+`EnableLogs` stays on the options of `UseSentry` in ASP.NET Core, MAUI, Blazor WebAssembly and generic host apps. There it still defaults to `false`, and it only controls whether the `ILogger` integration that `UseSentry` adds sends log entries as logs:
+
+```csharp {filename:Program.cs}
+var builder = WebApplication.CreateBuilder(args);
+builder.UseSentry(options =>
+{
+    options.Dsn = "___PUBLIC_DSN___";
+    options.EnableLogs = true;
+});
+```
+
+You can also set `EnableLogs` in the `Sentry` section of `appsettings.json` in these apps. A generic host app that set `EnableLogs` on `Logging.AddSentry` in 6.x sets it on `UseSentry` now.
+
+The Serilog sink no longer takes an `enableLogs` argument, and NLog's `enableLogs` setting has no effect. The Serilog sink, the NLog target and the log4net appender send logs whether `EnableLogs` is on or off. See [Logging Integrations Send Logs](#logging-integrations-send-logs).

includes/migration/dotnet-v7/enablemetrics-is-removed.mdx

@@ -0,0 +1,34 @@
+---
+id: enablemetrics-is-removed
+title: "EnableMetrics Is Removed"
+phase: code-changes
+category: removed-api
+severity: action-required
+frameworks: all
+platformCategory: all
+order: 100
+---
+
+Version 7 removes `SentryOptions.EnableMetrics`, so setting it fails to compile with error CS1061. The option has been obsolete and ignored since 6.10.0, because metrics are always on. To drop metrics, return `null` from `SetBeforeSendMetric`.
+
+In 6.x, the obsolete option compiled but had no effect:
+
+```csharp {filename:Program.cs}
+SentrySdk.Init(options =>
+{
+    options.Dsn = "___PUBLIC_DSN___";
+    options.EnableMetrics = false;
+});
+```
+
+In 7.x, drop metrics in the callback:
+
+```csharp {filename:Program.cs}
+SentrySdk.Init(options =>
+{
+    options.Dsn = "___PUBLIC_DSN___";
+    options.SetBeforeSendMetric(_ => null);
+});
+```
+
+The SDK ignores an `EnableMetrics` key in the `Sentry` section of `appsettings.json`. Remove it.