Seamless migration: from Xamarin to .NET MAUI

Introduction: from Xamarin to .NET MAUI

Moving from Xamarin to .NET MAUI is an important step in the evolution of cross-platform applications. Xamarin enabled C# teams to build native iOS and Android applications from a single codebase. .NET MAUI develops this idea further by simplifying the project structure, improving performance and making native API easier to access. You gain a single source of truth for resources and configuration, a new rendering architecture, and a more modern approach to UI composition.

Migration to .NET MAUI is not just a tooling upgrade, but an opportunity to streamline architecture, increase performance, and improve both user and developer experience.

Plan your migration path

Before you begin, prepare a realistic action plan covering scope, risks and milestones. Xamarin reached end of support in May 2024, so it is worth prioritising business-critical projects.

- Inventory applications and libraries, and identify areas that require changes - Train the team on what is new in .NET MAUI and review best practices - Choose a navigation strategy and view structure, for example Shell in .NET MAUI - Align with the .NET roadmap and tooling updates to avoid regressions

Key architectural differences

The shift from multiple projects to a single project in .NET MAUI simplifies maintenance. Instead of working with separate projects for each platform, you work within one repository, while platform-specific code goes into the Platforms folder.

- Single project with multitargeting and unified configuration for resources, fonts and images - Handlers instead of renderers, providing better performance and more flexibility when customising controls - Built-in API familiar from Xamarin.Essentials, integrated directly into MAUI - A consistent startup pipeline and configuration in MauiProgram with dependency injection

Understanding these changes makes migration decisions easier and reduces technical debt.

Step by step: how to migrate

- Install the latest .NET tools and the .NET MAUI workload in Visual Studio - Create a new .NET MAUI project and configure MauiProgram, DI and services - Migrate the logic layer and ViewModels, starting with modules that have few dependencies - Copy and adapt XAML and code-behind, updating namespaces and styles - Replace renderers with handlers or mappers, adding extensions for custom controls - Move native code to the Platforms folders and apply conditional compilation where necessary - Replace Xamarin.Essentials calls with their .NET MAUI equivalents - Update or replace NuGet libraries with versions compatible with .NET - Configure application resources, fonts and images in one place, eliminating duplicates - Build and run the application on each platform, resolving warnings and errors step by step - Automate CI/CD for Android, iOS, Windows and MacCatalyst

Optimisation before migration

- Refactor and simplify logic, removing dead code and unused dependencies - Extract modules and domain boundaries to reduce coupling during migration - Tidy up the presentation architecture, for example MVVM with CommunityToolkit.Mvvm - Limit the number of UI libraries and effects that have no equivalents in MAUI - Standardise navigation and styles in preparation for Shell and shared resources

These actions shorten migration time, reduce risk and make scaling easier after the move to MAUI.

Common challenges and how to work around them

- Outdated API or lack of support in third-party libraries - Differences in application lifecycle and permissions across platforms - The shift from renderers to handlers and the need to write custom adapters - Issues with the resource pipeline, images and fonts on the platform side - Differences in linking, trimming and AOT affecting size and performance

How to deal with them

- Use official migration guides and the .NET Upgrade Assistant where possible - Replace unsupported libraries with alternatives or isolate them using adapters and interfaces - Create custom handlers for project-specific controls and test them per platform - Enable build diagnostics, analysers and warnings to catch regressions quickly - Implement changes iteratively, starting with the least risky modules

Testing after migration

- Unit tests for domain logic and ViewModels with service mocks - UI tests using automation tools on Android and iOS, plus manual testing on real devices - Regression tests comparing key user journeys before and after migration - Performance and resource usage tests with system profilers and .NET tools - Verification of accessibility, font scaling and dark mode on each platform - Telemetry and crash reporting after deployment to quickly identify user issues - Gradual rollouts and feature flags to introduce changes safely

Short migration checklist

- Decide on navigation in MAUI, for example Shell - Map renderers to handlers - Update namespaces and resources in a single project - Review and replace NuGet libraries - Verify permissions and application lifecycle - Configure CI/CD and the device test matrix

Summary

Migrating from Xamarin to .NET MAUI is an investment in simpler maintenance, better performance and a more consistent user experience. A well-prepared plan, an understanding of architectural differences, iterative delivery and reliable testing will ensure a smooth transition and deliver measurable business benefits.