Navigation (.NET 11): Shell route templates and Apple page handlers by davidortinau · Pull Request #3457 · dotnet/docs-maui

davidortinau · 2026-08-06T14:46:29Z

Summary

Documents three .NET MAUI 11 Preview 7 changes:

Shell route templates: Routing.RegisterRoute accepts required, optional, defaulted, constrained, catch-all, and mixed path parameters.
NavigationPage handler on iOS and Mac Catalyst: NavigationPage uses NavigationViewHandler by default instead of NavigationRenderer, with behavior changes and a compatibility fallback.
TabbedPage handler on iOS and Mac Catalyst: TabbedPage uses TabbedViewHandler by default instead of TabbedRenderer, with preserved behavior and a compatibility fallback.

Preview 7 What's New integration is intentionally excluded and is owned by #3458.

Files changed

File	Change
`docs/fundamentals/shell/navigation.md`	Route-template syntax, constraints, registration, navigation, parameter delivery, precedence, restrictions, and sample link.
`docs/user-interface/pages/navigationpage.md`	Apple-platform handler default, lifecycle and toolbar behavior changes, and renderer fallback.
`docs/user-interface/pages/tabbedpage.md`	Apple-platform handler default, preserved functionality, and renderer fallback.
`docs/migration/custom-renderers.md`	Migration and fallback guidance for custom `NavigationRenderer` and `TabbedRenderer` subclasses.
`docs/user-interface/handlers/index.md`	.NET MAUI 11 handler table updated for `NavigationPage` and `TabbedPage` while retaining `PhoneFlyoutPageRenderer` for `FlyoutPage`.

All version-specific content is gated for >=net-maui-11.0. No TOC change is required because all articles already exist.

Source verification

The canonical source is release/11.0.1xx-preview7, not the later net11.0 branch tip.

Shell route templates

Grounded in dotnet/maui#35110, RouteTemplate.cs, Routing.cs, RouteRequestBuilder.cs, ShellNavigationManager.cs, and ShellRouteTemplatesTests.cs on the Preview 7 release branch.

Values remain strings; constraints validate but don't convert.
Path parameters are URL decoded before delivery and before constraint evaluation.
Literal routes take precedence over templates, and path values take precedence over same-name query values.
Route templates require absolute navigation in Preview 7.

NavigationPage handler

Grounded in dotnet/maui#36109 and the final release-branch registration:

handlersCollection.AddHandler<NavigationPage, NavigationViewHandler>();

The handler is unconditional on iOS and Mac Catalyst. NavigationRenderer remains available for explicit fallback. The documented migration-sensitive behavior is source-backed:

Appearing is raised before the native push; NavigatedTo is deferred until ViewDidAppear.
A page pushed after being popped receives a fresh view controller.
Secondary toolbar items use a UIMenu overflow button instead of the renderer's bottom toolbar.

TabbedPage handler

Grounded in dotnet/maui#36507 and the final release-branch registration:

handlersCollection.AddHandler<TabbedPage, TabbedViewHandler>();

The handler is unconditional on iOS and Mac Catalyst. TabbedRenderer remains available for explicit fallback.

Important Preview 7 boundary

FlyoutPage did not move to FlyoutViewHandler in Preview 7. The final release branch still contains:

handlersCollection.AddHandler(
    typeof(FlyoutPage),
    typeof(Handlers.Compatibility.PhoneFlyoutPageRenderer));

dotnet/maui#36676 merged into net11.0, but it is absent from the Preview 7 release-branch compare and isn't claimed in these docs.

Sample dependency

The route-template section uses the durable sample URL:

/samples/dotnet/maui-samples/navigation-shell-route-templates

The URL is supplied by dotnet/maui-samples#777, which is at b752d128db48e09838e574cb74d1e4901718e482 and has passed local builds plus all 12 DevFlow route checks on final MAUI 11.0.0-preview.7.26406.9.

The sample itself has been correct throughout. Every blocker on #777 has been a CI toolchain gap, and both remaining ones are now fixed and merged:

Blocker	Symptom in #777 CI	Fix	State
Packages unpublished	`NU1102` during restore	`Microsoft.Maui.Controls` `11.0.0-preview.7.26406.9` and `Microsoft.Extensions.Logging.Debug` `11.0.0-preview.7.26381.103` published to NuGet.org	Cleared
Floating SDK resolved Preview 6	`CS1705` on `Java.Interop, Version=99.61.0.0`	#778 pins `setup-dotnet` to the exact SDK `11.0.100-preview.7.26381.103`	Merged
CI selected an old Xcode	`.NET for iOS (26.5.11997-net11-p7) requires Xcode 26.6. The current version of Xcode is 26.3.`	#779, Use Xcode 26.6 in CI, changes `xcode-select` in `build-pr.yml` and `build-all.yml`	Merged

After #778 merged, the SDK-mismatch class of failure disappeared: the following #777 run had zero NU1102 and zero CS1705 errors, and build (windows-latest) passed. Only build (macos-26) remained red, solely on the Xcode version. #779 addresses exactly that, replacing Xcode_26.3.app with Xcode_26.6.app in both workflows on main.

No #777 run has yet executed with both fixes in effect — its newest result predates #779, and the branch is currently behind main. So the outstanding item is simply a definitive fresh #777 CI run.

Remaining gate, in order:

~~Merge the shared-workflow SDK pin.~~ Done in Use custom renderers in .NET MAUI #778. Restore and the Java.Interop mismatch are cleared, and Windows CI passes.
~~Merge the Xcode-selection workflow change.~~ Done in Migrating a Xamarin.Forms app to .NET MAUI #779. build-pr.yml and build-all.yml now select Xcode 26.6.
Get a definitive fresh Create an app tutorial #777 CI run with both fixes applied, then merge Create an app tutorial #777 and let the Samples Browser index the navigation-shell-route-templates slug.

Don't merge this PR until #777 merges and the sample URL resolves, otherwise the published article ships a 404 link. No docs change is needed at any step — the durable URL is already correct.

Overlap with #3117

PR #3117 also touches tabbedpage.md. The content sections don't overlap; only ms.date may require a one-line conflict resolution for whichever PR merges second.

Validation

All docs CI checks pass, including OpenPublishing, build warnings, markdownlint, preview links, PoliCheck, and CLA.
Review threads are resolved.
Moniker blocks and local anchors are balanced and valid.
Final factual and pre-push review found no issues.

Internal previews

File	Preview link
docs/fundamentals/shell/navigation.md	docs/fundamentals/shell/navigation
docs/migration/custom-renderers.md	docs/migration/custom-renderers
docs/user-interface/handlers/index.md	docs/user-interface/handlers/index
docs/user-interface/pages/navigationpage.md	docs/user-interface/pages/navigationpage
docs/user-interface/pages/tabbedpage.md	docs/user-interface/pages/tabbedpage

learn-build-service-prod · 2026-08-06T14:47:30Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-08-06T14:48:05Z

Learn Build status updates of commit 7c39c91:

✅ Validation status: passed

File	Status	Preview URL
docs/fundamentals/shell/navigation.md	✅Succeeded	View (>=net-maui-8.0)
docs/migration/custom-renderers.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/tabbedpage.md	✅Succeeded	View (>=net-maui-8.0)
docs/whats-new/dotnet-11.md	✅Succeeded	View (>=net-maui-8.0)

For more details, please refer to the build report.

learn-build-service-prod · 2026-08-06T14:49:36Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-08-06T14:49:52Z

Learn Build status updates of commit 8eb56ae:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/fundamentals/shell/navigation.md	💡Suggestion	View (>=net-maui-8.0)	Details
docs/migration/custom-renderers.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/tabbedpage.md	✅Succeeded	View (>=net-maui-8.0)

docs/fundamentals/shell/navigation.md

Line 134, Column 75: [Suggestion: learn-site-link-broken - See documentation] Link '/samples/dotnet/maui-samples/navigation-shell-route-templates' points to a learn site page that doesn't exist. Check the path or URL and update the link.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copilot

Pull request overview

Documents .NET MAUI (.NET 11 Preview 7) navigation updates by adding new guidance for Shell route templates (path parameters in Routing.RegisterRoute) and documenting the iOS/Mac Catalyst TabbedPage default switch to TabbedViewHandler, with migration/fallback steps.

Changes:

Added Shell Route templates documentation (syntax, constraints, registration, navigation, precedence, restrictions) and cross-references from related sections.
Added iOS/Mac Catalyst TabbedPage handler change documentation and a compatibility-renderer fallback snippet.
Added migration guidance for iOS TabbedPage custom renderers and summarized both features in dotnet-11.md.

Show a summary per file

