跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

maui-app-lifecycle

.NET MAUI app lifecycle guidance — the four app states, cross-platform Window lifecycle events (Created, Activated, Deactivated, Stopped, Resumed, Destroying), platform-specific lifecycle mapping, backgrounding and resume behavior, and state-preservation patterns. USE FOR: "app lifecycle", "window lifecycle events", "save state on background", "resume app", "OnStopped", "OnResumed", "backgrounding", "deactivated event", "ConfigureLifecycleEvents", "platform lifecycle hooks". DO NOT USE FOR: navigation events (use maui-shell-navigation), dependency injection setup (use maui-dependency-injection), platform API invocation (use conditional compilation and partial classes).

managedcode · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add managedcode/dotnet-skills --skill maui-app-lifecycle

技能说明


name: maui-app-lifecycle description: >- .NET MAUI app lifecycle guidance — the four app states, cross-platform Window lifecycle events (Created, Activated, Deactivated, Stopped, Resumed, Destroying), platform-specific lifecycle mapping, backgrounding and resume behavior, and state-preservation patterns. USE FOR: "app lifecycle", "window lifecycle events", "save state on background", "resume app", "OnStopped", "OnResumed", "backgrounding", "deactivated event", "ConfigureLifecycleEvents", "platform lifecycle hooks". DO NOT USE FOR: navigation events (use maui-shell-navigation), dependency injection setup (use maui-dependency-injection), platform API invocation (use conditional compilation and partial classes). license: MIT

.NET MAUI App Lifecycle

Handle application state transitions correctly in .NET MAUI. This skill covers the cross-platform Window lifecycle events, their platform-native mappings, and patterns for preserving state across backgrounding and resume cycles.

When to Use

  • Saving or restoring state when the app backgrounds or resumes
  • Subscribing to Window lifecycle events (Created, Activated, Deactivated, Stopped, Resumed, Destroying)
  • Hooking into platform-native lifecycle callbacks via ConfigureLifecycleEvents
  • Deciding where to place initialization, teardown, or refresh logic
  • Understanding the difference between Deactivated and Stopped

When Not to Use

  • Page-level navigation events — use Shell navigation guidance instead
  • Registering services at startup — use dependency injection guidance instead
  • Calling platform-specific APIs outside lifecycle context — use platform invoke guidance instead

Inputs

  • The target lifecycle transition (e.g., "save draft when backgrounded", "refresh data on resume")
  • Which platforms the developer targets (Android, iOS, Mac Catalyst, Windows)
  • Whether the app uses multiple windows (iPad, Mac Catalyst, desktop Windows)

App States

A .NET MAUI app moves through four states:

StateDescription
Not RunningProcess does not exist
RunningForeground, receiving input
DeactivatedVisible but lost focus (dialog, split-screen, notification shade)
StoppedFully backgrounded, UI not visible

Typical flow: Not Running → Running → Deactivated → Stopped → Running (resumed) or Not Running (terminated).

Window Lifecycle Events

Microsoft.Maui.Controls.Window exposes six cross-platform events:

EventFires when
CreatedNative window allocated
ActivatedWindow receives input focus
DeactivatedWindow loses focus (may still be visible)
StoppedWindow is no longer visible
ResumedWindow returns to foreground after Stopped
DestroyingNative window is being torn down

Subscribing via CreateWindow

Override CreateWindow in your App class and attach event handlers:

public partial class App : Application
{
    protected override Window CreateWindow(IActivationState? activationState)
    {
        var window = base.CreateWindow(activationState);

        window.Created += (s, e) => Debug.WriteLine("Created");
        window.Activated += (s, e) => Debug.WriteLine("Activated");
        window.Deactivated += (s, e) => Debug.WriteLine("Deactivated");
        window.Stopped += (s, e) => Debug.WriteLine("Stopped");
        window.Resumed += (s, e) => Debug.WriteLine("Resumed");
        window.Destroying += (s, e) => Debug.WriteLine("Destroying");

        return window;
    }
}

Subscribing via a Custom Window Subclass

Create a Window subclass and override the virtual methods:

public class AppWindow : Window
{
    public AppWindow(Page page) : base(page) { }

    protected override void OnActivated() { /* refresh UI */ }
    protected override void OnStopped() { /* save state */ }
    protected override void OnResumed() { /* restore state */ }
    protected override void OnDestroying() { /* cleanup */ }
}

Return it from CreateWindow:

protected override Window CreateWindow(IActivationState? activationState)
    => new AppWindow(new AppShell());

Workflow: Save and Restore State on Background

  1. Identify transient state — draft text, scroll position, form inputs, timer values.
  2. Save in OnStopped — use Preferences for small values or file serialization for larger state.
  3. Restore in OnResumed — read back saved values and apply to your view model.
  4. Also save in OnDestroying on Android — the back button can skip Stopped entirely.
  5. Keep handlers fast — complete within 1–2 seconds to avoid ANR on Android or watchdog kills on iOS.
protected override void OnStopped()
{
    base.OnStopped();
    Preferences.Set("draft_text", _viewModel.DraftText);
    Preferences.Set("scroll_y", _viewModel.ScrollY);
}

protected override void OnResumed()
{
    base.OnResumed();
    _viewModel.DraftText = Preferences.Get("draft_text", string.Empty);
    _viewModel.ScrollY = Preferences.Get("scroll_y", 0.0);
}

protected override void OnDestroying()
{
    base.OnDestroying();
    // Android back-button can skip Stopped
    Preferences.Set("draft_text", _viewModel.DraftText);
}

Platform Lifecycle Mapping

Android

Window EventAndroid Callback
CreatedOnCreate
ActivatedOnResume
DeactivatedOnPause
StoppedOnStop
ResumedOnRestart → OnStart → OnResume
DestroyingOnDestroy

iOS / Mac Catalyst

Window EventUIKit CallbackAddiOS builder method
CreatedWillFinishLaunching / SceneWillConnect.WillFinishLaunching() / .SceneWillConnect()
ActivatedDidBecomeActive.OnActivated()
DeactivatedWillResignActive.OnResignActivation()
StoppedDidEnterBackground.DidEnterBackground()
ResumedWillEnterForeground.WillEnterForeground()
Destroying`WillT
阅读完整来源 ↗