[jamescrosswell]

Warning

Do not merge before sentry-dotnet 7.0.0 is released (planned 2026-11-30).

DESCRIBE YOUR PR

In sentry-dotnet 7.0.0 the Microsoft.Extensions.Logging integration no longer initializes the SDK (getsentry/sentry-dotnet#5595). Generic host apps initialize Sentry with UseSentry from the new Sentry.Extensions.Hosting package instead (getsentry/sentry-dotnet#5739). This updates the parts of getsentry/sentry-dotnet#5706 that #19925 leaves out:

• Microsoft.Extensions.Logging guide:
  • Generic host apps (worker services, Windows services, console apps on the generic host) call UseSentry from Sentry.Extensions.Hosting, without Logging.AddSentry().
  • Apps without a host, and .NET Framework apps on Host.CreateApplicationBuilder(), call SentrySdk.Init, then AddSentry(). If they inject IHub, ISentryClient or Func<IHub>, they register them with HubAdapter.Instance, because AddSentry() no longer does (feat(mel)!: Logging.AddSentry() no longer registers IHub or ISentryClient sentry-dotnet#5740).
  • ClearProviders(): call UseSentry after it, or call Logging.AddSentry() after it to add Sentry's providers back. Not when Serilog, NLog or log4net already sends ILogger entries to Sentry (fix(logging): make Logging.AddSentry() work after UseSentry and ClearProviders() sentry-dotnet#5776, fix(logging): warn when ClearProviders() removes the logger providers UseSentry added sentry-dotnet#5789, docs: add an ASP.NET Core NLog sample and stop advising AddSentry() when another integration handles ILogger sentry-dotnet#5821).
  • Removes the DSN in AddSentry(...), InitializeSdk, and SDK settings under Logging:Sentry. Documents what Logging:Sentry still accepts, the top-level Sentry section that UseSentry reads, EnableLogs for UseSentry, and AddLogEntryFilter.
• ASP.NET Core guide: SentryAspNetCoreOptions now extends SentryHostOptions, not SentryLoggingOptions.

Closes getsentry/sentry-dotnet#5706

Notes for review

• Generic host guide: Document how to initialize Sentry in generic host apps for v7.0.0 sentry-dotnet#5707 adds a dedicated guide at docs/platforms/dotnet/guides/extensions-hosting/ in a separate PR. This page doesn't link to it yet, because the link would 404 on this branch. Once both merge, the "Generic Host" section should link to it.
• Messages that point here: the uninitialized-SDK warning links to this page and says to call SentrySdk.Init or UseSentry. The Logging:Sentry startup errors and the obsolete Dsn/InitializeSdk/AddSentry(dsn) errors name UseSentry from Sentry.Extensions.Hosting, SentrySdk.Init and the Sentry section. The Debug warnings cover a redundant AddSentry(), its ignored options, and providers removed by ClearProviders(). The Configure section answers each of them.
• Checked against origin/version7 (f5f063e99):
  • Every C# snippet compiles on net10.0. The Host.CreateDefaultBuilder + UseSentry and the .NET Framework SentrySdk.Init + Host.CreateApplicationBuilder snippets also compile on net48, and Host.CreateApplicationBuilder().UseSentry() doesn't (CS1929).
  • Without the HubAdapter lines, a hosted service that injects IHub fails with Unable to resolve service for type 'Sentry.IHub' while attempting to activate 'Worker'. With them, all three types resolve to HubAdapter and captures through each reach the SDK.
  • UseSentry, then ClearProviders(), then AddSentry() sends LogError entries again, with the host's MinimumEventLevel. Options passed to that AddSentry() are ignored, with a diagnostic warning. Without AddSentry(), nothing reaches Sentry and the Debug warning appears. ClearProviders() before UseSentry works.
  • UseSentry with a later AddSentry() sends each error once and warns that the call has no effect.
  • Logging:Sentry:Dsn and Logging:Sentry:EnableLogs fail at startup with both setups. LogLevel, MinimumBreadcrumbLevel and MinimumEventLevel load.
  • Structured logs are on by default with SentrySdk.Init, and off with UseSentry until EnableLogs is true.
• Filters was always internal. The page shows AddLogEntryFilter, which now also works on the UseSentry options.
• The ASP.NET Core paragraph leaves out namespaces. SentryHostOptions is still in Sentry.Extensions.Logging on version7.
• On 6.x, AddSentry() after SentrySdk.Init initializes the SDK again without a DSN, and that throws. That's why the 7.0.0 note tells 6.x users to set the DSN in AddSentry(...) instead.
• docs(dotnet): Correct quick-start setup and verification #20240 also edits this page, against 6.x. Whichever merges second needs a merge from master. This PR leaves the Sentry prefix alert alone, which docs(dotnet): Correct quick-start setup and verification #20240 rewrites.

IS YOUR CHANGE URGENT?

Help us prioritize incoming PRs by letting us know when the change needs to go live.
Select exactly one option. For deadlines, replace YYYY-MM-DD with the due date. You can update this information later by editing the PR description.

• Urgent deadline (GA date, etc.): 2026-11-30
• Other deadline: YYYY-MM-DD
• No deadline: Not urgent, can wait up to 1 week+

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
sentry-docs	Ready	Preview	Oct 29, 2026 6:30am UTC

1 Skipped Deployment

Project	Deployment	Actions	Updated
develop-docs	Ignored	Preview	Oct 29, 2026 6:30am UTC

[cursor]

The change rewrites one guide so readers initialize the SDK before they add logging. It also updates option type names on a second guide. An issue escalates when those pages emit new client errors or stop serving.

Services: sentry-docs.

Mention @change-monitor in a comment to update the plan.

Plan

What changed

Visitors to /platforms/dotnet/guides/extensions-logging/ now see SentrySdk.Init before AddSentry(). SDK options now live in that init call. They no longer live in AddSentry or in the Sentry appsettings section. Visitors to /platforms/dotnet/guides/aspnetcore/ now see SentryAspNetCoreOptions extend SentryHostOptions and SentryOptions. This change is live after a production deploy of sentry-docs. The Vercel reporter maps that project to sentry-docs. The change does not ship develop-docs. It only edits files under docs/.

Risk

Broken MDX or code tabs can fail those two pages for every visitor. The ASP.NET Core guide has more traffic than the logging guide. The same code-tab and platform picker code also serves other .NET guides. Shipping this text before SDK 7.0.0 is released tells readers to call APIs that do not exist. Site telemetry cannot see that content error.

Intended effect

This is a documentation edit. Sentry has no metric for the new sentences. The executor cannot mark intended effect confirmed or absent from these queries. intended_effect stays unknown from telemetry.

Regression watch

Watch client errors and failed loads on the two changed pages. Also watch other .NET guide pages that share code tabs and the platform picker. Traces are sampled at 30 percent. Error events are not sampled.

Signal	Baseline	Rule	Source
Production error events on https://docs.sentry.io/platforms/dotnet/guides/extensions-logging/ and https://docs.sentry.io/platforms/dotnet/guides/aspnetcore/	0 events in 2026-10-13T23:43:06Z to 2026-10-14T23:43:06Z. 0 events in 2026-10-12T23:43:06Z to 2026-10-14T23:43:06Z.	Hold at 0. Any new title is a regression.	Sentry org sentry project docs. Query environment:production url:"https://docs.sentry.io/platforms/dotnet/guides/extensions-logging/" and the same query with the ASP.NET Core URL.
http.server spans with http.status_code >= 400 on those two paths	0 spans in 2026-10-12T23:43:06Z to 2026-10-14T23:43:06Z. 13 http.server spans on the path family were all 200.	Hold at 0.	Sentry traces project docs. Query span.op:http.server environment:production http.status_code:>=400 plus http.url or http.target for each path.
Sampled pageload and navigation spans for https://docs.sentry.io/platforms/dotnet/guides/aspnetcore/	17 spans in 2026-10-13T23:43:06Z to 2026-10-14T23:43:06Z. 27 spans in 2026-10-12T23:43:06Z to 2026-10-14T23:43:06Z. That is 10 spans in the prior 24 hours. Band 10-17 sampled spans per 24 hours.	Stay in 10-17 per 24 hours. Treat 0 as a miss. The page did not load.	Sentry traces project docs. Query environment:production span.op:[pageload,navigation] http.url:"https://docs.sentry.io/platforms/dotnet/guides/aspnetcore/".
Production error events whose URL contains /platforms/dotnet/guides/	3 events in 2026-10-12T23:43:06Z to 2026-10-14T23:43:06Z. All used title Event: Event \Event` (type=error) captured as promise rejection`.	Keep that title in 0-3 events per 48 hours. Any other title is a regression.	Sentry org sentry project docs. Query environment:production url:"*/platforms/dotnet/guides/*" grouped by title.

If a new error title appears, inspect that event for code-tab or MDX render frames.

Not observable

The live HTML of the two pages. Telemetry cannot show whether SentrySdk.Init is in the text. Pageload volume for /platforms/dotnet/guides/extensions-logging/ is not usable. The exact URL had 0 sampled pageload or navigation spans in 2026-10-12T23:43:06Z to 2026-10-14T23:43:06Z. Origin 4xx responses can miss Sentry because the CDN serves most hits. Whether readers copy the new init code into apps is not in this project.

[jamescrosswell]

Something I don't much like about the docs in general is phrasing like this:

This is on by default when you initialize Sentry with SentrySdk.Init. With UseSentry, set EnableLogs to true

The distinction between SentrySdk.Init and UseSentry won't always be clear to users. As SDK maintainers, we know that you either initialise the SDK with the static SentrySdk.Init or you use one of the UseSentry extension methods to initialise it via one of our integrations... but that's insider knowledge so when we phrase instructions as we have done above, I worry that might confuse other SDK users.

Not sure how to handle this. Potentially we could document this somewhere centrally (in a FAQ or something) and refer back to it whenever relevant. That might be messy though.

Alternatively we describe the difference we're actually talking about rather than just referring to Init/UseSentry as shorthand for the different app models that Sentry supports.

@ric-oliv thoughts? You've got reasonably fresh eyes for this so maybe you're more objective than me still.