Jan 09, 2026 .
The Ultimate Guide to Migrating from Xamarin.Forms to .NET MAUI
The time has come. With official support for all Xamarin SDKs having ended, migrating your Xamarin.Forms applications to .NET Multi-platform App UI (.NET MAUI) is no longer a strategic option-it is a business and security necessity.youtube
But this transition should not be viewed as a mere technical chore. Migrating to .NET MAUI is a significant upgrade. It aligns your application with the future of the .NET ecosystem, offering a streamlined single-project structure, major performance enhancements through a new handler architecture, and a more unified development experience across iOS, Android, macOS, and Windows.
This guide provides a comprehensive, step-by-step approach to ensure your migration is as smooth and efficient as possible.
Migration Strategy: The .NET Upgrade Assistant vs. Manual Migration
Before you begin, you must choose one of two primary migration paths :
- .NET Upgrade Assistant: This is a command-line tool from Microsoft designed to automate much of the tedious work. It converts project files to the new SDK-style, updates dependencies, and handles common code updates. This is the ideal starting point for smaller, less complex projects.
- Manual Migration: For large, complex, or highly customized projects, a manual approach is often necessary. This involves creating a new .NET MAUI project and meticulously migrating every file. While it requires more effort, it provides granular control and is often better for tailoring the application to leverage MAUI's advanced features.
Recommendation: For most projects, the best strategy is a hybrid approach. Start by running the .NET Upgrade Assistant to handle the bulk conversion, then manually address the specific code changes, dependencies, and custom UI components that the tool cannot handle automatically.
The Step-by-Step Migration Plan
A successful migration is a planned migration. Follow these phases to ensure a structured and predictable process.
Phase 1: Pre-Migration Preparation
- Update Your Xamarin.Forms App: Before you do anything else, update your existing application to use Xamarin.Forms 5.0 and ensure all its dependencies (NuGet packages) are updated to their latest versions. This crucial first step minimizes the API differences between the two frameworks and simplifies the migration process.
- Audit Your Codebase: Thoroughly assess your existing code. Identify all third-party dependencies and check if .NET MAUI-compatible versions exist. Pay special attention to any custom renderers, as they will need to be completely rewritten as handlers in .NET MAUI.
-
Prepare Your Environment: Install the .NET Upgrade Assistant tool. You can install it as a Visual Studio extension or globally via the command line with
dotnet tool install -g upgrade-assistant.
Phase 2: The Core Migration Process
- Create a New .NET MAUI Project: The recommended approach is to create a fresh .NET MAUI project with the same name as your Xamarin.Forms app. This gives you a clean slate and avoids issues with legacy project file configurations.
-
Run the .NET Upgrade Assistant: From your project's folder in the command line, run the command
upgrade-assistant upgrade. This tool will convert your old project files to the modern SDK-style, update your target frameworks, and replace Xamarin.Forms NuGet packages with their .NET MAUI counterparts. -
Migrate Your Code, Assets, and Namespaces:
- Copy your core logic files (ViewModels, Models, Services) from the old project into the new one.
- Move your resources like images, fonts, and icons into the new, unified Resources folder in the .NET MAUI single-project structure.
- Perform a project-wide "find and replace" to update namespaces from
using Xamarin.Forms;tousing Microsoft.Maui.Controls;.
- Port Custom Renderers to Handlers: This is the most significant architectural change and will require manual effort. .NET MAUI replaces the renderer architecture with a faster, more flexible "handler" architecture. You will need to rewrite each custom renderer as a handler, following Microsoft's official documentation for this process.
Phase 3: Post-Migration Validation
- Address Incompatible Dependencies: The Upgrade Assistant may not catch everything. Manually review your NuGet packages and replace any incompatible dependencies with versions that support .NET 8 or higher. For UI components from vendors like Telerik, you will need to replace the Xamarin controls with their specific .NET MAUI counterparts.
- Compile and Test Thoroughly: Compile your new .NET MAUI application and conduct extensive testing on all target platforms-iOS, Android, Windows, and macOS. Pay close attention to UI layout inconsistencies and performance bottlenecks that may have emerged during the migration.
- Optimize and Refine: Once the application is stable, take advantage of .NET MAUI's new features to optimize performance and improve the user experience.
Overcoming the Biggest Challenges
- Dependency Management: The most common hurdle is finding .NET MAUI-compatible replacements for all your old third-party libraries. Start this research early.
- The Handler Architecture: The shift from renderers to handlers is a fundamental change that requires learning a new approach to UI customization. Allocate sufficient time for this part of the migration.
- API Changes: Even with the Upgrade Assistant, you will encounter breaking API changes that require manual code updates. Consult the official Microsoft documentation frequently.
By following this structured approach, you can transform the daunting task of migration into a strategic opportunity to modernize your application, enhance its performance, and secure its future on the .NET platform.
