maui-app-architecture

MAUI App Architecture

Use this skill for app-level wiring: services, pages, ViewModels, bindings, and navigation. Favor explicit, testable architecture over service locator patterns.

Workflow

1. Inspect MauiProgram.cs, AppShell.xaml, page constructors, and existing ViewModels.
2. Preserve the app's UI pattern: XAML/MVVM, C# Markup, MauiReactor, Blazor Hybrid, or a mix.
3. Register dependencies in MauiProgram.cs.
4. Use constructor injection for pages and ViewModels.
5. Use compiled bindings with x:DataType in pages and data templates.
6. Register Shell routes once, near app startup. When asked how to register a Shell route, show the literal Routing.RegisterRoute(...) call, not only a prose summary.
7. Pass navigation data through Shell route query parameters. For trim-sensitive or NativeAOT-sensitive flows, prefer IQueryAttributable over [QueryProperty].
8. Keep platform APIs behind interfaces so ViewModels remain unit-testable.

Dependency Injection Guidance

Avoid calling BuildServiceProvider() inside MauiProgram.cs. Register the type and let MAUI resolve it.

Shell Navigation Pattern

Routing.RegisterRoute(nameof(DetailsPage), typeof(DetailsPage));

await Shell.Current.GoToAsync($"{nameof(DetailsPage)}?id={Uri.EscapeDataString(id)}");

public sealed partial class DetailsViewModel : ObservableObject, IQueryAttributable
{
    public void ApplyQueryAttributes(IDictionary<string, object> query)
    {
        if (query.TryGetValue("id", out var value) && value is string id)
        {
            Load(Uri.UnescapeDataString(id));
        }
    }
}