Skip to content

aalmada/Stationary / .agents/skills/dotnet-maui

dotnet-maui

Verified

Build, architect, debug, test, and publish .NET MAUI 10 cross-platform native apps for Android, iOS, Mac Catalyst, and Windows using C#, XAML, or C# markup. USE FOR: MAUI project configuration, single-project targeting, pages, layouts, controls, XAML, MVVM, data binding, CommunityToolkit.Mvvm, dependency injection, Shell navigation, handlers, platform integration, permissions, lifecycle, accessibility, localization, performance, trimming, Appium UI tests, Android/iOS/Windows publishing. DO NOT USE FOR: ASP.NET Core web UI, Blazor-only apps, Avalonia, WPF-only, Xamarin.Forms migration without MAUI target code, or generic .NET code with no MAUI UI or platform concern.

references/architecture-and-startup.md

View on GitHub
# Architecture And Startup

## Composition Root

- Build the app in `MauiProgram.CreateMauiApp`. Configure fonts, logging, handlers, configuration, and dependency registrations before `builder.Build()`; registrations are immutable afterward.
- Keep `App.xaml` for application resources and `AppShell.xaml` for root navigation. Create `Window` instances in `App.CreateWindow` when window lifecycle or multi-window behavior needs control.
- Use the single-project model: shared code and resources live at the root, while target configuration and native files live below `Platforms/`.
- Keep domain logic independent of MAUI types so it can be unit-tested without a device or UI host.

## Dependency Injection

| Registration | Use For | Avoid For |
| --- | --- | --- |
| `AddSingleton` | Stateless shared services, caches, settings, clients | Views, pages, native controls, user-specific transient state |
| `AddTransient` | Pages, view models, short-lived operations | A shared cache or long-lived connection owner |
| `AddScoped` | Explicitly created/disposed `IServiceScope` work units | Assumed per-page/per-navigation scope |

- Constructor-inject dependencies into services and view models. Register interface-to-implementation mappings at the composition root.
- MAUI has no automatic navigation scope; non-Blazor `AddScoped` services effectively behave as application singletons unless the app explicitly creates scopes.
- Do not resolve arbitrary dependencies from `IServiceProvider` in views or view models. Use a factory only when runtime selection is genuinely necessary.

## Project Configuration

- Target only platforms the product supports with `TargetFrameworks`; verify each target's supported OS and SDK workload in CI.
- Use conditional MSBuild properties or item groups for target configuration. Keep conditional compilation at platform boundaries.
- Add fonts with `ConfigureFonts`, images as `MauiImage`, raw files as `MauiAsset`, and app icons/splash screens with MAUI asset items.
- Add structured logging during startup and avoid logging secrets or personal data.

## Sources

- [Dependency injection](https://learn.microsoft.com/dotnet/maui/fundamentals/dependency-injection?view=net-maui-10.0)
- [Single project](https://learn.microsoft.com/dotnet/maui/fundamentals/single-project?view=net-maui-10.0)
- [App startup](https://learn.microsoft.com/dotnet/maui/fundamentals/app-startup?view=net-maui-10.0)
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall