Repository navigation
docs(dotnet): Update Microsoft.Extensions.Logging guide for SDK 7.0.0 - #19961
jamescrosswell wants to merge 5 commits into
Conversation
In 7.0.0 the Microsoft.Extensions.Logging integration no longer initializes the SDK. The guide now initializes Sentry with SentrySdk.Init before AddSentry(), limits the Logging:Sentry section to the levels it still accepts, drops InitializeSdk, documents AddLogEntryFilter and the standard-error warning, and fixes the ASP.NET Core options hierarchy. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
1 Skipped Deployment
|
github-actions
Bot
added
the
Priority: Urgent
Co-authored-by: James Crosswell <jamescrosswell@users.noreply.github.com>
|
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: Mention PlanWhat changedVisitors to RiskBroken 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 effectThis 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 watchWatch 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.
If a new error title appears, inspect that event for code-tab or MDX render frames. Not observableThe live HTML of the two pages. Telemetry cannot show whether |
…s-logging Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
sentry-dotnet 7.0.0 adds Sentry.Extensions.Hosting, whose UseSentry initializes Sentry for generic host apps and adds the logging integration (getsentry/sentry-dotnet#5739). Logging.AddSentry() no longer registers IHub, ISentryClient or Func<IHub> (#5740), and it adds Sentry's providers back after ClearProviders() (#5776, #5789, #5821). The guide now shows UseSentry for generic host apps, and SentrySdk.Init with AddSentry() for apps without a host and for .NET Framework apps on Host.CreateApplicationBuilder(), with the HubAdapter registration for apps that inject the hub. It adds the ClearProviders() rule, the top-level Sentry section next to Logging:Sentry, and EnableLogs for UseSentry. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
<!-- Keep the urgency section so automation can prioritize this PR. You may delete other sections you don't need. --> ## DESCRIBE YOUR PR This PR adds the migration guide for version 7 of the Sentry SDK for .NET, ready for the public release candidate, `7.0.0-rc.2`. It follows the pattern of the Flutter v10 guide from #19390: - A full guide at `/platforms/dotnet/migration/v6-to-v7/`, built from one include per change in `includes/migration/dotnet-v7/`. - An interactive checklist at `/platforms/dotnet/migration/v6-to-v7/interactive/` that renders the same includes through `<MigrationGuide migration="dotnet-v7" />`. - An agent prompt callout that points at the guide's `.md` URL. - A "Migrating to 7.x" section at the top of the existing .NET migration page, which links to both. Both pages live under `common/`, so they render for every .NET guide, such as ASP.NET Core, MAUI, WPF and Serilog. Xamarin uses a separate SDK, so the new pages exclude it. I didn't move the 6.x, 4.x and 3.x sections, so every existing URL and anchor keeps working and the PR needs no redirects. To register the collection, the PR adds `dotnet-v7` to the `MIGRATIONS` map in the `MigrationGuide` component and to the validator's `COLLECTIONS` map, with specs for both. These changes in `src/components/migrationGuide/` and `scripts/` touch code that the JavaScript and Flutter guides share, so they need an approval from the docs team. For reference, msonnb approved the last change to the component in #19729, and andreiborza approved the JavaScript interactive guide that added it in #19076. The checklist shows one step only on the MAUI guide. Every other step applies to every .NET guide, because .NET apps combine integrations, such as a Serilog sink in an ASP.NET Core app. I checked the guide against `7.0.0-rc.2` from nuget.org and against the `version7` branch at getsentry/sentry-dotnet@a56c63455. The guide describes 7.0.0. Where rc.2 still behaves differently, the release candidate note at the top says so. ### Why this goes live during the release candidate I'd like to merge this as soon as it's approved, while 7.0 is still in release candidate. 7.0.0 GA is planned for 2026-11-30. People who try the release candidate need the guide now, and the agent prompt needs a published `.md` URL to point at. Two develop-docs rules pull in different directions here. [Managing Linear projects](https://develop.sentry.dev/sdk/getting-started/playbooks/coordination/managing-linear-projects/#visibility-for-major-releases) says docs "MUST NOT go live before the SDK ships". The [breaking changes playbook](https://develop.sentry.dev/sdk/getting-started/playbooks/sdk-lifecycle/breaking-changes/#6-update-docs-and-changelog) says to publish the migration guide "before or alongside the major release". I read the first rule as protecting users from docs for code they can't get. Version `7.0.0-rc.2` is public on nuget.org, and the guide's first block says it's a release candidate and names that version. Other SDKs made the same call: - The Python 2.0 guide merged on 2024-02-28, while only the `2.0.0a1` alpha was out. Its note at the top said so. - The JavaScript v11 guide merged on 2026-09-08 with `11.0.0-beta.1` out, and its interactive version followed on 2026-09-11. - The Flutter v10 guide merged on 2026-10-05 with `10.0.0-rc.2` out, four days before 10.0.0. ### The release candidate note The guide opens with one `<Alert>`. It says there is no stable 7.0 yet, names `7.0.0-rc.2`, and says the rest of the .NET docs describe 6.x until 7.0.0 ships. It also covers what only the release candidate has: - `Logging.AddSentry()` after `ClearProviders()` doesn't add Sentry's logger providers back yet. That came with getsentry/sentry-dotnet#5776, after rc.2. - `DecompressionMethods` still includes Brotli, which getsentry/sentry-dotnet#5816 takes out of the default after rc.2. The note says how to leave it out until then. - An ASP.NET Core app that sends `ILogger` entries through NLog crashes with `Debug` on, tracked in getsentry/sentry-dotnet#5822. The guide's verify step turns `Debug` on, so the note says to leave it off in those apps. - Its `net11.0` builds depend on the .NET 11 release candidate versions of three `Microsoft.Extensions` packages. The rest of the guide describes 7.0.0 as released. At GA, I'll delete that one block from `includes/dotnet-v7-migration-overview.mdx`, and nothing else needs to change. ### What this PR leaves to other PRs This PR only adds the guide and what it needs. The reference pages are in other PRs, and this one doesn't need any of them to merge first: - Logs and the logging integrations: #19925 - `Microsoft.Extensions.Logging` and ASP.NET Core: #19961 - OpenTelemetry propagation: #19924 - Release and environment: #19960 - Hangfire monitor schedules: #19781 Three links in the guide point to the "Apps That Call UseSentry" sections that #19925 adds to the Serilog, NLog and log4net guides. Until #19925 merges, they open those guides at the top, and the migration guide sums up the same setups itself. There is no page for the new `Sentry.Extensions.Hosting` package yet. I'll link it from the guide once that page exists. Refs https://linear.app/getsentry/issue/NET-860 Refs getsentry/sentry-dotnet#5710 ## 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. - [x] Urgent deadline (GA date, etc.): 2026-11-30 - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: Not urgent, can wait up to 1 week+ ## PRE-MERGE CHECKLIST _Make sure you've checked the following before merging your changes:_ - [ ] Checked Vercel preview for correctness, including links - [ ] PR was reviewed and approved by any necessary SMEs (subject matter experts) - [ ] PR was reviewed and approved by a member of the [Sentry docs team](https://github.com/orgs/getsentry/teams/docs) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: James Crosswell <jamescrosswell@users.noreply.github.com> Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>
There was a problem hiding this comment.
Looks good overall!
One structural suggestion: what do you think about not documenting the Generic Host on this page? Now that it has its own integration, I'd treat it like ASP.NET Core and MAUI and add a "skip this setup" note that links to the Generic Host guide from #20311. This page would then only cover apps that call SentrySdk.Init and AddSentry() themselves.
#20311 already covers most of what this PR adds for the Generic Host: UseSentry on both builders, not calling AddSentry() as well, the Sentry section, ClearProviders(), the .NET Framework fallback with HubAdapter, and EnableLogs. Keeping both means two copies to keep in sync. It also settles line 23. On this page logs are always sent, so there's no split between SentrySdk.Init and UseSentry to explain here. #20311 should pick that up, though. An app that replaces SentrySdk.Init with UseSentry stops sending ILogger entries as logs until it sets EnableLogs.
A few things to watch when moving it out:
- The link 404s until #20311 merges, so that one needs to land first.
- Generic host apps that followed this page on 6.x are the readers most likely to land here after upgrading, so the skip note should name them.
- I'd keep the
Logging:Sentrypart of Logging Configuration. Apps that callSentrySdk.InitandAddSentry()hit the same three-key rule, so a leftoverLogging:Sentry:Dsnstill fails at startup. Only the top-levelSentrysection moves out. ClearProviders()isn't Generic Host only. ASP.NET Core'sUseSentryadds the same providers and logs the same warning, and the ASP.NET Core guide doesn't mention it. I'd either keep a short version here or move it to that guide.AddLogEntryFilteron theUseSentryoptions isn't in #20311 yet, so it'd need to move there. It's defined onSentryHostOptions, so it works with ASP.NET Core's options too.- Once the .NET Framework tab moves out, only apps that build their own
ServiceCollectionneed theHubAdapterblock. Keep it if Other Apps covers them, otherwise it can go.
Two smaller things inline. The 7.0.0 note is the one I'd change before merging.
| } | ||
| ``` | ||
|
|
||
| `LogLevel` controls which entries are sent as [structured logs](logs/). `MinimumBreadcrumbLevel` and `MinimumEventLevel` are described under [Options](#options). |
There was a problem hiding this comment.
Default here only affects structured logs, but a category entry also drops breadcrumbs and events for that category. A rule like "Noisy": "Warning" under Logging:Sentry:LogLevel is more specific than the _ => true filter the integration adds for the events provider, so MEL picks it for both providers. I checked with a small MEL-only app that mirrors the two providers (both with the Sentry alias): an Information entry from Noisy.Thing reached neither. 6.x behaves the same, so this is only wording:
| `LogLevel` controls which entries are sent as [structured logs](logs/). `MinimumBreadcrumbLevel` and `MinimumEventLevel` are described under [Options](#options). | |
| `LogLevel:Default` controls which entries are sent as [structured logs](logs/). A category entry under `LogLevel`, such as `"Microsoft": "Warning"`, also filters breadcrumbs and events from that category. `MinimumBreadcrumbLevel` and `MinimumEventLevel` are described under [Options](#options). |
There was a problem hiding this comment.
Bugger... that's true - it's definitely not what we'd prefer.
We have SentryOptions.MinimumBreadcrumbLevel and SentryOptions.MinimumEventLevel and we don't really want the confusion/complexity of people potentially having conflicting rules in code vs config and then having to explain to them how those things get resolved (the logic is onerously complex). Your comment here illustrates that it's even more complex than I thought it was.
I think this is technically a bug - our preferred design would be that logging configuration would have no impact on which breadcrumbs and events get captured. Relatively hard to fix and also probably not a super high priority as it only bites in edge cases and I think there's a good chance we deprecate breadcrumbs in any case.
There was a problem hiding this comment.
Co-authored-by: Ricardo Colombo Oliveira <github@ricoliv.com>
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
UseSentryfrom the newSentry.Extensions.Hostingpackage instead (getsentry/sentry-dotnet#5739). This updates the parts of getsentry/sentry-dotnet#5706 that #19925 leaves out:UseSentryfromSentry.Extensions.Hosting, withoutLogging.AddSentry().Host.CreateApplicationBuilder(), callSentrySdk.Init, thenAddSentry(). If they injectIHub,ISentryClientorFunc<IHub>, they register them withHubAdapter.Instance, becauseAddSentry()no longer does (feat(mel)!: Logging.AddSentry() no longer registers IHub or ISentryClient sentry-dotnet#5740).ClearProviders(): callUseSentryafter it, or callLogging.AddSentry()after it to add Sentry's providers back. Not when Serilog, NLog or log4net already sendsILoggerentries 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).AddSentry(...),InitializeSdk, and SDK settings underLogging:Sentry. Documents whatLogging:Sentrystill accepts, the top-levelSentrysection thatUseSentryreads,EnableLogsforUseSentry, andAddLogEntryFilter.SentryAspNetCoreOptionsnow extendsSentryHostOptions, notSentryLoggingOptions.Closes getsentry/sentry-dotnet#5706
Notes for review
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.SentrySdk.InitorUseSentry. TheLogging:Sentrystartup errors and the obsoleteDsn/InitializeSdk/AddSentry(dsn)errors nameUseSentryfromSentry.Extensions.Hosting,SentrySdk.Initand theSentrysection. TheDebugwarnings cover a redundantAddSentry(), its ignored options, and providers removed byClearProviders(). The Configure section answers each of them.origin/version7(f5f063e99):Host.CreateDefaultBuilder+UseSentryand the .NET FrameworkSentrySdk.Init+Host.CreateApplicationBuildersnippets also compile on net48, andHost.CreateApplicationBuilder().UseSentry()doesn't (CS1929).HubAdapterlines, a hosted service that injectsIHubfails withUnable to resolve service for type 'Sentry.IHub' while attempting to activate 'Worker'. With them, all three types resolve toHubAdapterand captures through each reach the SDK.UseSentry, thenClearProviders(), thenAddSentry()sendsLogErrorentries again, with the host'sMinimumEventLevel. Options passed to thatAddSentry()are ignored, with a diagnostic warning. WithoutAddSentry(), nothing reaches Sentry and theDebugwarning appears.ClearProviders()beforeUseSentryworks.UseSentrywith a laterAddSentry()sends each error once and warns that the call has no effect.Logging:Sentry:DsnandLogging:Sentry:EnableLogsfail at startup with both setups.LogLevel,MinimumBreadcrumbLevelandMinimumEventLevelload.SentrySdk.Init, and off withUseSentryuntilEnableLogsistrue.Filterswas always internal. The page showsAddLogEntryFilter, which now also works on theUseSentryoptions.SentryHostOptionsis still inSentry.Extensions.Loggingonversion7.AddSentry()afterSentrySdk.Initinitializes 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 inAddSentry(...)instead.master. This PR leaves theSentryprefix 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-DDwith the due date. You can update this information later by editing the PR description.🤖 Generated with Claude Code