[Net11 Preview6] Shell: Document Android Handler implementation and ShellRenderer usage

docs/fundamentals/shell/index.md

@@ -15,6 +15,26 @@ ms.date: 08/30/2024
 - A URI-based navigation scheme that permits navigation to any page in the app.
 - An integrated search handler.
 
+::: moniker range=">=net-maui-11.0"
+
+> [!NOTE]
+> On Android, <xref:Microsoft.Maui.Controls.Shell> uses a handler-based implementation in .NET 11, aligning with the handler architecture. In .NET 10 and earlier, <xref:Microsoft.Maui.Controls.Shell> used the `ShellRenderer`-based implementation on Android.
+
+## Revert to ShellRenderer behavior
+
+We recommend using the new handler-based <xref:Microsoft.Maui.Controls.Shell> on Android, but if you want to opt out and revert to the `ShellRenderer` behavior, you can use the following code in your `MauiProgram.cs`:
+
+```csharp
+#if ANDROID
+builder.ConfigureMauiHandlers(handlers =>
+{
+    handlers.AddHandler<Shell, Microsoft.Maui.Controls.Handlers.Compatibility.ShellRenderer>();
+});
+#endif
+```
+
+::: moniker-end
+
 ## App visual hierarchy
 
 In a .NET MAUI Shell app, the visual hierarchy of the app is described in a class that subclasses the <xref:Microsoft.Maui.Controls.Shell> class. This class can consist of three main hierarchical objects:

docs/whats-new/dotnet-11.md

@@ -48,6 +48,21 @@ In .NET 11 Preview 4, the Android handlers for several core controls use Materia
 
 In .NET 11 Preview 5, the underlying Material 3 helper types (`MauiMaterialEditText`, `MauiMaterialDatePicker`, `MauiMaterialPicker`, `MauiMaterialTimePicker`, `MauiMaterialTextView`, `MauiMaterialSearchBarTextInputLayout`, `MaterialActivityIndicator`, and `MauiMaterialContextThemeWrapper`) are public so you can subclass them from your own handler customizations. For more information, see [GitHub PR #35323](https://github.com/dotnet/maui/pull/35323) and [Material 3](~/user-interface/material-design.md).
 
+### Shell handler on Android
+
+Starting in .NET 11 Preview 6, <xref:Microsoft.Maui.Controls.Shell> on Android uses a handler-based implementation, aligning with the current .NET MAUI handler architecture. In .NET 10 and earlier, <xref:Microsoft.Maui.Controls.Shell> used the `ShellRenderer`-based implementation on Android. For more information, see [GitHub PR #34758](https://github.com/dotnet/maui/pull/34758) and [Shell](~/fundamentals/shell/index.md#revert-to-shellrenderer-behavior).
+
+If you need to revert to the previous `ShellRenderer` behavior, you can use the following code in your `MauiProgram.cs`:
+
+```csharp
+#if ANDROID
+builder.ConfigureMauiHandlers(handlers =>
+{
+    handlers.AddHandler<Shell, Microsoft.Maui.Controls.Handlers.Compatibility.ShellRenderer>();
+});
+#endif
+```
+
 ### BoxView Fill property
 
 :::moniker range=">=net-maui-11.0"