diff --git a/docs/fundamentals/shell/index.md b/docs/fundamentals/shell/index.md index edf1bf663d..cd50a0723d 100644 --- a/docs/fundamentals/shell/index.md +++ b/docs/fundamentals/shell/index.md @@ -1,7 +1,7 @@ --- title: ".NET MAUI Shell overview" description: ".NET MAUI Shell provides the fundamental features that most apps require, including a common navigation user experience, a URI-based navigation scheme, and an integrated search handler." -ms.date: 08/30/2024 +ms.date: 07/08/2026 --- # .NET MAUI Shell overview @@ -30,6 +30,27 @@ These objects don't represent any user interface, but rather the organization of For more information, see [Create a .NET MAUI Shell app](create.md). +::: moniker range=">=net-maui-11.0" + +## Android handler architecture + +Starting in .NET MAUI 11, Shell on Android uses a handler-based architecture by default. The Android implementation is built around `ShellHandler`, `ShellItemHandler`, and `ShellSectionHandler`, and reuses `MauiDrawerLayout`, `TabbedViewManager`, and the navigation handler infrastructure used by other .NET MAUI navigation controls. This doesn't change how you define the Shell hierarchy in XAML or C#. + +iOS and Mac Catalyst Shell continue to use the legacy `ShellRenderer`. If an Android app depends on legacy Shell renderer behavior or custom Android `ShellRenderer` subclasses, you can opt out of the Android handler architecture by registering the compatibility renderer explicitly: + +```csharp +builder.ConfigureMauiHandlers(handlers => +{ +#if ANDROID + handlers.AddHandler(); +#endif +}); +``` + +For custom Android Shell renderer migration guidance, see [Reuse custom renderers in .NET MAUI](~/migration/custom-renderers.md#migrate-android-shell-renderers). + +::: moniker-end + ## Navigation user experience The navigation experience provided by .NET MAUI Shell is based on flyouts and tabs. The top level of navigation in a Shell app is either a flyout or a bottom tab bar, depending on the navigation requirements of the app. The following example shows an app where the top level of navigation is a flyout: diff --git a/docs/migration/custom-renderers.md b/docs/migration/custom-renderers.md index 8b056f117c..a6a3bff399 100644 --- a/docs/migration/custom-renderers.md +++ b/docs/migration/custom-renderers.md @@ -1,7 +1,7 @@ --- title: "Reuse custom renderers in .NET MAUI" description: "Learn how to adapt Xamarin.Forms custom renderers to work in a .NET MAUI app." -ms.date: 04/13/2023 +ms.date: 07/08/2026 --- # Reuse custom renderers in .NET MAUI @@ -84,6 +84,34 @@ The renderers are registered with the [!IMPORTANT] > Only renderers that derive from `FrameRenderer`, `ListViewRenderer`, `NavigationRenderer` on iOS, `ShellRenderer` on iOS and Android, `TabbedRenderer` on iOS, `TableViewRenderer`, and `VisualElementRenderer` can be registered with the method. +::: moniker range=">=net-maui-11.0" + +### Migrate Android Shell renderers + +Starting in .NET MAUI 11, Android Shell uses handlers by default. Apps with custom Android Shell renderer subclasses should migrate those customizations to the Android Shell handler types where possible: + +| Android renderer customization | Handler customization | +| -- | -- | +| `ShellRenderer` subclass | `ShellHandler` subclass | +| `ShellItemRenderer` subclass | `ShellItemHandler` subclass | +| `ShellSectionRenderer` subclass | `ShellSectionHandler` subclass | +| `ShellItemRenderer.OnTabReselected()` | `ShellItemHandler.OnTabReselected()` | +| Shell `More` overflow menu or bottom sheet customization | `ShellItemHandler.CreateMoreBottomSheet()` | +| Navigation animation `SetupAnimation(...)` | `ShellSectionHandler.OnCreateNavigationAnimation(Context, bool isPopping, bool enter)` | + +If you need the legacy Android Shell renderer while migrating, register it explicitly with : + +```csharp +builder.ConfigureMauiHandlers(handlers => +{ +#if ANDROID + handlers.AddHandler(); +#endif +}); +``` + +::: moniker-end + ### Consume the custom renderers The custom renderer can be consumed in a .NET MAUI app as a custom control: diff --git a/docs/user-interface/handlers/index.md b/docs/user-interface/handlers/index.md index a6abb14bdb..3c1b5e7b6a 100644 --- a/docs/user-interface/handlers/index.md +++ b/docs/user-interface/handlers/index.md @@ -1,7 +1,7 @@ --- title: ".NET MAUI handlers" description: "Learn about .NET MAUI handlers, which map cross-platform controls to performant native controls on each platform." -ms.date: 01/13/2025 +ms.date: 07/08/2026 --- # Handlers @@ -97,19 +97,38 @@ The following table lists the types that implement views in .NET MAUI: The following table lists the types that implement pages in .NET MAUI: +::: moniker range="<=net-maui-10.0" + | Page | Android Handler | iOS/Mac Catalyst Handler | Windows Handler | Property Mapper | Command Mapper | | -- | -- | -- | -- | -- | -- | | | | | | | | | | | PhoneFlyoutPageRenderer | | `Mapper` | | | | | NavigationRenderer | | `Mapper` | | | | | TabbedRenderer | | `Mapper` | | -| | `ShellHandler` | ShellRenderer | ShellRenderer | `Mapper` | | +| | ShellRenderer | ShellRenderer | `ShellHandler` | `Mapper` | | + +::: moniker-end + +::: moniker range=">=net-maui-11.0" + +| Page | Android Handler | iOS/Mac Catalyst Handler | Windows Handler | Property Mapper | Command Mapper | +| -- | -- | -- | -- | -- | -- | +| | | | | | | +| | | PhoneFlyoutPageRenderer | | `Mapper` | | +| | | NavigationRenderer | | `Mapper` | | +| | | TabbedRenderer | | `Mapper` | | +| | `ShellHandler` | ShellRenderer | `ShellHandler` | `Mapper` | | + +> [!NOTE] +> Starting in .NET MAUI 11, Android Shell uses the handler-based `ShellHandler`, `ShellItemHandler`, and `ShellSectionHandler` by default. iOS and Mac Catalyst Shell continue to use `ShellRenderer`. + +::: moniker-end