Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 42 ยท Getting Started

App Lifecycle and MauiProgram

Understand how a MAUI app starts - MauiProgram.CreateMauiApp, the builder, App and Window classes, lifecycle events such as Created, Activated and Stopped, and how to react to them.

Every MAUI app starts in the same place: a static method called CreateMauiApp in MauiProgram.cs. It uses a builder (the same pattern as ASP.NET Core) to register the app class, fonts, services and handlers. After that MAUI creates your App object, which creates a Window, which shows your first page. Along the way the window raises lifecycle events that tell you when the app starts, goes to the background and comes back.

MAUI code in this lesson is read-only. The runnable blocks are C# stand-ins: a builder with real Microsoft.Extensions.DependencyInjection, and a small lifecycle state machine.

MauiProgram

This is the template's file (read-only):

C#
using Microsoft.Extensions.Logging;

namespace HelloMaui;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();

        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
                fonts.AddFont("OpenSans-Semibold.ttf", "OpenSansSemibold");
            });

#if DEBUG
        builder.Logging.AddDebug();
#endif

        return builder.Build();
    }
}

Reading it line by line:

  • MauiApp.CreateBuilder() creates a MauiAppBuilder.
  • UseMauiApp<App>() says which class is your application.
  • ConfigureFonts registers fonts; the second argument is the alias you use in XAML (FontFamily="OpenSansRegular").
  • builder.Logging is the standard .NET logging setup.
  • builder.Services (not shown here) is the dependency injection container; the dependency injection lesson uses it.
  • builder.Build() returns the finished MauiApp, which the platform start-up code runs.

Other UseXxx calls you will meet add libraries: UseMauiCommunityToolkit(), UseSkiaSharp(), and so on. Each one is an extension method that registers services and handlers. This is why a missing Use... call is a common reason for "my feature does nothing".

The same builder idea, runnable

The stand-in below uses the real ServiceCollection from Microsoft.Extensions.DependencyInjection (which MAUI uses internally) with a tiny AppBuilder of our own. It shows why registration happens before Build() and why the result is read-only afterwards. It is not MAUI, but the shape is the same.

C# Stand-in: a MauiProgram-style builder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Notice how MyApp received an IClock through its constructor without calling new. MAUI resolves your App, pages and view models the same way.

App, Window and the first page

After the builder runs, MAUI creates your App class. In current templates, App.xaml.cs creates the first window (read-only):

C#
namespace HelloMaui;

public partial class App : Application
{
    public App()
    {
        InitializeComponent();
    }

    protected override Window CreateWindow(IActivationState? activationState)
    {
        return new Window(new AppShell());
    }
}

CreateWindow returns a Window whose content is the first page (here an AppShell). On desktop (Windows, macOS) an app can have several windows; on phones there is normally one. You can set the title or size of a desktop window here (Title, Width, Height).

Older templates set MainPage = new AppShell(); in the constructor. That property is obsolete in recent versions; use CreateWindow.

Lifecycle events

A Window raises cross-platform events as the app moves through its life:

Event Meaning
Created The native window exists
Activated The app is in the foreground and can receive input
Deactivated The app lost focus (for example a dialog, or split screen)
Stopped The app is no longer visible; it is in the background
Resumed The app returns from the background
Destroying The window is being closed

You override the matching methods on Window, or subscribe to events (read-only):

C#
protected override Window CreateWindow(IActivationState? activationState)
{
    var window = new Window(new AppShell());

    window.Stopped += (s, e) => SaveDraft();        // user left the app
    window.Resumed += (s, e) => RefreshFromServer(); // user came back

    return window;
}

Use Stopped to save unsaved work, because the system may kill a background app at any time without further notice. Use Resumed to refresh data and restart timers.

For platform-specific events (for example Android's OnBackPressed or iOS's OpenUrl), you use ConfigureLifecycleEvents in MauiProgram, with #if ANDROID and #if IOS blocks.

C# Stand-in: lifecycle state machine

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with Console.ReadLine()), it gets the next line from this box.

Practical tips

  • Keep CreateMauiApp short; put long registration lists in extension methods such as builder.Services.AddAppServices().
  • Do not do slow work (network calls, big file reads) in MauiProgram or in a page constructor; the splash screen stays up until the first page shows.
  • Save state in Stopped, not in Destroying: the latter often never runs on mobile.
  • Test on a real device. Lifecycle behaviour (especially background kill) differs from emulators.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which method builds the MauiApp?

    CreateMauiApp creates the builder, registers things and returns builder.Build().
  2. 2. Where should you save unsaved work when the user leaves the app?

    A background app can be killed without warning, so save in Stopped. Destroying often never runs on mobile.
  3. 3. What does ConfigureFonts do?

    AddFont(file, alias) registers the bundled font, and you use the alias in FontFamily.
  4. 4. Which method returns the first Window in current MAUI templates?

    App overrides CreateWindow and returns new Window(new AppShell()) (or another first page).

Summary

  • MauiProgram.CreateMauiApp builds the app: UseMauiApp<App>(), fonts, services, libraries.
  • App.CreateWindow returns the first Window and its page.
  • Window events (Created, Activated, Stopped, Resumed, Destroying) tell you where the app is in its life.
  • Save state on Stopped and keep start-up work light.

Next: XAML Basics