Shell Navigation In .Net Maui Complete Guide

Prerequisites:

• Ensure you have .NET MAUI installed.
• Have Visual Studio 2022 or later, or Visual Studio for Mac with .NET MAUI support.

Step 1: Create a New .NET MAUI Project

1. Open Visual Studio.
2. Create a new project.
3. Select "MAUI App".
4. Configure your project details (name, location, etc.) and click "Create".

Step 2: Add NuGet Packages (if needed)

.NET MAUI comes with built-in functionality for XAML shells and navigation, so typically you don't need to install additional NuGet packages.

Step 3: Define Your Shell Structure

In this example, we'll create three simple pages and define a basic shell structure.

Create the First Page (MainPage.xaml)

Right-click on the Pages folder (or wherever you want to keep your pages), select Add -> New Item, and add a new Content Page named MainPage.xaml.

MainPage.xaml:

<?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="YourAppNamespace.MainPage"
             Title="Main Page">
    <StackLayout>
        <Label Text="Welcome to the Main Page!" 
               FontSize="Large" 
               HorizontalOptions="Center" 
               VerticalOptions="CenterAndExpand"/>
        <Button Text="Go to Page 1" 
                Command="{Binding NavigateToPage1Command}" 
                HorizontalOptions="Center" />
    </StackLayout>
</ContentPage>

Create the Code-behind for the first page (MainPage.xaml.cs).

MainPage.xaml.cs:

using Microsoft.Maui.Controls;
using System.Windows.Input;

namespace YourAppNamespace.Pages
{
    public partial class MainPage : ContentPage
    {
        public ICommand NavigateToPage1Command { get; }

        public MainPage()
        {
            InitializeComponent();
            BindingContext = this;
            NavigateToPage1Command = new Command(NavigateToPage1);
        }

        private async void NavigateToPage1()
        {
            await Shell.Current.GoToAsync("//page1");
        }
    }
}

Create the Second Page (Page1.xaml)

Right-click on the Pages folder, select Add -> New Item, and add a new Content Page named Page1.xaml.

Page1.xaml:

<?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="YourAppNamespace.Pages.Page1"
             Title="Page 1">
    <StackLayout>
        <Label Text="Welcome to Page 1!"
               FontSize="Large" 
               HorizontalOptions="Center" 
               VerticalOptions="CenterAndExpand"/>
        <Button Text="Go back to Main Page"
                Command="{Binding GoBackCommand}"
                HorizontalOptions="Center" />
        <Button Text="Go to Page 2"
                Command="{Binding NavigateToPage2Command}"
                HorizontalOptions="Center" />
    </StackLayout>
</ContentPage>

Create the Code-behind for the second page (Page1.xaml.cs).

Page1.xaml.cs:

using Microsoft.Maui.Controls;
using System.Windows.Input;

namespace YourAppNamespace.Pages
{
    public partial class Page1 : ContentPage
    {
        public ICommand GoBackCommand { get; }
        public ICommand NavigateToPage2Command { get; }

        public Page1()
        {
            InitializeComponent();
            BindingContext = this;
            GoBackCommand = new Command(() => Shell.Current.GoToAsync(".."));
            NavigateToPage2Command = new Command(() => Shell.Current.GoToAsync("//page2"));
        }
    }
}

Create the Third Page (Page2.xaml)

Right-click on the Pages folder, select Add -> New Item, and add a new Content Page named Page2.xaml.

Page2.xaml:

<?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="YourAppNamespace.Pages.Page2"
             Title="Page 2">
    <StackLayout>
        <Label Text="Welcome to Page 2!"
               FontSize="Large"
               HorizontalOptions="Center"
               VerticalOptions="CenterAndExpand"/>
        <Button Text="Go back to Page 1"
                Command="{Binding GoBackCommand}"
                HorizontalOptions="Center" />
    </StackLayout>
</ContentPage>

Create the Code-behind for the third page (Page2.xaml.cs).

Page2.xaml.cs:

using Microsoft.Maui.Controls;
using System.Windows.Input;

namespace YourAppNamespace.Pages
{
    public partial class Page2 : ContentPage
    {
        public ICommand GoBackCommand { get; }

        public Page2()
        {
            InitializeComponent();
            BindingContext = this;
            GoBackCommand = new Command(() => Shell.Current.GoToAsync(".."));
        }
    }
}

Step 4: Define Shell Routes

Modify the AppShell.xaml to define routes for your pages.

AppShell.xaml:

<?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"
       x:Class="YourAppNamespace.AppShell">

    <!-- Define the routes here -->
    <ShellContent Title="Home"
                  Route="home"
                  ContentTemplate="{DataTemplate local:MainPage}" />
    <ShellContent Title="Page 1"
                  Route="page1"
                  ContentTemplate="{DataTemplate local:Page1}" />
    <ShellContent Title="Page 2"
                  Route="page2"
                  ContentTemplate="{DataTemplate local:Page2}" />
</Shell>

Ensure the xmlns:local attribute includes the right namespace reference in your AppShell.xaml.

AppShell.xaml (Root):

<?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:YourAppNamespace.Pages"
       x:Class="YourAppNamespace.AppShell">

    <!-- Define the routes here -->
    <TabBar>
        <ShellContent Title="Home"
                      Route="home"
                      ContentTemplate="{DataTemplate local:MainPage}" />
        <ShellContent Title="Page 1"
                      Route="page1"
                      ContentTemplate="{DataTemplate local:Page1}" />
        <ShellContent Title="Page 2"
                      Route="page2"
                      ContentTemplate="{DataTemplate local:Page2}" />
    </TabBar>
</Shell>

Step 5: Configure App.xaml.cs

Ensure that the AppShell is set as the root page of your application.

App.xaml.cs:

using Microsoft.Maui.Controls;

namespace YourAppNamespace
{
    public partial class App : Application
    {
        public App()
        {
            InitializeComponent();

            MainPage = new AppShell();
        }
    }
}

Step 6: Run the Application

1. Press F5 or click the "Start Debugging" button in Visual Studio.
2. The application should open displaying the MainPage.
3. Click the "Go to Page 1" button to navigate to Page1.
4. From Page1, click the "Go back to Main Page" button to go back to MainPage.
5. From Page1, click the "Go to Page 2" button to navigate to Page2.
6. From Page2, click the "Go back to Page 1" button to go back to Page1.

Summary:

This example illustrated how to:

1. Create multiple pages (MainPage.xaml, Page1.xaml, Page2.xaml).
2. Define route mappings using AppShell.xaml.
3. Navigate between different pages using commands bound to buttons.
4. Use the Shell.Current.GoToAsync() method for navigation.

Remember, Shell navigation in .NET MAUI provides a flexible way to handle navigation in your applications, especially when working with tabs, flyouts, and other complex layouts. The double slash (//) before a route name tells the shell to reset the navigation stack to this page. The single dot (..) navigates one page back in the stack.