dotnet-maui-development
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.
<!-- MyApp.csproj -->
<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:
<!-- Resources are configured in .csproj ItemGroups -->
<ItemGroup>
<!-- SVG/PNG images: MAUI resizes for each platform density -->
<MauiImage Include="Resources\Images\*" />
<!-- Fonts: registered automatically -->
<MauiFont Include="Resources\Fonts\*" />
<!-- Splash screen -->
<MauiSplashScreen Include="Resources\Splash\splash.svg"
Color="#512BD4" BaseSize="128,128" />
<!-- App icon -->
<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. UseMainThread.BeginInvokeOnMainThread()orMainThread.InvokeOnMainThreadAsync()fromMicrosoft.Maui.ApplicationModelinstead. - Do not hardcode platform checks with
RuntimeInformation. UseDeviceInfo.Platformcomparisons (DevicePlatform.Android,DevicePlatform.iOS) which are MAUI's cross-platform abstraction for platform detection. - Do not use
{Binding}withoutx:DataType. Always setx:DataTypeon 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 withRouting.RegisterRouteinAppShellconstructor, or navigation throwsRouteNotFoundException.
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
More from novotnyllc/dotnet-artisan
dotnet-csharp
Baseline C# skill loaded for every .NET code path. Guides language patterns (records, pattern matching, primary constructors, C# 8-15), coding standards, async/await, DI, LINQ, serialization, domain modeling, concurrency, Roslyn analyzers, globalization, native interop (P/Invoke, LibraryImport, ComWrappers), WASM interop (JSImport/JSExport), and type design. Spans 25 topics. Do not use for ASP.NET endpoint architecture, UI framework patterns, or CI/CD guidance.
127dotnet-ui
Builds .NET UI apps across Blazor (Server, WASM, Hybrid, Auto), MAUI (XAML, MVVM, Shell, Native AOT), Uno Platform (MVUX, Extensions, Toolkit), WPF (.NET 8+, Fluent theme), WinUI 3 (Windows App SDK, MSIX, Mica/Acrylic, adaptive layout), and WinForms (high-DPI, dark mode) with JS interop, accessibility (SemanticProperties, ARIA), localization (.resx, RTL), platform bindings (Java.Interop, ObjCRuntime), and framework selection. Spans 20 topic areas. Do not use for backend API design or CI/CD pipelines.
99dotnet-api
Builds ASP.NET Core APIs, EF Core data access, gRPC, SignalR, and backend services with middleware, security (OAuth, JWT, OWASP), resilience, messaging, OpenAPI, .NET Aspire, Semantic Kernel, HybridCache, YARP reverse proxy, output caching, Office documents (Excel, Word, PowerPoint), PDF, and architecture patterns. Spans 32 topic areas. Do not use for UI rendering patterns or CI/CD pipeline authoring.
90dotnet-testing
Defines .NET test strategy and implementation patterns across xUnit v3 (Facts, Theories, fixtures, IAsyncLifetime), integration testing (WebApplicationFactory, Testcontainers), Aspire testing (DistributedApplicationTestingBuilder), snapshot testing (Verify, scrubbing), Playwright E2E browser automation, BenchmarkDotNet microbenchmarks, code coverage (Coverlet), mutation testing (Stryker.NET), UI testing (page objects, selectors), and AOT WASM test compilation. Spans 13 topic areas. Do not use for production API architecture or CI workflow authoring.
86dotnet-advisor
Routes .NET/C# requests to the correct domain skill and loads coding standards as baseline for all code paths. Determines whether the task needs API, UI, testing, devops, tooling, or debugging guidance based on prompt analysis and project signals, then invokes skills in the right order. Always invoked after [skill:using-dotnet] detects .NET intent. Do not use for deep API, UI, testing, devops, tooling, or debugging implementation guidance.
60dotnet-debugging
Debugs Windows and Linux/macOS applications (native, .NET/CLR, mixed-mode) with WinDbg MCP (crash dumps, !analyze, !syncblk, !dlk, !runaway, !dumpheap, !gcroot, BSOD), dotnet-dump, lldb with SOS, createdump, and container diagnostics (Docker, Kubernetes). Hang/deadlock diagnosis, high CPU triage, memory leak investigation, kernel debugging, and dotnet-monitor for production. Spans 17 topic areas. Do not use for routine .NET SDK profiling, benchmark design, or CI test debugging.
57