Pages as the Building Block of MAUI Apps
A ContentPage is the fundamental screen unit in .NET MAUI: it hosts a single root layout (Grid, StackLayout, or similar) and defines the visible content of one navigable destination. Every route registered in Shell ultimately resolves to a Page subtype, and pages participate in a lifecycle of Appearing/Disappearing events that fire as navigation moves them on and off screen.
Cricket analogy: A ContentPage is like a single innings in a match: it has one clearly bounded scope — batting starts, wickets fall, it ends — the same way a page has a defined beginning (Appearing) and end (Disappearing).
The Page Lifecycle
OnAppearing fires just before a page becomes visible, making it the right place to refresh data or start a timer, while OnDisappearing fires as the page is navigated away from, suitable for pausing work or saving state. These are protected virtual methods you override on the page's code-behind, and they fire on every navigation event, not just the first time the page loads, so OnAppearing can run multiple times across a page's life if the user navigates back to it.
Cricket analogy: OnAppearing is like the umpire signaling 'play' as a new bowler starts their run-up, and OnDisappearing is like calling 'over' — both trigger every single over, not just the first one of the match.
public partial class OrderHistoryPage : ContentPage
{
private readonly OrderViewModel _viewModel;
public OrderHistoryPage(OrderViewModel viewModel)
{
InitializeComponent();
BindingContext = _viewModel = viewModel;
}
protected override async void OnAppearing()
{
base.OnAppearing();
await _viewModel.RefreshOrdersAsync();
}
protected override void OnDisappearing()
{
base.OnDisappearing();
_viewModel.CancelPendingRequests();
}
}Modal Navigation
Modal pages are presented over the current page rather than replacing it, typically covering the full screen and blocking interaction with what's underneath until dismissed. In Shell, you present them by prefixing the route with a leading slash inside GoToAsync, e.g. GoToAsync("AddItemPage"), or by registering them and navigating with an absolute route combined with modal presentation semantics; Shell also honors the Shell.PresentationMode attached property (NotAnimated, Animated, Modal, ModalAnimated) to control how a route is displayed.
Cricket analogy: A modal page is like a rain-delay interruption that takes over the entire broadcast with a weather graphic, blocking the match view until the umpires resume play and dismiss it.
Modal pages typically hide the Shell flyout and tab bar by default so the user's focus stays on the task at hand. Provide an explicit close/cancel action (a toolbar item or button calling GoToAsync("..")) since modals don't automatically expose the hardware back button behavior consistently across platforms.
Overriding OnAppearing with an async void signature (as shown above) means exceptions thrown inside it cannot be caught by the caller and will crash the app. Wrap awaited calls in a try/catch inside OnAppearing, or route the logic through a command the ViewModel can properly await and handle errors for.
- ContentPage is the base building block for a single navigable screen with one root layout.
- OnAppearing fires before a page becomes visible; OnDisappearing fires as it's navigated away from.
- Lifecycle methods fire on every navigation event, not only the first time a page is created.
- Modal pages overlay the current page and block interaction until explicitly dismissed.
- Shell.PresentationMode controls whether a route is animated, modal, or both.
- Modals typically hide the flyout and tab bar and need an explicit close action.
- Avoid async void in lifecycle overrides without try/catch, since unhandled exceptions there crash the app.
Practice what you learned
1. What is the fundamental building block that represents a single navigable screen in .NET MAUI?
2. When does OnDisappearing fire relative to a page's lifetime?
3. What attached property controls whether a Shell route is presented modally?
4. Why is an async void OnAppearing override risky?
Was this page helpful?
You May Also Like
Shell Navigation
Learn how .NET MAUI Shell provides a unified, URI-based navigation system with flyouts, tabs, and route registration.
Platform-Specific Code
Learn how to branch behavior per platform in .NET MAUI using conditional compilation, partial classes, and platform folders.
Permissions and Lifecycle
Understand runtime permission requests and the app lifecycle events that govern how a .NET MAUI app behaves in the foreground and background.
Related Reading
Related Study Notes in Programming
Browse all study notesApache Spark Study Notes
Programming · 30 topics
ProgrammingApache Flink Study Notes
Programming · 30 topics
ProgrammingHadoop Study Notes
Programming · 30 topics
ProgrammingSnowflake Study Notes
Programming · 30 topics
ProgrammingApache Airflow Study Notes
Programming · 30 topics
Programmingdbt (Data Build Tool) Study Notes
Programming · 30 topics