Maui App Assets Lifecycle

MAUI App Assets and Lifecycle

Use this skill when a MAUI app needs app identity assets, packaged files, or state handling across start, stop, resume, and multi-window lifecycle events.

Workflow

1. Inspect the app project file and Resources folders before adding assets.
2. Use MAUI single-project item types for shared assets.
3. Put platform-only assets under the matching Platforms/* folder only when a shared MAUI asset cannot express the requirement.
4. For Xamarin.Forms asset migrations, explicitly map old Android drawable-*, iOS .xcassets, and iOS Info.plist UIAppFonts font registrations to MAUI MauiImage, MauiFont, Resources/Images, and Resources/Fonts.
5. Access bundled raw files through FileSystem.OpenAppPackageFileAsync.
6. Use Window lifecycle events for cross-platform app/window state.
7. Use ConfigureLifecycleEvents for platform-specific lifecycle hooks.
8. Persist user/session state before deactivation or stop; restore on resume or app startup.
9. Validate icon/splash/background behavior on each target platform.

Asset Item Types

<MauiIcon Include="Resources/AppIcon/appicon.svg" ForegroundFile="Resources/AppIcon/appiconfg.svg" Color="#512BD4" />
<MauiSplashScreen Include="Resources/Splash/splash.svg" Color="#512BD4" BaseSize="128,128" />
<MauiImage Include="Resources/Images/*" />
<MauiFont Include="Resources/Fonts/*" />
<MauiAsset Include="Resources/Raw/**" LogicalName="%(RecursiveDir)%(Filename)%(Extension)" />

Use vector SVG sources when possible and let MAUI generate platform-specific sizes. Avoid manually adding resized copies unless a platform requires a custom override.

When migrating from Xamarin.iOS, remove old UIAppFonts entries from Platforms/iOS/Info.plist; MauiFont generates those registrations. Keep font aliases in MAUI's font pipeline, typically with MauiFont items and ConfigureFonts() when explicit aliases are needed. Do not copy Xamarin Android drawable-* folders or iOS .xcassets directly into Platforms/* for images used by MAUI XAML/C#; put shared image assets in Resources/Images as MauiImage items.

Bundled Assets

Put read-only bundled files in Resources/Raw and open them with:

await using var stream = await FileSystem.OpenAppPackageFileAsync("seed.json");

Copy bundled data into app storage before editing it. Files in the app package are read-only.

Lifecycle Guidance

Cross-platform Window lifecycle events are the default place to coordinate state:

• Created
• Activated
• Deactivated
• Stopped
• Resumed
• Destroying

Use platform lifecycle hooks only for behavior that truly depends on native app events, such as Android activity callbacks or iOS scene/app delegate events.

State Preservation

• Save lightweight preferences in Preferences.
• Save larger state, drafts, and caches in app data files or SQLite.
• Persist in-progress work before Stopped or Destroying.
• Reconcile stale network data after Resumed.
• Treat each window as having separate UI/navigation state when multi-window is enabled.
• Keep background work platform-specific and explicit; do not assume arbitrary code continues running after the app is stopped.

Platform Configuration

Validation Checklist

• Shared assets use MAUI item types and live under Resources.
• Bundled files are read through FileSystem.OpenAppPackageFileAsync.
• Editable data is copied out of the app package.
• Xamarin migration guidance removes old UIAppFonts/Info.plist font registrations when MauiFont/ConfigureFonts() owns shared fonts.
• State is saved before stop/destroy and restored on startup/resume.
• Platform lifecycle hooks are isolated to platform-specific behavior.