Understanding implicit vs explicit shell route registration

[hansmbakker]

I have an issue with route registration in MAUI Shell.

First of all, it is possible to define routes on different places, having a different effect. This different result is super confusing.

1. in AppShell.xaml using the Route parameter of ShellItems. This results in an object in Shell.Current.Children having an Route property with value IMPL_{value of Route parameter in AppShell.xaml}. This is an implicit route according to the logic in Routing.cs. It does not show up in Routing.s_routes.
2. in C# using Routing.RegisterRoute(route, typeof(TView)), or using something like AddSingletonWithShellRoute from MAUI Community Toolkit (which calls Routing.RegisterRoute(route, typeof(TView)) under the hood). This does result in a route registered in Routing.s_routes. I guess you could call this an explicit route then, although it is not called as such in the code.

Another, even more annoying part is that

• when a route is registered as implicit route, it is possible to call Shell.Current.GoToAsync("///LoadingPage") on it without a problem
• when a route is registered as explicit route, calling Shell.Current.GoToAsync("///LoadingPage") throws an exception:

  System.Exception: 'Global routes currently cannot be the only page on the stack, so absolute routing to global routes is not supported. For now, just navigate to: /LoadingPage'

This means that you cannot use Routing.RegisterRoute(route, typeof(TView)) nor the AddSingletonWithShellRoute convenience function to register routes if you want to do an absolute navigation.

Documentation for this item is missing, and from the code it is not intuitive what to expect with what approach

[tele-bird]

One workaround would be to add a ShellItem with Route="LandingPage" to your AppShell.xaml. Then you can invoke Shell.Current.GoToAsync("//LandingPage"); without the error. Just make sure to put it somewhere innocuous, like below all your other items. But note that this would change the lifecycle of that page.

[AndreasReitberger]

@PureWeen
I'm facing this probelm in the latest version 9.0.120. When register a Route with AddSingletonWithShellRoute I cannot do any absolute navigations. When I register at the ShellItem with Route="MyRoute", I can. Why does the one way work and the other not? Is there any fix for this?

Thanks!

[stephenquan]

Let's assume you want to have two top-level pages LandingPage and SecondPage. And you wish to switch between them. .NET MAUI requires you to have a global top-level page that you can't pop, so, we have to have a starter page, e.g. MainPage, but, it can be effectively invisible. Also note that absolute routes cannot remove the MainPage and must use double slash not triple slash.

Register LandingPage and SecondPage as you normally would in MauiProgram.cs:

Register.Route(nameof(LandingPage), typeof(LandingPage));
Register.Route(nameof(SecondPage), typeof(SecondPage));

In the constructor of MainPage, navigate to the LandingPage, e.g.

public partial class MainPage : ContentPage
{
    public MainPage()
    {
        Dispatcher.Dispatch(async() => await Shell.Current.GoToAsync(nameof(LandingPage)); // route will become //MainPage/LandingPage
    }
}

Then from the LandingPage, you can navigate to ../SecondPage and back with ../LandingPage (or with absolute routes //MainPage/SecondPage and //MainPage/LandingPage respectively).

Also, you can make both LandingPage and SecondPage look like top-level pages by disabling the Shell BackButton, e.g.

<ContentPage ... >
    <Shell.BackButtonBehavior>
        <BackButtonBehavior IsVisible="False" IsEnabled="False" />
    </Shell.BackButtonBehavior>
    <!-- ... -->
</ContentPage>

Reference:

• https://learn.microsoft.com/en-us/dotnet/maui/fundamentals/shell/navigation?view=net-maui-9.0#absolute-routes