{"slug":"maui-app-lifecycle","title":"maui-app-lifecycle","summary":".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 l","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-24T05:37:29.989775Z","repo":{"url":"https://github.com/dotnet/skills","stars":5471,"forks":418,"license":"MIT","updatedAt":"2026-09-24T06:38:55Z"},"bodyHtml":"
\n

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

\n

.NET MAUI App Lifecycle

\n

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.

\n

When to Use

\n\n

When Not to Use

\n\n

Inputs

\n\n

App States

\n

A .NET MAUI app moves through four states:

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

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

\n

Window Lifecycle Events

\n

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

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
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
\n

Subscribing via CreateWindow

\n

Override CreateWindow in your App class and attach event handlers:

\n
public partial class App : Application\n{\n    protected override Window CreateWindow(IActivationState? activationState)\n    {\n        var window = base.CreateWindow(activationState);\n\n        window.Created += (s, e) => Debug.WriteLine(\"Created\");\n        window.Activated += (s, e) => Debug.WriteLine(\"Activated\");\n        window.Deactivated += (s, e) => Debug.WriteLine(\"Deactivated\");\n        window.Stopped += (s, e) => Debug.WriteLine(\"Stopped\");\n        window.Resumed += (s, e) => Debug.WriteLine(\"Resumed\");\n        window.Destroying += (s, e) => Debug.WriteLine(\"Destroying\");\n\n        return window;\n    }\n}\n
\n

Subscribing via a Custom Window Subclass

\n

Create a Window subclass and override the virtual methods:

\n
public class AppWindow : Window\n{\n    public AppWindow(Page page) : base(page) { }\n\n    protected override void OnActivated() { /* refresh UI */ }\n    protected override void OnStopped() { /* save state */ }\n    protected override void OnResumed() { /* restore state */ }\n    protected override void OnDestroying() { /* cleanup */ }\n}\n
\n

Return it from CreateWindow:

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

Workflow: Save and Restore State on Background

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

Platform Lifecycle Mapping

\n

Android

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

iOS / Mac Catalyst

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Window EventUIKit CallbackAddiOS builder method
CreatedWillFinishLaunching / SceneWillConnect.WillFinishLaunching() / .SceneWillConnect()
ActivatedDidBecomeActive.OnActivated()
DeactivatedWillResignActive.OnResignActivation()
StoppedDidEnterBackground.DidEnterBackground()
ResumedWillEnterForeground.WillEnterForeground()
DestroyingWillTerminate.WillTerminate()
\n
\n

⚠️ The UIKit selector names and the AddiOS builder method names differ for\nactivation. There is no .DidBecomeActive() or .WillResignActive() builder\nmethod — use .OnActivated() and .OnResignActivation() or the code will not compile.

\n
\n

Windows (WinUI)

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
Window EventWinUI Callback
CreatedOnLaunched
ActivatedActivated (foreground)
DeactivatedActivated (background)
StoppedVisibilityChanged (false)
ResumedVisibilityChanged (true)
DestroyingClosed
\n

Hooking Native Lifecycle Directly

\n

Use ConfigureLifecycleEvents in MauiProgram.cs when you need platform-specific callbacks beyond what Window events provide:

\n
builder.ConfigureLifecycleEvents(events =>\n{\n#if ANDROID\n    events.AddAndroid(android => android\n        .OnCreate((activity, bundle) => Debug.WriteLine(\"Android OnCreate\"))\n        .OnResume(activity => Debug.WriteLine(\"Android OnResume\"))\n        .OnPause(activity => Debug.WriteLine(\"Android OnPause\"))\n        .OnStop(activity => Debug.WriteLine(\"Android OnStop\"))\n        .OnDestroy(activity => Debug.WriteLine(\"Android OnDestroy\")));\n#elif IOS || MACCATALYST\n    events.AddiOS(ios => ios\n        .OnActivated(app => Debug.WriteLine(\"iOS OnActivated\"))\n        .OnResignActivation(app => Debug.WriteLine(\"iOS OnResignActivation\"))\n        .DidEnterBackground(app => Debug.WriteLine(\"iOS DidEnterBackground\"))\n        .WillEnterForeground(app => Debug.WriteLine(\"iOS WillEnterForeground\")));\n#elif WINDOWS\n    events.AddWindows(windows => windows\n        .OnLaunched((app, args) => Debug.WriteLine(\"Windows OnLaunched\"))\n        .OnActivated((window, args) => Debug.WriteLine(\"Windows Activated\"))\n        .OnClosed((window, args) => Debug.WriteLine(\"Windows Closed\")));\n#endif\n});\n
\n

Common Pitfalls

\n
    \n

  1. Resumed does not fire on first launch. The initial sequence is Created → Activated. Use OnActivated for logic that must run on every foreground entry, not OnResumed.

    \n
    2. \n

  2. Deactivated ≠ Stopped. A dialog, split-screen, or notification pull-down triggers Deactivated without Stopped. Do not perform heavy saves in OnDeactivated — the app may never actually background.

    \n
    3. \n

  3. Android back button skips Stopped. On Android, pressing back may call Destroying directly without Stopped. Place critical save logic in both OnStopped and OnDestroying.

    \n
    4. \n

  4. Multi-window apps fire events independently. On iPad, Mac Catalyst, and desktop Windows each Window instance fires its own lifecycle events. Do not assume a single global lifecycle.

    \n
    5. \n

  5. Long-running handlers cause kills. Android enforces a ~5 second ANR timeout; iOS has limited background execution time. Keep lifecycle handlers synchronous and fast — use Preferences for quick saves, not database writes.

    \n
    6. \n

  6. Do not use legacy Xamarin.Forms lifecycle methods. Application.OnStart(), Application.OnSleep(), and Application.OnResume() exist for backward compatibility but bypass Window-level events. In .NET MAUI, prefer Window lifecycle events (OnActivated, OnStopped, OnResumed, etc.) for correct multi-window behavior.

    \n
    7. \n
\n","files":[{"path":"references/lifecycle-api.md","sizeBytes":5673,"isText":true},{"path":"SKILL.md","sizeBytes":9241,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-24T05:40:48.878081Z","sha256":"F63FEB80B75B5919ADD4470943136BA3557B17F02B7F99597A3B1F22F562B356","sizeBytes":5426},"review":null,"source":{"repositoryUrl":"https://github.com/dotnet/skills","path":"plugins/dotnet-maui/skills/maui-app-lifecycle","license":"MIT","commit":"e115891bd2ac3c7eefd5e30a405f7b5638f5e429","subtreeSha":"DFC3007FAACC6BBD9255AF3A1B3B10158639D5870B0EE4E609BE35C248FD4E1E","lastSyncedAt":"2026-09-24T06:48:49.987562Z"},"reviewedAt":"2026-08-24T05:50:03.414608Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/dotnet/skills/tree/main/plugins/dotnet-maui/skills/maui-app-lifecycle"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install dotnet-skills@llmmart"},{"target":"git","command":"git clone https://github.com/dotnet/skills.git"}]}