Xamarin to .NET MAUI Program Playbook
Migrate a legacy Xamarin.Forms app to its supported successor, .NET MAUI, before Xamarin end of support bites. Triage dependencies, migrate the single-project structure, port renderers to handlers, validate module by module, and retire the Xamarin build after stabilization.
Xamarin to .NET MAUI Program
Xamarin reached end of support in May 2024, and .NET MAUI (Multi-platform App UI) is its supported successor for building cross-platform mobile and desktop apps from one C# codebase. This playbook migrates a Xamarin.Forms app to .NET MAUI before the lack of support becomes a security and tooling liability.
MAUI is an evolution of Xamarin.Forms, not a rewrite, but the project structure, dependency model, and the renderer-to-handler architecture all change. The program manages those changes methodically.
Phase-by-Phase
Assessment and Upgrade Path. Audit the Xamarin app, assess which NuGet dependencies have MAUI-compatible versions (the common blocker), and choose the upgrade path: in-place upgrade with the migration assistant or a fresh MAUI project that pulls code across.
Project and Dependency Migration. Migrate the project to the single-project MAUI structure, update or replace dependencies, and port custom renderers to the new handler architecture. Custom renderers are usually the largest porting cost.
Feature Validation. Validate screens module by module, keeping the Xamarin build releasable behind feature flags as a fallback. Match platform-specific behavior on both iOS and Android, and instrument crashes from the first MAUI build.
Release and Sunset. Validate store-review compliance, tune startup and rendering performance, and retire the Xamarin build only after the MAUI app is stable in production.
Team and Roles
An architect owns the upgrade path and handler migration. Mobile engineers port modules and dependencies. QA runs device-matrix regression. DevOps maintains dual-store CI and signing.
Risks and Mitigations
- Dependency incompatibility: triage every NuGet package for MAUI support before committing to an upgrade path.
- Platform-specific bugs: test both platforms on real devices each release.
- Performance regression: profile startup against the Xamarin baseline.
Success Criteria
The crash-free rate holds against the Xamarin baseline, release cadence recovers on the supported platform, and startup time stays within budget.
Tooling
Use the .NET MAUI upgrade assistant, dual-store CI with code signing, a device test farm, feature flags, and crash and performance monitoring.