How to migrate Xamarin to MAUI: A step-by-step guide  

The end of Microsoft’s official Xamarin support on May 1, 2024, became a new beginning for businesses willing to adopt the future of cross-platform development with .NET MAUI. If your company is among them, this guide will walk you through the MAUI’s advantages and provide practical guidance for a smooth migration process. 

Why do you need to migrate from Xamarin to .NET MAUI?  

For organizations dependent on Xamarin, moving to .NET MAUI not only extends the lifespan of their apps but also offers future-proofing advantages.  

The first point in favor of .NET MAUI is that Microsoft is committed to supporting it for many years, which means you can be confident your apps will remain supported and updated. 

The second one is that .NET MAUI is an open-source project, which makes it more accessible to developers and automatically makes them a part of a large and open-minded community. This can be helpful if you need assistance in problem-solving or want to contribute to the project. 

Eventually, .NET MAUI is Microsoft’s latest and greatest cross-platform development platform and the future of cross-platform development. It is built on .NET 9 — the latest version of the .NET framework and offers several solid advantages over Xamarin.  

Benefits of Xamarin to .NET MAUI migration  

MAUI offers an advanced development framework that combines the familiarity of Xamarin with the powerful features of .NET 9. Unlike Xamarin, which requires separate projects for each platform, .NET MAUI adopts a single project structure that simplifies the process of building and maintaining cross-platform applications. This unified approach allows developers to allocate resources more effectively. 

MAUI is feature-rich and supports custom MAUI handlers and native controls. Eventually, it’s a newer framework than Xamarin. There is a lower chance of bugs or security vulnerabilities, which in turn means reduced maintenance costs. 

Xamarin to .NET MAUI migration: Pre-migration checklist  

While being a successor to Xamarin, .NET MAUI still requires a carefully planned migration process to ensure all existing functionalities transition smoothly to the new framework. Preparing the environment and yourself is crucial. The following is a checklist of vital steps to complete before migrating. 

Ensure all your Xamarin.Forms code is compatible with .NET MAUI. Do the same for any custom renderers or platform-specific code that might need adjustments to fit into the new framework. Use .NET Upgrade Assistant or Visual Studio’s built-in NuGet package explorer to spot problems early on. Adjust third-party libraries and NuGet packages to ensure they are compatible with .NET MAUI. 

Familiarise yourself with the new project layout and functionalities of .NET MAUI, such as the single-project approach and improved performance capabilities.  

Make sure to back up your Xamarin project and use version control systems such as Git to monitor modifications and enable reverting if necessary.  

Build a clear migration plan to allow troubleshooting and testing while maintaining functionality at every step throughout the run. Set up performance standards for the post-transitional comparison.  

Review your user interface (UI) layouts and adjust them to take advantage of the latest controls and layouts in .NET MAUI and make your design look great on various screen sizes.  

Prepare emulators and devices to test the migrated app.  

Collect the documents and migration instructions from Microsoft and sources within the community network.  

Best ways for seamless migration from Xamarin to.NET MAUI  

Xamarin.Forms migration to MAUI can be done in two ways: manually and with .NET Upgrade Assistant. 

As the name suggests, manual migration refers to manually migrating each file of the Xamarin project to a newly created MAUI one. This method requires much effort but proves to be the best for large and complex projects.  

Manual migration: A comprehensive approach 

Manual migration is a meticulous process that involves migrating every file from an existing Xamarin project to a newly created .NET MAUI project. While this approach requires significant effort and expertise, it provides greater control over the migration process and is well-suited for large, complex projects with unique requirements. 

Manual migration ensures the resulting application is better tailored to meet the organization’s needs. With careful planning and execution, it lays the foundation for leveraging .NET MAUI’s advanced features. Here’s how to successfully carry out manual migration: 

1. Prepare your Xamarin.Forms project: 

