Skip to content

docs(dotnet): Document release and environment resolution for SDK 7.0.0 - #19960

Merged
jamescrosswell merged 8 commits into
dotnet-v7from
dotnet-v7-release-environment
Nov 11, 2026
Merged

jamescrosswell merged 8 commits into
dotnet-v7from
dotnet-v7-release-environment

Conversation

@jamescrosswell

@jamescrosswell jamescrosswell commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

Note

This targets dotnet-v7, which collects the .NET docs for sentry-dotnet 7.0.0. #20641 merges that branch into master when 7.0.0 ships, so this PR can merge into dotnet-v7 as 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.

  • Options > Release: SENTRY_RELEASE is read first, then the app package on Android, iOS and Mac Catalyst, or the entry assembly elsewhere. Removes the JavaScript SDK's window.SENTRY_RELEASE aside.
  • Options > Environment: the precedence (code or configuration, SENTRY_ENVIRONMENT, then the host environment in ASP.NET Core, Blazor WebAssembly and Google Cloud Functions, then debug/production), the casing rule and AdjustStandardEnvironmentNameCasing, and that Scope.Environment now applies to every kind of telemetry, with null clearing it.
  • Releases page (set-release include): adds the Android, iOS and Mac Catalyst default, <package-id>@<version>+<build>, and where its parts come from.
  • Environments page (set-environment include): 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 version7 source rather than the issue text. Where the two differ:

  • The app-package release default also applies on Mac Catalyst, not just Android and iOS. It sits behind #if ANDROID || __IOS__, and the Mac Catalyst SDK defines __IOS__.
  • The issue says Scope.Release and Scope.Distribution going away means release and distribution "can only be set on SentryOptions". That's not quite right: SentryEvent, transactions and check-ins still have their own Release. 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).
  • The host-environment mapping covers every ASP.NET Core UseSentry overload, including the ISentryBuilder ones 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 to debug/production.

Left unchanged:

  • The Google Cloud Functions guide already says "Environment is automatically set (IHostingEnvironment)". That wasn't true in 6.x, but it is from 7.0.0. The ASP.NET Core guide's Environment section is also correct for 7.x. The Blazor WebAssembly guide doesn't mention the environment, and there's no gRPC page.
  • There's no "Before version 7.0.0" note for Blazor WebAssembly, Google Cloud Functions and the ISentryBuilder overloads starting to read the host environment. Add one if you think 6.x readers need it.
  • Edits to options.mdx stay inside the Release and Environment entries, 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-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+

SLA

  • Teamwork makes the dream work, so please add a reviewer to your PRs.
  • Please give the docs team up to 1 week to review your PR unless you've supplied a deadline.

Thanks in advance for your help!

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

🤖 Generated with Claude Code

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>
@vercel

vercel Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

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

Project Deployment Actions Updated
sentry-docs Ready Ready Preview Nov 10, 2026 8:52pm UTC
1 Skipped Deployment
Project Deployment Actions Updated
develop-docs Ignored Ignored Preview Nov 10, 2026 8:52pm UTC

Request Review

@codeowner-assignment
codeowner-assignment Bot requested a review from a team October 13, 2026 22:45
@github-actions github-actions Bot added the Priority: Urgent Docs review is needed immediately for an urgent deadline label Oct 13, 2026
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@cursor

cursor Bot commented Oct 14, 2026 •

Copy link
Copy Markdown
Contributor

Services awaiting deployment · Rollout details

Status Service Environment
⚪ Not deployed yet sentry-docs

Mention @rollout in a comment to update the plan.

ric-oliv added a commit that referenced this pull request Oct 29, 2026
<!-- 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 ric-oliv left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

jamescrosswell and others added 2 commits November 11, 2026 09:44
…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>
@jamescrosswell

Copy link
Copy Markdown
Collaborator Author

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 NLog.config samples and now link to the Release and Environment options for the resolution order, so they no longer describe the 6.x lookup.

@jamescrosswell
jamescrosswell merged commit d94c3eb into dotnet-v7 Nov 11, 2026
12 checks passed
@jamescrosswell
jamescrosswell deleted the dotnet-v7-release-environment branch November 11, 2026 02:54
jamescrosswell added a commit that referenced this pull request Nov 11, 2026
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>
@jamescrosswell

Copy link
Copy Markdown
Collaborator Author

Thanks! Your three suggestions were already in, so I resolved those threads. On the NLog Releases and Environments pages: #19925 deletes the NLog-specific set-release and set-environment snippets, so once it merges, the NLog guide uses the pages this PR updated.

ric-oliv added a commit that referenced this pull request Nov 15, 2026
## 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>

This branch was successfully deployed

1 active deployment
Preview – sentry-docs — e940ad7c Deployed Nov 10, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Priority: Urgent Docs review is needed immediately for an urgent deadline

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Document the release and environment changes for v7.0.0

2 participants