What you will learn
- Define a ShellContent entry point
- Register a detail-page route
- Use awaited Shell.GoToAsync calls and return navigation
MauiNavigation with .NET 10. Use the complete file listings below, and leave other template-generated files unchanged unless the lesson explicitly says otherwise. Run the Android target on Windows.1. Create the new MAUI project
Create a project called MauiNavigation. Replace AppShell.xaml, AppShell.xaml.cs, and MainPage files. Add a new .NET MAUI ContentPage (XAML) named DetailsPage.xaml, then replace its XAML and C# content.
2. Configure routes correctly
The home screen is declared as ShellContent, so it is part of the Shell visual hierarchy. The DetailsPage is registered using Routing.RegisterRoute; it is not a ShellContent entry.
Navigate to the registered detail page with await Shell.Current.GoToAsync(nameof(DetailsPage)). Use await Shell.Current.GoToAsync("..") to go back.
3. Run and test the navigation stack
- Launch the Android app.
- Tap Open details.
- Confirm that the details screen appears and has a way back.
- Tap Return home or the system back button.
A relative route is appropriate here because DetailsPage is registered outside the Shell visual tree. Relative navigation should not be used to push a route defined solely in ShellContent.
4. Where Shell helps
For larger projects, Shell can organize tab bars, flyout menus and nested routes. This simple two-page project establishes the routing approach used by many production apps.
Complete sample code
Use the exact file names and folder locations shown below. Copy each listing into your MAUI project. The separate source files can also be downloaded individually.
<?xml version="1.0" encoding="utf-8" ?>
<Shell xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
xmlns:local="clr-namespace:MauiNavigation"
x:Class="MauiNavigation.AppShell"
FlyoutBehavior="Disabled">
<ShellContent Title="Home" Route="home"
ContentTemplate="{DataTemplate local:MainPage}" />
</Shell>namespace MauiNavigation;
public partial class AppShell : Shell
{
public AppShell()
{
InitializeComponent();
Routing.RegisterRoute(nameof(DetailsPage), typeof(DetailsPage));
}
}<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="MauiNavigation.MainPage"
Title="Home">
<VerticalStackLayout Padding="24" Spacing="16">
<Label Text="Navigation Demo" FontSize="26"
FontAttributes="Bold" />
<Label Text="This is the home page." />
<Button Text="Open details" Clicked="OnOpenDetails" />
</VerticalStackLayout>
</ContentPage>namespace MauiNavigation;
public partial class MainPage : ContentPage
{
public MainPage() => InitializeComponent();
private async void OnOpenDetails(object sender, EventArgs e)
{
await Shell.Current.GoToAsync(nameof(DetailsPage));
}
}<?xml version="1.0" encoding="utf-8" ?>
<ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
x:Class="MauiNavigation.DetailsPage"
Title="Details">
<VerticalStackLayout Padding="24" Spacing="16">
<Label Text="Details Page" FontSize="26"
FontAttributes="Bold" />
<Label Text="Navigation succeeded." />
<Button Text="Return home" Clicked="OnGoBack" />
</VerticalStackLayout>
</ContentPage>namespace MauiNavigation;
public partial class DetailsPage : ContentPage
{
public DetailsPage() => InitializeComponent();
private async void OnGoBack(object sender, EventArgs e)
{
await Shell.Current.GoToAsync("..");
}
}Common problems and solutions
- Route not found: Ensure you registered DetailsPage in the AppShell constructor.
- Duplicate route: Register the route only once and keep names unique.
- Navigation appears inconsistent: Always await GoToAsync.
Practice exercise
Add a third page called AboutPage and register a separate route for it.