maui-app-lifecycle
.NET MAUI app lifecycle guidance covering the four app states (not running, running, deactivated, stopped), cross-platform Window lifecycle events, backgrounding and resume behaviour, platform-specific lifecycle mapping for Android and iOS/Mac Catalyst, and state-preservation patterns. USE FOR: "app lifecycle", "OnStart", "OnSleep", "OnResume", "backgrounding", "app state", "window lifecycle", "save state on background", "resume app", "deactivated event", "lifecycle events". DO NOT USE FOR: navigation events (use maui-shell-navigation), dependency injection setup (use maui-dependency-injection), or platform APIs (use maui-platform-invoke).
How do I install this agent skill?
npx skills add https://github.com/davidortinau/maui-skills --skill maui-app-lifecycleIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill provides standard documentation and best practices for .NET MAUI application lifecycle management. No malicious patterns or security vulnerabilities were detected.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
.NET MAUI App Lifecycle
Critical Behavioral Gotchas
⚠️ Resumed ≠ first launch
Resumed only fires when returning from the Stopped state. On first launch the sequence is Created → Activated — Resumed is never called.
// ❌ Putting initialization logic in OnResumed — won't run on first launch
protected override void OnResumed()
{
LoadUserProfile(); // Skipped on cold start!
}
// ✅ Use OnActivated for logic that must run on every foreground entry
protected override void OnActivated()
{
LoadUserProfile(); // Runs on both first launch and resume
}
⚠️ Deactivated ≠ Stopped
A dialog, split-screen, or notification pull-down triggers Deactivated without Stopped. Don't save heavy state on Deactivated — the app may never actually background.
// ❌ Heavy save on every deactivation — fires too often
protected override void OnDeactivated()
{
await SaveAllDataToDatabase(); // Wasteful for a dialog appearance
}
// ✅ Save state only when truly backgrounded
protected override void OnStopped()
{
await SaveAllDataToDatabase();
}
⚠️ Android back button skips Stopped
On Android, pressing the hardware back button may call Destroying without Stopped if the activity finishes. Critical save logic in OnStopped alone can be missed.
// ✅ Save in both Stopped and Destroying for safety on Android
protected override void OnStopped()
{
base.OnStopped();
SaveDraft();
}
protected override void OnDestroying()
{
base.OnDestroying();
SaveDraft(); // Catches Android back-button finish
}
⚠️ Multiple windows fire independently
On iPad, Mac Catalyst, and desktop Windows, each Window instance fires its own lifecycle events independently. Don't assume a single global lifecycle.
Performance: Keep Handlers Fast
Long-running work in lifecycle handlers causes ANR kills on Android (5s timeout) and watchdog kills on iOS (limited background time).
// ❌ Blocking the lifecycle handler
protected override void OnStopped()
{
Thread.Sleep(3000); // ANR on Android!
SaveData();
}
// ✅ Fire-and-forget or use a brief async save
protected override void OnStopped()
{
base.OnStopped();
Preferences.Set("draft_text", _viewModel.DraftText); // Fast, synchronous
}
For larger state, use SecureStorage or file-based serialization — but keep it under 1–2 seconds.
iOS Scene Lifecycle
iOS 13+ uses the scene lifecycle (SceneWillConnect, etc.). Older delegate methods are still forwarded by MAUI, but you should target scene-based APIs for modern iOS.
State Preservation Checklist
- Transient UI state (scroll position, draft text) saved in
OnStopped - State restored in
OnResumed— not inOnActivated(avoid double-restore) - No heavy I/O in
OnDeactivated— it fires too frequently - Android: critical save logic also in
OnDestroying(back-button case) - Lifecycle handlers complete in under 2 seconds
- Multi-window apps handle per-window state independently
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/davidortinau/maui-skills/maui-app-lifecycle">View maui-app-lifecycle on skillZs</a>