• Ensure your Xamarin.Forms project is updated to version 5.0. 
• Update all dependencies to their latest versions to minimize compatibility issues during migration. 

2. Convert project files to SDK-style: 

• Modify your Xamarin.Forms project files to follow the SDK-style format used in .NET MAUI. 

3. Migrate code and dependencies: 

• Replace incompatible dependencies with MAUI-compatible ones. 
• Address any API changes by consulting official documentation or community resources. 
• Update namespaces from Xamarin.Forms to Microsoft.Maui and Microsoft.Maui.Controls. 

4. Adapt UI and functionality: 

• Redesign the user interface (UI) to leverage MAUI’s advanced controls and layouts, ensuring compatibility across devices. 
• Test functionalities thoroughly to maintain feature parity with the original Xamarin app. 

5. Configure .NET MAUI: 

• Set up your new MAUI project environment and configurations, including the UseMaui property in project files. 
• Adjust platform-specific implementations to align with MAUI standards. 

6. Test, debug, and optimize: 

• Continuously test your application on various devices and emulators to identify and resolve bugs or performance bottlenecks. 
• Optimize the app to utilize MAUI’s enhanced performance capabilities. 

Migration with .NET Upgrade Assistant 

.NET Upgrade Assistant helps you upgrade Xamarin.Forms projects to .NET MAUI by converting the solution’s project file and performing common code updates. Migrating with .NET Upgrade Assistant is extremely simplified, and the tool is a big time-saver. Here’s how to use it properly step-by-step. 

Step 1: Before migration, ensure your Xamarin.Forms project is updated to version 5.0 and running on .NET Standard 2.0 or higher for the best results. 

Step 2: If you’re using Visual Studio on Windows, install the .NET Upgrade Assistant from the Extensions menu. For CLI, use the command: 

• dotnet tool install -g upgrade-assistant 

To update the tool, use: 

• dotnet tool update -g upgrade-assistant 

Note that if you have additional NuGet feed sources configured, you may need to use –ignore-failed-sources to avoid errors. 

Step 3: In Visual Studio, right-click on the project and select ‘Upgrade’. For CLI, navigate to your project folder and run: 

• upgrade-assistant upgrade 

This will update all eligible files within your project. 

Step 4: With the .NET Upgrade Assistant convert your project files to SDK-style projects, update target frameworks, set <UseMaui>true</UseMaui>, and handle NuGet package transitions: 

• Remove Xamarin.Forms and Xamarin.Essentials packages 
• Replace Xamarin.CommunityToolkit with .NET MAUI Community Toolkit 
• Update SkiaSharp packages for .NET MAUI compatibility 
• Replace Xamarin.Forms and Xamarin.Essentials namespaces with Microsoft.Maui and Microsoft.Maui.Controls  

Before migration, you must update your Xamarin.Forms platform projects to the SDK-style projects. To migrate a Xamarin.Forms library project into a .NET MAUI library project, you do the following: 

• Update your Xamarin.Forms app to use Xamarin.Forms 5 
• Update the app’s dependencies to the latest versions 
• Update your project file to be SDK-style 
• Update namespaces 
• Address any API changes 
• Configure .NET MAUI 
• Upgrade or replace incompatible dependencies with .NET 7+ versions 
• Compile and test your app 

Why migrate your Xamarin app to MAUI with Blackthorn Vision?  

Moving from Xamarin.Forms to .NET MAUI isn’t just about adopting a new technology; it’s about ensuring the viability and competitive advantage of your mobile applications. Xamarin remains in the past while .NET MAUI becomes a modern and powerful framework with a wide range of features and improved user experience.  

At Blackthorn Vision, we opt for manual migration as it has proven to be a more reliable approach, especially for projects with intricate structures and specialized needs. By carefully addressing each aspect of the migration process, we ensure the accuracy and stability of the final product, minimizing risks and ensuring long-term success. 

Contact us, and let’s keep your systems and your business up-to-date!