The future of cross-platform mobile development is here—and it’s called .NET MAUI (Multi-platform App UI). As Xamarin.Forms reaches its end phase, developers and enterprises alike are exploring how to migrate Xamarin to .NET MAUI for a more streamlined, performance-driven, and maintainable codebase. But migration isn’t a simple upgra de; it’s a thoughtful transition that demands a solid plan.
This blog is a comprehensive, step-by-step Xamarin.Forms migration guide, designed to help you move confidently from Xamarin to MAUI. Whether you’re maintaining a legacy Xamarin.Forms app or preparing your product for future scalability, this guide simplifies the .NET MAUI migration process.
Why Move to .NET MAUI?
Let’s begin by understanding what makes this transition worthwhile. Xamarin.Forms served its purpose well, but .NET MAUI takes things several notches higher. It consolidates mobile and desktop development into a single project architecture, unifies platform APIs, and enhances performance with better rendering and deployment support. If you’re looking to modernize your app while reducing maintenance overhead, MAUI is the natural next step.
For a broader look at how the ecosystem is evolving, check out our detailed breakdown on Xamarin and .NET MAUI: The Future of Cross-Platform Development.
Preparing for the Migration
Migration begins not with code but with preparation. First, ensure your development environment is up to date. You’ll need Visual Studio 2022 (version 17.3 or later) with the .NET MAUI workload installed. Also, make sure your current Xamarin.Forms app uses a relatively modern architecture such as MVVM, as this will make the migration significantly smoother.
You should also audit your app for third-party dependencies, custom renderers, and platform-specific code. Not all Xamarin libraries are compatible with .NET MAUI, so having a compatibility matrix or list of replacements handy will save time later.
Steps to shift from Xamarine.Forms to Net Maui
Once you’re prepared, you’re ready to start the actual Xamarin.Forms to .NET MAUI migration.
Step 1: Create a Fresh .NET MAUI Project
Instead of trying to convert your existing Xamarin.Forms project, start fresh. Using Visual Studio, create a new .NET MAUI App. This gives you a clean base with the new single-project structure.
Why start fresh? Because MAUI projects are fundamentally different under the hood. Copy-pasting a Xamarin.Forms project and tweaking it can result in configuration issues and broken dependencies. A clean MAUI scaffold ensures you’re aligned with the latest project architecture and file structure.
Step 2: Move Core Business Logic and Resources
Once your new project is ready, begin migrating your core logic. Move your ViewModels, Models, and Services first. These are usually independent of the UI and require minimal changes, aside from namespace updates.
For resources like images and fonts, MAUI uses a different approach. Instead of placing assets under platform-specific folders, everything now goes into a central Resources folder. Update your paths and configure your MauiProgram.cs accordingly to register fonts, handlers, and dependencies.
Step 3: Update the UI and Navigation
The UI migration is where you’ll spend most of your time. While XAML remains the primary markup language, some controls and layouts have changed. For instance, StackLayout is still available, but you’re encouraged to use the more performant VerticalStackLayout and HorizontalStackLayout.
Additionally, you’ll need to replace Xamarin.Forms namespaces with Microsoft.Maui.Controls and other updated references. Custom renderers must be replaced with Handlers, which are MAUI’s new extensibility mechanism for customizing native controls. This step often involves architectural tweaks and may benefit from a phased approach—start with the main pages and iterate through the rest.
Navigation is largely similar, but with subtle changes. If you use Shell navigation, most patterns will work as-is, though the Shell structure itself has a few enhancements in MAUI.
Step 4: Replace or Update Dependencies
Most Xamarin.Forms projects rely on third-party libraries—and this is where many migrations hit snags. Some libraries have official .NET MAUI versions, while others are deprecated. For example, Xamarin.Essentials is now baked into MAUI by default, so you can remove it as a separate package.
If you’re using the Xamarin.CommunityToolkit, it should be replaced with its MAUI counterpart, CommunityToolkit.Maui, which you can install via NuGet and initialize in your MauiProgram.cs.
Make sure to check each dependency’s documentation for migration tips. If there is no MAUI version, explore alternatives or consider implementing the required functionality natively using platform APIs and conditional compilation.
Step 5: Handle Platform-Specific Code
One of MAUI’s strengths is how it organizes platform-specific code. Instead of maintaining separate projects, you now have Platforms/Android, Platforms/iOS, and so on within the same project structure.
You can use preprocessor directives like #if ANDROID or #if IOS to implement platform-specific logic. This makes your code cleaner and easier to maintain while offering the same level of customization.
Any permissions, services, or integrations tied to a specific OS should be migrated and tested individually, especially if you rely on deep integrations like camera, notifications, or background services.
Step 6: Test and Optimize
With your app migrated, it’s time to build and test it thoroughly. Start with one platform—typically Android or Windows—and validate the entire workflow. Once stable, move on to others. Pay close attention to navigation, rendering, API calls, and third-party integrations.
Also, explore MAUI-specific performance tuning features. Thanks to reduced overhead and a unified rendering pipeline, MAUI apps generally start faster and consume fewer resources—but this only holds if everything is configured correctly.
Use tools like the .NET MAUI profiler and built-in Visual Studio diagnostics to measure memory usage, load time, and render speed.
Step 7: Final Cleanup and Deployment
After testing, perform a final cleanup. Remove any deprecated Xamarin code or configuration files you may have ported during the migration. Standardize naming conventions, organize platform folders, and update app icons, splash screens, and metadata as per MAUI’s standards.
Finally, set up your deployment pipelines. MAUI works well with Azure DevOps, GitHub Actions, and other CI/CD platforms, thanks to the unified project format. Whether you’re targeting App Store, Play Store, or Microsoft Store, the deployment process is now more predictable and consistent.
Looking Ahead
The move from Xamarin.Forms to MAUI is more than just a framework upgrade—it’s a shift to a unified, future-ready platform designed for performance, scalability, and long-term support. With MAUI being an official part of .NET, it benefits from the entire ecosystem’s stability and evolution.
Taking a deliberate, phased approach to this Xamarin to MAUI upgrade not only reduces risk but also gives you the opportunity to modernize your architecture, clean up legacy code, and leverage the latest development tools.
Need Help Migrating?
If you’re short on time or need technical guidance during your .NET MAUI migration, partnering with experts can accelerate the process. Whether you’re porting a large enterprise app or refactoring a small prototype, having the right strategy makes all the difference.
Get in touch with our mobile team to ensure a smooth transition from Xamarin.Forms to .NET MAUI—future-proofing your app with the latest Microsoft stack.
HybridAppBuilders
Latest posts by HybridAppBuilders (see all)
- Migrating from Xamarin.Forms to .NET MAUI: a step-by-step guide - May 29, 2025
- How AI is Transforming React Native App Development - May 22, 2025
- How to Find the Perfect UI/UX Designer for Your Mobile App Project - May 16, 2025