File	Description
docs/whats-new/dotnet-11.md	Adds .NET 11 Preview 7 release notes entries for Shell route templates and iOS/Mac Catalyst TabbedPage handler change.
docs/user-interface/pages/tabbedpage.md	Documents the new default `TabbedPage` handler on iOS/Mac Catalyst plus an explicit compatibility-renderer fallback.
docs/migration/custom-renderers.md	Adds a migration section for iOS/Mac Catalyst `TabbedPage` custom renderer scenarios (handler mapper + fallback registration).
docs/fundamentals/shell/navigation.md	Adds a new Route templates section and updates related navigation guidance with monikered callouts and cross-references.

Copilot's findings

Files reviewed: 3/3 changed files
Comments generated: 2

learn-build-service-prod · 2026-08-06T14:55:51Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-08-06T14:56:18Z

Learn Build status updates of commit ec31d7e:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/fundamentals/shell/navigation.md	💡Suggestion	View (>=net-maui-8.0)	Details
docs/migration/custom-renderers.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/tabbedpage.md	✅Succeeded	View (>=net-maui-8.0)

docs/fundamentals/shell/navigation.md

Line 134, Column 75: [Suggestion: learn-site-link-broken - See documentation] Link '/samples/dotnet/maui-samples/navigation-shell-route-templates' points to a learn site page that doesn't exist. Check the path or URL and update the link.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

learn-build-service-prod · 2026-08-11T13:26:50Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-08-11T13:27:19Z

Learn Build status updates of commit ab53dd0:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/fundamentals/shell/navigation.md	💡Suggestion	View (>=net-maui-8.0)	Details
docs/migration/custom-renderers.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/tabbedpage.md	✅Succeeded	View (>=net-maui-8.0)

docs/fundamentals/shell/navigation.md

Line 134, Column 75: [Suggestion: learn-site-link-broken - See documentation] Link '/samples/dotnet/maui-samples/navigation-shell-route-templates' points to a learn site page that doesn't exist. Check the path or URL and update the link.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

…TabbedPage handlers Documents .NET MAUI 11 Preview 7 navigation changes: - Shell path route templates, including constraints, catch-all and mixed segments, parser restrictions, and parameter delivery. - NavigationPage and TabbedPage now use handlers on iOS and Mac Catalyst, with compatibility renderer fallback and migration guidance. - Corrects the .NET 11 handler table, which listed the superseded NavigationRenderer and TabbedRenderer for iOS and Mac Catalyst. Verified against the release/11.0.1xx-preview7 branch. FlyoutPage still uses PhoneFlyoutPageRenderer on iOS and Mac Catalyst and is unchanged here. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: d3a19c75-df1e-4d74-bfd1-bf0168b79405

learn-build-service-prod · 2026-08-11T14:41:48Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

dotnet#3457 now supplies the NavigationPage sections. Match its precise wording so the two articles agree: a re-pushed page is one that was previously popped, and the toolbar change applies to ToolbarItem objects whose Order property is Secondary. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 35c845e8-c26a-4489-b9de-2c1d32638c6d

learn-build-service-prod · 2026-08-11T14:42:06Z

Learn Build status updates of commit 96c447c:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/fundamentals/shell/navigation.md	💡Suggestion	View (>=net-maui-8.0)	Details
docs/migration/custom-renderers.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/handlers/index.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/navigationpage.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/tabbedpage.md	✅Succeeded	View (>=net-maui-8.0)

docs/fundamentals/shell/navigation.md

Line 134, Column 75: [Suggestion: learn-site-link-broken - See documentation] Link '/samples/dotnet/maui-samples/navigation-shell-route-templates' points to a learn site page that doesn't exist. Check the path or URL and update the link.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

learn-build-service-prod · 2026-08-11T14:42:51Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-08-11T14:43:22Z

Learn Build status updates of commit 4f3b2ba:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/fundamentals/shell/navigation.md	💡Suggestion	View (>=net-maui-8.0)	Details
docs/migration/custom-renderers.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/handlers/index.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/navigationpage.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/tabbedpage.md	✅Succeeded	View (>=net-maui-8.0)

docs/fundamentals/shell/navigation.md

Line 134, Column 75: [Suggestion: learn-site-link-broken - See documentation] Link '/samples/dotnet/maui-samples/navigation-shell-route-templates' points to a learn site page that doesn't exist. Check the path or URL and update the link.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

learn-build-service-prod · 2026-08-11T17:21:04Z

PoliCheck Scan Report

The following report lists PoliCheck issues in PR files. Before you merge the PR, you must fix all severity-1 and severity-2 issues. The AI Review Details column lists suggestions for either removing or replacing the terms. If you find a false positive result, mention it in a PR comment and include this text: #policheck-false-positive. This feedback helps reduce false positives in future scans.

