Migrate your app from Xamarin.Forms

You don't need to rewrite your Xamarin.Forms apps to move them to .NET Multi-platform App UI (.NET MAUI). However, you need to make a small amount of code changes to each app. Similarly, you can use single-project features without merging all of your Xamarin.Forms projects into one project.

 Important

.NET Multi-platform App UI (.NET MAUI) is currently in preview. This content relates to a pre-release product that may be substantially modified before it's released. Microsoft makes no warranties, express or implied, with respect to the information provided here.

The process for migrating a Xamarin.Forms app to .NET MAUI is expected to be:

1. Use the .NET upgrade assistant for .NET MAUI to migrate your Xamarin.Forms projects to .NET MAUI single project, and perform well-known code namespace changes.
2. Update any dependencies to .NET 6 and .NET MAUI compatible versions.
3. Register any compatibility services or renderers.
4. Build and fix any issues.
5. Run the converted app and verify that it functions correctly.

 Warning

Do not currently migrate your production apps to .NET MAUI.

Port an app example

This example ports the Button Demos sample. The process is as follows:

1. Create a new, blank, multi-targeted .NET MAUI project:

   .NET CLICopy

    

   dotnet new maui -n ButtonDemos
   

2. Restore the dependencies for the newly created project:

   .NET CLICopy

    

   cd ButtonDemos
   dotnet restore
   

    Note

   If you are unable to restore project dependencies, ensure that you have the latest .NET MAUI preview installed.

3. Copy the code files (except App.xaml) into the newly created project.

4. In the newly created project, replace the following namespaces:

   TABLE 1

   Old namespace	New namespace
   xmlns="http://xamarin.com/schemas/2014/forms"	xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
   using Xamarin.Forms	using Microsoft.Maui AND using Microsoft.Maui.Controls
   using Xamarin.Forms.Xaml	using Microsoft.Maui.Controls.Xaml

5. Run the app on your chosen platform:

   .NET CLICopy

    

   dotnet build -t:Run -f net6.0-android
   dotnet build -t:Run -f net6.0-ios
   dotnet build -t:Run -f net6.0-maccatalyst
   

6. Examine any run-time errors, some of which will be due to incomplete handler availability.