Skip to content

docs(dotnet): Add 6.x to 7.x migration guide for 7.0.0-rc.2 - #20143

Merged
ric-oliv merged 8 commits into
masterfrom
docs/dotnet-7-migration-guide
Oct 29, 2026
Merged

ric-oliv merged 8 commits into
masterfrom
docs/dotnet-7-migration-guide

Conversation

@ric-oliv

@ric-oliv ric-oliv commented Oct 21, 2026 •

Copy link
Copy Markdown
Member

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 says docs "MUST NOT go live before the SDK ships". The breaking changes playbook 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:

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:

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.

  • 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

Version 7 of the .NET SDK moves initialization out of the logging integrations, removes SentryOptions.EnableLogs, adds Sentry.Extensions.Hosting and raises the mobile and MAUI minimum to .NET 10. Upgraders need a guide with before and after code for each change while 7.0 is in release candidate.

Follows the Flutter v10 pattern: a full guide and an interactive checklist built from one include per change, plus an agent prompt. An alert at the top names the current release candidate and comes out at GA. The dotnet-v7 collection is registered in the MigrationGuide component and the migration item validator.

Refs NET-860

Refs getsentry/sentry-dotnet#5710

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

vercel Bot commented Oct 21, 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 Oct 29, 2026 9:15am UTC
1 Skipped Deployment
Project Deployment Actions Updated
develop-docs Ignored Ignored Preview Oct 29, 2026 9:15am UTC

Request Review

@linear-code

linear-code Bot commented Oct 21, 2026

Copy link
Copy Markdown

NET-860

Reword the overview, the supported .NET versions, the CS0619 errors and the IHub registration as suggested in review. The overview now says the Sentry.OpenTelemetry package as a whole is obsolete and will be removed, not only the span processor setup.

The suggestions go in with a typo fix, US spelling and one run-on sentence split in two. The OpenTelemetry paragraph keeps the AddSentry() and UseOpenTelemetry() names so readers can match it to the warning they get. The EnableLogs section is unchanged until the discussion on getsentry/sentry-dotnet#5755 settles where EnableLogs lives.

Refs NET-860

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…learProviders

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
getsentry/sentry-dotnet#5755 closed without moving the ILogger
integration out of UseSentry, so EnableLogs stays on the host options.
Logging.AddSentry() can now add Sentry's logger providers back after
ClearProviders(), and DecompressionMethods no longer includes Brotli.

Rewrite the EnableLogs section around what turns logs on in each kind
of app, update the ClearProviders and redundant AddSentry advice, and
add an item for the Brotli default. Sum up the Serilog, NLog and log4net
setups in the guide, so it doesn't depend on #19925 merging first. The
release candidate note lists the two places where rc.2 still differs.

Refs NET-860

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ric-oliv ric-oliv changed the title docs(dotnet): Add 6.x to 7.x migration guide docs(dotnet): Add 6.x to 7.x migration guide for 7.0.0-rc.2 Oct 28, 2026
@ric-oliv
ric-oliv marked this pull request as ready for review October 28, 2026 13:33
@codeowner-assignment
codeowner-assignment Bot requested a review from a team October 28, 2026 13:33
@cursor

cursor Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Checks were inconclusive · Rollout details

Status Service Environment
❔ Inconclusive so far sentry-docs production

The check did not reach a verdict. Mention @rollout in a comment to update the plan, or wait for the next deploy.

An independent review against 7.0.0-rc.2 found that a 6.x Serilog or NLog
package left next to Sentry 7 usually fails silently. It adds fine, then
throws MissingMethodException on every entry, which the logging framework
swallows. The guide said the Serilog sink fails as soon as the app adds
it, which only happens with WriteTo.Sentry() and no arguments. A dsn in
Serilog's JSON configuration surfaces as a TargetInvocationException,
with the explanation in its inner exception.

rc.2 still accepts Brotli by default, so the release candidate note says
how to leave it out until the next release. The overview's logs bullet
also names Logging.AddSentry() after SentrySdk.Init, and says the
Sentry.OpenTelemetry setup has been obsolete since 6.12.0.

Refs NET-860

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ric-oliv

Copy link
Copy Markdown
Member Author

@jamescrosswell I've updated the guide, and the PR is now specific to rc.2. The note at the top lists where rc.2 still behaves differently from what the guide describes.

Since option 4 was dropped in getsentry/sentry-dotnet#5755, the EnableLogs section now follows your three points. There's also a new item for the Brotli default from getsentry/sentry-dotnet#5816, and the guide sums up the Serilog, NLog and log4net setups itself, so it can merge before #19925.

Mind taking another look?

@coolguyzone coolguyzone left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Looks good!

Co-authored-by: Alex Krawiec <alex.krawiec@sentry.io>
The Removed and Internal APIs section had only one subsection, Other Removed and
Internal APIs, so the two headings repeated each other. Keep the one that matches
the item's title, so its link stays the same.

