Repository navigation
docs(dotnet): Document release and environment resolution for SDK 7.0.0 - #19960
Conversation
Describe how the .NET SDK 7.0.0 picks its default release and environment: - Release: SENTRY_RELEASE, then the app package on Android, iOS and Mac Catalyst, or the entry assembly elsewhere. - Environment: code or configuration, then SENTRY_ENVIRONMENT, then the host environment in ASP.NET Core, Blazor WebAssembly and Google Cloud Functions, then debug or production. - Scope.Environment now applies to every kind of telemetry, and null clears it. Refs getsentry/sentry-dotnet#5709 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
|
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Services awaiting deployment · Rollout details
Mention |
<!-- 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>
Co-authored-by: Ricardo Colombo Oliveira <github@ricoliv.com>
ASP.NET Core and Generic Host apps only report the host environment when they start Sentry with UseSentry. Apps that call SentrySdk.Init instead fall back to debug or production, so say so in the Environment option. Also spell "lowercases" the way the migration guide and the Generic Host guide do, and drop two trailing spaces. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
ric-oliv
left a comment
There was a problem hiding this comment.
The NLog guide has its own set-release and set-environment includes (dotnet.nlog.mdx), so its Releases and Environments pages don't pick up any of this. On the preview, the NLog Releases page still says the SDK "will first look at the entry assembly" and doesn't mention SENTRY_RELEASE. That was already wrong in 6.x, and now it contradicts the Options page on the same guide.
The NLog includes could keep their NLog.config samples and point to the option for the order, the way this PR does in set-environment/dotnet.mdx. It doesn't need to block this PR, though. A follow-up against dotnet-v7 works too if you'd rather keep this one focused. What do you think?
…entry assembly link Co-authored-by: ric-oliv <ric-oliv@users.noreply.github.com> Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…olution order The NLog includes described the 6.x release lookup and didn't mention SENTRY_RELEASE, contradicting the Options page in the same guide. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks @ric-oliv! All three suggestions are applied in 5277c63. I folded the NLog fix into this PR too (e940ad7). The NLog Releases and Environments pages keep their |
Keeps the deletion of the NLog-specific set-release and set-environment includes. The NLog guide now uses the generic .NET includes, which carry the release and environment text from #19960. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thanks! Your three suggestions were already in, so I resolved those threads. On the NLog Releases and Environments pages: #19925 deletes the NLog-specific |
## DESCRIBE YOUR PR This updates the .NET docs for sentry-dotnet 7.0.0, which has been on NuGet since 2026-11-12. Each change was reviewed in its own PR against the `dotnet-v7` branch, so the 7.x docs go live together: - #20311 docs(dotnet): Add a Generic Host guide for SDK 7.0.0 - #20642 docs(dotnet): Add supported versions to the MAUI guide for SDK 7.0.0 - #19960 docs(dotnet): Document release and environment resolution for SDK 7.0.0 - #19961 docs(dotnet): Update Microsoft.Extensions.Logging guide for SDK 7.0.0 - #19924 docs(dotnet): Update OTLP propagation docs for SDK 7.0.0 - #19925 docs(dotnet): Update logging docs for SDK 7.0.0 - #20715 docs(dotnet): Document ClearProviders() in the ASP.NET Core guide for SDK 7.0.0 - #20752 docs(dotnet): Tell .NET Framework apps to install Microsoft.Extensions.Logging for SDK 7.0.0 - #20743 docs(dotnet): Document NLog's MinimumLogLevel for SDK 7.0.0 - #20742 docs(dotnet): Link the Generic Host guide from the other .NET pages for SDK 7.0.0 - #20689 docs(dotnet): Update the 7.x migration guide for 7.0.0 - #20780 docs(dotnet): Fix Serilog flushing, Serilog usings and the Azure Functions package for SDK 7.0.0 - #20781 docs(dotnet): Fix the .NET logs and metrics examples and other pages for SDK 7.0.0 ### Issues this closes Closes getsentry/sentry-dotnet#5710 The other docs issues for 7.0.0 were closed when their PRs merged into `dotnet-v7`. ### Before merging - [x] sentry-dotnet 7.0.0 is on NuGet. - [x] The release candidate alert is gone from `includes/dotnet-v7-migration-overview.mdx`. - [x] The links that #20311, #19961 and #19925 left for after the other PRs merge are in. - [x] `master` is merged into `dotnet-v7`, and the Vercel preview looks right. - [x] This description has a `Closes` line for every issue that's still open. ## 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-13 - [ ] Other deadline: YYYY-MM-DD - [ ] No deadline: Not urgent, can wait up to 1 week+ --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: James Crosswell <jamescrosswell@users.noreply.github.com> Co-authored-by: ric-oliv <ric-oliv@users.noreply.github.com> Co-authored-by: ric-oliv <5938598+ric-oliv@users.noreply.github.com> Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>
Note
This targets
dotnet-v7, which collects the .NET docs for sentry-dotnet 7.0.0. #20641 merges that branch intomasterwhen 7.0.0 ships, so this PR can merge intodotnet-v7as soon as it's approved.DESCRIBE YOUR PR
Documents how the .NET SDK resolves its default release and environment from 7.0.0 on (getsentry/sentry-dotnet#5671 and getsentry/sentry-dotnet#5703). The .NET docs aren't versioned, so the text is written for 7.x, with a short "Before version 7.0.0" note where a 6.x reader would otherwise be misled.
Release:SENTRY_RELEASEis read first, then the app package on Android, iOS and Mac Catalyst, or the entry assembly elsewhere. Removes the JavaScript SDK'swindow.SENTRY_RELEASEaside.Environment: the precedence (code or configuration,SENTRY_ENVIRONMENT, then the host environment in ASP.NET Core, Blazor WebAssembly and Google Cloud Functions, thendebug/production), the casing rule andAdjustStandardEnvironmentNameCasing, and thatScope.Environmentnow applies to every kind of telemetry, withnullclearing it.set-releaseinclude): adds the Android, iOS and Mac Catalyst default,<package-id>@<version>+<build>, and where its parts come from.set-environmentinclude): points to the option for the defaults, and shows overriding the environment on the scope.Closes getsentry/sentry-dotnet#5709
Notes for review
All of this was checked against the
version7source rather than the issue text. Where the two differ:#if ANDROID || __IOS__, and the Mac Catalyst SDK defines__IOS__.Scope.ReleaseandScope.Distributiongoing away means release and distribution "can only be set onSentryOptions". That's not quite right:SentryEvent, transactions and check-ins still have their ownRelease. These pages don't cover that, and the removal belongs in the migration guide (Write the 7.x section of the .NET migration guide sentry-dotnet#5710).UseSentryoverload, including theISentryBuilderones that gRPC apps use, so the docs just say "ASP.NET Core". Generic Host apps (worker services) are listed ahead of Add a non-logging way to initialise Sentry in generic host apps sentry-dotnet#5572, which is expected to map the host environment the same way and merge before 7.0.0. Check that it does before merging this. MAUI still falls back todebug/production.Left unchanged:
ISentryBuilderoverloads starting to read the host environment. Add one if you think 6.x readers need it.options.mdxstay inside theReleaseandEnvironmententries, so they shouldn't conflict with docs(dotnet): Document OnCrashedLastRun for iOS and Mac Catalyst #19897 (Hooks) or docs(dotnet): Document TraceIgnoreStatusCodes #19898 (tracing options).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.SLA
Thanks in advance for your help!
PRE-MERGE CHECKLIST
Make sure you've checked the following before merging your changes:
🤖 Generated with Claude Code