Maui App Assets Lifecycle (.NET)

---
name: maui-app-assets-lifecycle
description: >-
  Configure MAUI assets and lifecycle. USE FOR: `MauiIcon`, `MauiSplashScreen`, images, fonts, raw assets, `OpenAppPackageFileAsync`, window lifecycle, `ConfigureLifecycleEvents`, resume/state restore, Xamarin asset migration. DO NOT USE FOR: localization, permissions, broad project structure.
metadata:
  origin: .NET
---

# 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

```xml
<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:

```csharp
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

| Area | Shared default | Platform override examples |
| --- | --- | --- |
| Icon | `MauiIcon` | Android adaptive icon details, iOS alternate icon metadata |
| Splash | `MauiSplashScreen` | Platform launch storyboard/theme customization |
| Bundled files | `MauiAsset` in `Resources/Raw` | Native-only files under `Platforms/*` |
| Lifecycle | `Window` events | `ConfigureLifecycleEvents` for native callbacks |

## 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.