Migrating from Xamarin.Forms

Without a doubt, .NET MAUI is the successor of Xamarin.Forms, and most developers approaching .NET MAUI come from the Xamarin.Forms development experience. Microsoft stopped supporting Xamarin.Forms on May 1, 2024, so there are several reasons to migrate existing Xamarin.Forms solutions to MAUI: technology improvements, easier maintenance, and the end of support for Xamarin.Forms.

Microsoft provides a very detailed page about migration, with a strictly technical focus. This chapter provides, instead, information on how migrating a project works from a more general perspective.

.NET MAUI has been built in a way that migrating Xamarin.Forms solutions should be easy, but there are some caveats that you will discover in the sections that follow.

Note: The end of the official support for Xamarin.Forms means that Microsoft will no longer release updates and hotfixes. This includes support for new API levels that Apple and Google often require us to target in order to keep applications available in their stores. In addition, Microsoft is no longer obliged to reply to customers’ technical support requests.

General considerations

There are a few general, common considerations that apply to each solution you want to migrate:

·     Migrating Xamarin.Forms projects means migrating to .NET. Your existing code will likely work, but there might be breaking API changes that you will need to fix.

·     You will need to change XAML namespace references.

·     You will need to change C# namespace references.

Table 10 summarizes the namespaces you will need to update.

Table 10: Namespaces to be updated

This is the easiest part. Now it is time to analyze solutions for migration.

Analyzing existing solutions

Migrating a Xamarin.Forms solution to .NET MAUI certainly has costs, especially in terms of time and human resources. So, you need to carefully analyze your existing code and accurately plan the migration. The following list describes points that you should consider before you start:

·     Third-party components: Before you start migrating, make sure there is a .NET MAUI version of each third-party component you use in your Xamarin.Forms solution.

·     NuGet packages: Similarly, ensure there is a .NET MAUI version of each NuGet package, and more generally, of each dependency you have in your Xamarin.Forms solutions.

·     Custom renderers: If your Xamarin.Forms solutions include custom renderers, ensure you have an option to convert them to MAUI handlers. This might not always be possible in a simple way, and you might need to completely rearchitect your code.

·     Assets and resources: Ensure that all your assets and resource files are still supported in .NET MAUI.

This list is not exhaustive because a lot depends on the particulars of each solution, but it is a very good starting point. If you can satisfy all the listed points, you can start considering a migration from Xamarin.Forms to MAUI.

The next paragraphs describe the two possible options available at the time of writing. If you cannot satisfy the preceding points, do not worry, and do not be in a hurry. Third-party vendors will certainly upgrade their product suites to target .NET MAUI, so it might just be a matter of waiting. After all, waiting is not so bad. As time goes on, MAUI will undergo many improvements and will be more reliable.

Note: Before you start any migration process, it is a good idea to place your existing solutions under source control if you haven’t already. This will help you revert your changes easily.

The Upgrade Assistant

Microsoft is working on a tool called Upgrade Assistant, which is currently in preview, and whose goal is to help automate the migration process. The Upgrade Assistant has the more general purpose of helping migrate existing .NET solutions to .NET 8, so it is not limited to a Xamarin.Forms-to-MAUI migration.

The Upgrade Assistant is a command-line tool that creates a backup copy of your projects and attempts to change the namespaces as described in Table 10. Because it is in a preview state, it is neither a reliable tool nor an effective solution for migration—these are the reasons why this tool is only mentioned and not covered. In the future, it should be able to upgrade NuGet package references and take further steps.

Even if it is eventually built in a step-by-step wizard way, for now you need to run the tool against every project of a Xamarin.Forms solution, and this is not convenient. Keep an eye on the development status of the tool, but if you want to start migrating now, the manual approach is the best one.

Effective migration: Creating a new project

With the resources you have today, the most effective way to migrate a Xamarin.Forms solution to .NET MAUI is a manual migration. Assuming you have analyzed the availability of .NET MAUI resources for your existing code, this is how manual migration works:

1. Create a new .NET MAUI project.
2. Set up the platform properties to match your existing Xamarin-platform project’s settings.
3. Install the .NET MAUI version of all the third-party libraries, components, and NuGet packages that you also used in your Xamarin.Forms solution.
4. Copy all the asset and resource files into the .NET MAUI resource folders described back in Chapter 1.
5. Manually re-create the folder structure in your new project.
6. Manually copy all your C# code files.
7. Manually create all the necessary XAML files and copy both the XAML and C# code from the existing solution to the new one, paying attention to namespace references, as described in Table 10.
8. Fix all the API changes and code references that are different in .NET MAUI.

As you can see, migration is a very complex task, and it requires a lot of time and resources. However, if you plan to maintain your projects over a long time, it is something that you cannot avoid considering.

Chapter summary

This chapter provided practical suggestions on how to plan a migration from Xamarin.Forms to .NET MAUI, explaining all the necessary parts you must consider, such as libraries, custom renderers, and the project structure. As MAUI undergoes new releases, we can expect updates to the Upgrade Assistant tool that will help automate the process.

This book has given you the foundations for building cross-platform projects with .NET MAUI, explaining how you create and debug solutions, how you build the user interface with XAML, how you handle resources and navigation, and how you write platform-specific code, which includes managing the application lifecycle.

There is certainly much more to .NET MAUI, and updates will be released from Microsoft in the future, so it is recommended that you always keep an eye on the official documentation to stay up to date. Also, an upcoming ebook in the Succinctly series, dedicated to migration, will be available soon.