✅ No issues found

More information about PoliCheck

Information: PoliCheck | Severity Guidance | Term
For any questions: Try searching the learn.microsoft.com contributor guides or post your question in the Learn support channel.

learn-build-service-prod · 2026-08-11T17:21:20Z

Learn Build status updates of commit 33fc2ed:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/fundamentals/shell/navigation.md	💡Suggestion	View (>=net-maui-8.0)	Details
docs/migration/custom-renderers.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/handlers/index.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/navigationpage.md	✅Succeeded	View (>=net-maui-8.0)
docs/user-interface/pages/tabbedpage.md	✅Succeeded	View (>=net-maui-8.0)

docs/fundamentals/shell/navigation.md

Line 134, Column 75: [Suggestion: learn-site-link-broken - See documentation] Link '/samples/dotnet/maui-samples/navigation-shell-route-templates' points to a learn site page that doesn't exist. Check the path or URL and update the link.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

Copilot AI review requested due to automatic review settings August 6, 2026 14:46

Copilot started reviewing on behalf of davidortinau August 6, 2026 14:47 View session

Copilot AI reviewed Aug 6, 2026

View reviewed changes

Comment thread docs/fundamentals/shell/navigation.md

Comment thread docs/fundamentals/shell/navigation.md Outdated

dotnet-policy-service Bot added the okr-quality label Aug 6, 2026

davidortinau force-pushed the davidortinau-preview-7-navigation-docs branch from 8eb56ae to ec31d7e Compare August 6, 2026 14:54

davidortinau mentioned this pull request Aug 6, 2026

What's new (.NET 11): add Preview 7 highlights #3458

Merged

davidortinau force-pushed the davidortinau-preview-7-navigation-docs branch from ec31d7e to ab53dd0 Compare August 11, 2026 13:25

davidortinau force-pushed the davidortinau-preview-7-navigation-docs branch from ab53dd0 to 96c447c Compare August 11, 2026 14:40

davidortinau force-pushed the davidortinau-preview-7-navigation-docs branch from 96c447c to 4f3b2ba Compare August 11, 2026 14:41

davidortinau changed the title ~~Navigation (.NET 11): Shell route templates and iOS/Mac Catalyst TabbedPage handler~~ Navigation (.NET 11): Shell route templates and Apple page handlers Aug 11, 2026

davidortinau marked this pull request as ready for review August 11, 2026 17:19

davidortinau requested a review from a team as a code owner August 11, 2026 17:19

Merge branch 'main' into davidortinau-preview-7-navigation-docs

33fc2ed

davidortinau enabled auto-merge (squash) August 11, 2026 17:21

jfversluis approved these changes Aug 11, 2026

View reviewed changes

davidortinau merged commit b3a41de into dotnet:main Aug 11, 2026
8 checks passed

Uh oh!

Conversation

davidortinau commented Aug 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Files changed

Source verification

Shell route templates

NavigationPage handler

TabbedPage handler

Important Preview 7 boundary

Sample dependency

Overlap with #3117

Validation

Internal previews

Uh oh!

learn-build-service-prod Bot commented Aug 6, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented Aug 6, 2026

✅ Validation status: passed

Uh oh!

learn-build-service-prod Bot commented Aug 6, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented Aug 6, 2026

💡 Validation status: suggestions

docs/fundamentals/shell/navigation.md

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Copilot's findings

Uh oh!

Uh oh!

Uh oh!

learn-build-service-prod Bot commented Aug 6, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented Aug 6, 2026

💡 Validation status: suggestions

docs/fundamentals/shell/navigation.md

Uh oh!

learn-build-service-prod Bot commented Aug 11, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented Aug 11, 2026

💡 Validation status: suggestions

docs/fundamentals/shell/navigation.md

Uh oh!

learn-build-service-prod Bot commented Aug 11, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented Aug 11, 2026

💡 Validation status: suggestions

docs/fundamentals/shell/navigation.md

Uh oh!

learn-build-service-prod Bot commented Aug 11, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

Uh oh!

learn-build-service-prod Bot commented Aug 11, 2026

💡 Validation status: suggestions

docs/fundamentals/shell/navigation.md

Uh oh!

learn-build-service-prod Bot commented Aug 11, 2026

PoliCheck Scan Report

✅ No issues found

More information about PoliCheck

davidortinau commented Aug 6, 2026 •

edited

Loading