| name | dotnet-maui-development |
| description | Builds .NET MAUI mobile apps. Project structure, XAML/MVVM, platform services, caveats. |
| allowed-tools | ["Read","Grep","Glob","Bash","Write","Edit"] |
dotnet-maui-development
.NET MAUI cross-platform development: single-project structure with platform folders, XAML data binding with MVVM (CommunityToolkit.Mvvm), Shell navigation, platform services via partial classes and conditional compilation, dependency injection, Hot Reload per platform, and .NET 11 improvements (XAML source gen, CoreCLR for Android, dotnet run device selection). Includes honest current-state assessment and migration options.
Version assumptions: .NET 8.0+ baseline (MAUI ships with .NET 8+). .NET 11 Preview 1 content explicitly marked. Examples use the latest stable APIs.
Scope
- Single-project structure with platform folders
- XAML data binding with MVVM (CommunityToolkit.Mvvm)
- Shell navigation and platform services
- Dependency injection and Hot Reload
- Current-state assessment and migration options
- .NET 11 improvements (XAML source gen, CoreCLR for Android)
Out of scope
- MAUI Native AOT on iOS/Mac Catalyst -- see [skill:dotnet-maui-aot]
- MAUI testing (Appium, XHarness) -- see [skill:dotnet-maui-testing]
- General Native AOT patterns -- see [skill:dotnet-native-aot]
- UI framework selection decision tree -- see [skill:dotnet-ui-chooser]
Cross-references: [skill:dotnet-maui-aot] for Native AOT on iOS/Mac Catalyst, [skill:dotnet-maui-testing] for testing patterns, [skill:dotnet-version-detection] for TFM detection, [skill:dotnet-native-aot] for general AOT patterns, [skill:dotnet-ui-chooser] for framework selection, [skill:dotnet-accessibility] for accessibility patterns (SemanticProperties, screen readers).
Project Structure
MAUI uses a single-project architecture. One .csproj targets all platforms via multi-targeting, with platform-specific code in platform folders.
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
<TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">
$(TargetFrameworks);net8.0-windows10.0.19041.0
</TargetFrameworks>
<OutputType>Exe</OutputType>
<UseMaui>true</UseMaui>
<SingleProject>true</SingleProject>
<RootNamespace>MyApp</RootNamespace>
</PropertyGroup>
<ItemGroup>
<PackageReference Include="CommunityToolkit.Mvvm" Version="8.*" />
<PackageReference Include="CommunityToolkit.Maui" Version="9.*" />
</ItemGroup>
</Project>
Project Layout
MyApp/
MyApp/
App.xaml / App.xaml.cs # Application entry, resource dictionaries
AppShell.xaml / AppShell.xaml.cs # Shell navigation definition
MauiProgram.cs # Host builder, DI, service registration
MainPage.xaml / MainPage.xaml.cs # Initial page
ViewModels/ # MVVM ViewModels
Views/ # XAML pages
Models/ # Data models
Services/ # Service interfaces and implementations
Resources/
Fonts/ # Custom fonts (.ttf/.otf)
Images/ # SVG/PNG images (auto-resized per platform)
Styles/ # Shared styles, colors, resource dictionaries
Raw/ # Raw assets (JSON, etc.)
Splash/ # Splash screen image
Platforms/
Android/ # AndroidManifest.xml, MainActivity.cs
iOS/ # Info.plist, AppDelegate.cs
MacCatalyst/ # Info.plist, AppDelegate.cs
Windows/ # Package.appxmanifest, App.xaml
Properties/
launchSettings.json
MyApp.Tests/ # Unit tests
Resource Management
MAUI handles resource files declaratively. Images are auto-resized per platform from a single source:
<ItemGroup>
<MauiImage Include="Resources\Images\*" />
<MauiFont Include="Resources\Fonts\*" />
<MauiSplashScreen Include="Resources\Splash\splash.svg"
Color="#512BD4" BaseSize="128,128" />
<MauiIcon Include="Resources\AppIcon\appicon.svg"
ForegroundFile="Resources\AppIcon\appiconfg.svg"
Color="#512BD4" />
</ItemGroup>
For detailed code examples (XAML data binding, MVVM, Shell navigation, platform services, .NET 11 improvements, Hot Reload), see examples.md in this skill directory.
Agent Gotchas
- Do not create separate platform projects. MAUI uses a single-project structure. Platform-specific code goes in the
Platforms/ folder within the same project, not in separate Android/iOS projects (that was Xamarin.Forms).
- Do not mix MVVM Toolkit attributes with manual
INotifyPropertyChanged. Use [ObservableProperty] consistently. Mixing source-generated and hand-written property changed implementations causes subtle binding bugs.
- Do not call async methods in constructors. Use
OnAppearing() or a loaded command to trigger data loading. Constructor async calls cause unobserved exceptions and race conditions with binding context initialization.
- Do not use
Device.BeginInvokeOnMainThread. It is deprecated. Use MainThread.BeginInvokeOnMainThread() or MainThread.InvokeOnMainThreadAsync() from Microsoft.Maui.ApplicationModel instead.
- Do not hardcode platform checks with
RuntimeInformation. Use DeviceInfo.Platform comparisons (DevicePlatform.Android, DevicePlatform.iOS) which are MAUI's cross-platform abstraction for platform detection.
- Do not use
{Binding} without x:DataType. Always set x:DataType on the page and data templates to enable compiled bindings. Reflection-based bindings are slower and not caught at build time.
- Pages should generally be Transient, not Singleton. Singleton pages cause stale data and memory leaks from retained bindings. If state preservation is needed (e.g., tabbed pages), use a Singleton ViewModel with a Transient page.
- Do not forget to register Shell routes for non-tab pages. Pages pushed onto the navigation stack (via
GoToAsync) must be registered with Routing.RegisterRoute in AppShell constructor, or navigation throws RouteNotFoundException.
Prerequisites
- .NET 8.0+ (.NET MAUI ships with .NET 8+)
- MAUI workload:
dotnet workload install maui
- Platform SDKs: Android SDK (API 21+), Xcode (macOS only, for iOS/Mac Catalyst), Windows App SDK (for Windows)
- Visual Studio 2022+ with MAUI workload, VS Code with .NET MAUI extension, or JetBrains Rider 2024.2+
References