Refs NET-860

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@ric-oliv
ric-oliv merged commit ee268f0 into master Oct 29, 2026
29 checks passed
@ric-oliv
ric-oliv deleted the docs/dotnet-7-migration-guide branch October 29, 2026 10:20
ric-oliv added a commit that referenced this pull request Nov 3, 2026
<!-- Keep the urgency section so automation can prioritize this PR. You
may delete other sections you don't need. -->

## DESCRIBE YOUR PR

Version `7.0.0-rc.3` of the Sentry SDK for .NET is out, so this PR
updates the release candidate note at the top of the 7.x migration guide
from #20143.

The note listed three things that work differently on `7.0.0-rc.2`. All
three fixes are in rc.3, so I removed the list:

- `Logging.AddSentry()` after `ClearProviders()` adds Sentry's logger
providers back, from getsentry/sentry-dotnet#5776.
- `DecompressionMethods` leaves out Brotli by default, from
getsentry/sentry-dotnet#5816.
- An ASP.NET Core app that sends `ILogger` entries through NLog no
longer crashes with `Debug` on, from getsentry/sentry-dotnet#5823.

The note no longer names a release candidate. It points at the latest
one on NuGet instead, so another release candidate before GA won't need
a docs PR.

I also fixed two gaps in the NU1605 paragraph:

- `Sentry.AspNetCore.Blazor.WebAssembly` depends on the .NET 11 version
of `Microsoft.AspNetCore.Components.WebAssembly`, so a Blazor
WebAssembly app that pins 10.0.x fails to restore too. The paragraph now
names that package.
- An app that pins an older .NET 11 release candidate, such as
`11.0.0-rc.2`, fails the same way as one that pins 10.0.x. The paragraph
now says "an older version" and that the error message shows the version
to use.

I checked this against `7.0.0-rc.3` from nuget.org:

- The default `DecompressionMethods` is `GZip, Deflate`.
- A .NET 11 app fails to restore with NU1605 when it pins
`Microsoft.Extensions.Http` 10.0.0 or 11.0.0-rc.2.
- A Blazor WebAssembly app fails the same way when it pins
`Microsoft.AspNetCore.Components.WebAssembly` 10.0.0.
- All three fix PRs are in the `7.0.0-rc.3` tag.

No other page in the guide names a release candidate version. The whole
alert still comes out at 7.0.0 GA.

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.

- [ ] Urgent deadline (GA date, etc.): YYYY-MM-DD
- [ ] Other deadline: YYYY-MM-DD
- [x] 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>
jamescrosswell added a commit that referenced this pull request Nov 10, 2026
> [!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

Adds a Generic Host guide for `Sentry.Extensions.Hosting`, which
sentry-dotnet 7.0.0 adds (getsentry/sentry-dotnet#5739). In 7.0.0,
`Logging.AddSentry()` no longer initializes the SDK. Worker services,
console apps on the generic host, Windows services and Azure Functions
(isolated) apps call `UseSentry` from this package instead. The page is
written for 7.x. The docs aren't versioned, so this goes live with the
rest of the 7.0.0 docs.

The guide follows the quick start template from
#19990 and covers:

- `UseSentry` on `IHostApplicationBuilder` and `IHostBuilder`, the
`Sentry` and `Logging:Sentry` sections, and why not to call
`Logging.AddSentry()` as well
- the host environment, `"Dsn": ""`, and when the SDK starts (`Build()`)
and closes (`ApplicationStopped`)
- `ClearProviders()` ordering (getsentry/sentry-dotnet#5772,
getsentry/sentry-dotnet#5776, getsentry/sentry-dotnet#5789,
getsentry/sentry-dotnet#5821)
- ASP.NET Core and MAUI apps, and the static `UseSentry` call that
Aspire's `AddServiceDefaults` needs
- the .NET Framework gap, with the `SentrySdk.Init` and
`Logging.AddSentry()` fallback and its `HubAdapter.Instance`
registrations (getsentry/sentry-dotnet#5740)
- replacing `SentrySdk.Init`, briefly. The migration guide
(#20143) covers upgrades.

It also adds
`platform-includes/configuration/config-intro/dotnet.extensions-hosting.mdx`,
so the guide's Options page starts with `UseSentry` instead of
`SentrySdk.Init`.

Closes getsentry/sentry-dotnet#5707

### Notes for review

- **Registration.** A new .NET guide only needs its `index.mdx`. The
platform key `dotnet.extensions-hosting` comes from the folder name,
guides without `sidebar_order`, like the other .NET guides, are listed
by title, and the icon falls back to the .NET one, as for the
Microsoft.Extensions.Logging, Serilog and NLog guides. The page is new,
so it needs no redirects.
- **Package version.** The install snippets use
`packages.version('sentry.dotnet')`, because the release registry has no
`sentry.dotnet.extensions.hosting` entry yet. Until 7.0.0 is out, the
preview shows 6.12.1, which doesn't exist for this package. Once the
registry has the package, switch to its own key. The `sdk:` frontmatter
already uses `sentry.dotnet.extensions.hosting` (from `Constants.cs`).
Without a registry entry, the page just has no package details box.
- **Shared includes that render wrongly for
`dotnet.extensions-hosting`.** I left them alone, since other PRs own
them:
- `platform-includes/logs/setup/dotnet.mdx` falls into the
`SentrySdk.Init` section instead of `UseSentry` with `EnableLogs`.
#19925 is adding the key to the host sections.
- `platform-includes/logs/options/dotnet.mdx` shows the generic
`EnableLogs` text and leaves out "Configure Microsoft.Extensions.Logging
Filters". Same PR.
- `platform-includes/logs/usage/dotnet.mdx` shows only the
`SentrySdk.Logger` APIs. The key belongs in the `ILogger` section too.
- `platform-includes/logs/requirements/dotnet.mdx` says logs need SDK
version 5.14.0. This package starts at 7.0.0.
- **Additions to the brief from the `version7` source:**
- `"Dsn": ""` turns the SDK off, but `SENTRY_DSN` still wins over an
empty `Dsn` (`SettingLocator.GetDsn`). The page says so.
- `Logging:Sentry` only accepts `LogLevel`, `MinimumBreadcrumbLevel` and
`MinimumEventLevel`. Any other key makes `Build()` throw
`NotSupportedException`. With no DSN anywhere, `Build()` throws
`ArgumentNullException`.
- Calling `Sentry.AspNetCore`'s `UseSentry` twice still sends each error
twice (a follow-up in getsentry/sentry-dotnet#5739). The Aspire section
says not to call it again in `Program.cs`.
- **Azure Functions** gets one line in the intro. The Azure Functions
guide still shows `logging.AddSentry(...)`. #19925
owns it.
- **Links to add once the other PRs merge:**
- Microsoft.Extensions.Logging guide: send generic host apps here, from
the "If you use a host integration such as ASP.NET Core or MAUI"
paragraph. Its `Sentry.Samples.GenericHost` sample link belongs here
too, since the sample now calls `UseSentry`.
  - Azure Functions guide: link here from the `UseSentry` setup.
- `platform-includes/logs/integrations/dotnet.mdx`: add Generic Host to
the list.
- `docs/product/logs/getting-started/index.mdx` and
`docs/product/metrics/getting-started/index.mdx`: add Generic Host to
the .NET lists.
- Migration guide, "Generic Host Apps Call UseSentry": link to this
page.
- The sample link points at `main`, where `Sentry.Samples.GenericHost`
keeps the 6.x setup until `version7` is merged.
- The C# snippets compile against `version7`, on net10.0, and on net48
for the `IHostBuilder` example and the .NET Framework fallback. On
net48, `UseSentry` on `HostApplicationBuilder` fails with CS1929, as the
page says.

## 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+

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: Ricardo Colombo Oliveira <github@ricoliv.com>
ric-oliv added a commit that referenced this pull request Nov 13, 2026
## DESCRIBE YOUR PR

This gets the 6.x to 7.x migration guide for the Sentry SDK for .NET
ready for 7.0.0, following #20143. It targets `dotnet-v7`, so it goes
live with the rest of the 7.0.0 docs in #20641.

- Removes the release candidate alert. Its note about restore error
NU1605 still applies to .NET 11 apps on 7.0.0, so it moves to "Supported
.NET Versions and Platforms".
- Adds "Category Log Levels No Longer Filter Breadcrumbs and Events",
for getsentry/sentry-dotnet#5869. Entries under
`Logging:Sentry:LogLevel` now only filter logs, so an app that silenced
a category gets that category's breadcrumbs and events. The section
shows `AddLogEntryFilter` for apps that want the old filtering.
- Adds `GetInternalSentryOptions` to "Other Removed and Internal APIs",
for getsentry/sentry-dotnet#5862, and points to the new
`GetDiagnosticLogger()` extension on `IHub`.
- Links the Generic Host guide from #20311 and the MAUI guide's
supported versions from #20642, which are both on `dotnet-v7`.

These two SDK PRs are the only changes merged on `version7` since
7.0.0-rc.3 that affect people upgrading from 6.x.

Two things depend on how 7.0.0 ships:

- The NU1605 note assumes the `net11.0` builds depend on the stable .NET
11 packages. On `version7` today, they depend on .NET 11 RC 3.
- The `LogLevel` fix also landed on 6.x in getsentry/sentry-dotnet#5872,
which isn't released yet. The section says "6.12.1 and earlier", so it
stays correct whether or not a 6.x release ships first.

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-10-10
- [ ] 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](https://github.com/orgs/getsentry/teams/docs)

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

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>

This branch was successfully deployed

2 active (1 outdated) deployments
Preview – sentry-docs — 4bd89675 Deployed Oct 29, 2026 by vercel[bot]
Preview – develop-docs — 606b23ba Deployed Oct 21, 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.

3 participants