Xamarin: Migrate your Xamarin Forms project to .NET MAUI

We at ELCA love Xamarin Forms. Over the years we realized many projects with it and hence have now the need to migrate those projects to Microsoft's new MAUI Framework. This articles gives a step by step guide, made from one of our projects, on how to do so. Please note: At the time of the writing, MAUI was still in Beta! Updating your current project to the latest Xamarin and Xamarin Forms version will make it easier to completely migrate it to MAUI. While updating Xamarin also update all dependencies in your project to the latest version and fix any issue that comes with it. MAUI will be part of .NET 6. Hence .NET 6 needs to be installed. If you are working on a Mac, as I am, you will need at least OSX 10.15 Catalina installed for .NET 6 to run smoothly. The easiest way to install .NET 6 is through Visual Studio. However, only Visual Studio 2022 will support it. At the time of the writing, for OSX, only a preview of Visual Studio 2022 is available, which you can download at https://visualstudio.microsoft.com/vs/mac/preview/ So far the preview is working fine for me and I didn't encounter any serious issues. Now the actual migration. In short there is no migration feature (yet), the migration process is a manual one. First of all the MAUI Template needs to be installed, to install it run: If you have it already installed make sure it is up-to-date. After that we have to install the workloads for the different platforms. Right now MAUI supports 4 platforms, Android, iOS, Mac and Windows. Windows comes out of the box so we have to install the others. Run the commands as an administrator to install the workloads: Once everything is correctly installed you can double check by opening Visual Studio (Preview) and when creating a new project you should now be able to see Multiplatform App with MAUI as an option. Open up your project in Visual Studio (Preview). We need to do changes on the Forms and Platform csproj files to let it know that we want to use MAUI from now on. Right click on your Forms csproj and choose Edit Project File (3 Option from the bottom) Adapt your top level Property Group to look like this: TargetFrameworks defines which .net version and platform is targeted by the project (Note, that TargetFrameworks was named TargetFramework ← no s, before) UseMaui is a boolean indicating if the project uses Maui or not OutputType defines as what kind of type the project will be exported. For the forms project that's a library as it will be referenced in the native parts of the solution. You will later see that the platform parts are exported as executables, using the Forms library. UseInterpreter defines if C# Hot Reload will be used or not. In this case it is set to true if the selected build configuration is Debug. SupportedOSPlatformVersion defines the highest sdk target of the according platform. It usually is the latest release of the native SDKs. After the Forms csproj file the platform csproj files need to be adapted to .net6 and maui as well. This also applies to any other csproj file like Unittests, UITests or Notification Extension projects. The Android csproj looks like this And the iOS csproj quite similar with the .net6 ios target instead of android According to documentation on how the startup of MAUI works https://docs.microsoft.com/en-us/dotnet/maui/fundamentals/app-startup NET Multi-platform App UI (.NET MAUI) apps are bootstrapped using the .NET Generic Host. This enables apps to be initialized from a single location, and provides the ability to configure fonts, services, and third-party libraries. Each platform entry point calls a CreateMauiApp method on the static MauiProgram class that creates and returns a MauiApp, the entry point for your app. This MauiProgram does not exist within our Forms solution, hence we have to creat it. In your former Forms project create a new class and name it MauiProgram. Create it on the top level of the project. As said in the documentation, this is a static class with a static function called CreateMauiApp that returns the MauiApp itself. A MauiApp is just a standard Class that derives from the Application class. In an already existing Xamarin Forms project you should already have an Application class defined. We just need to return that one using the MauiApp Builder pattern. Note: App in UseMauiApp is your Application class and the name can differ. Now that we have the MauiApp creator set up, we have to actually create the app in the different platforms. For Android, this is done in the MainApplication class. If you don't have an Application class yet, create it, otherwise edit your existing one. The MainApplication now has to inherit from MauiApplication and override the CreateMauiApp function, calling our just created static class. For iOS the creation of the MauiApp is done within the AppDelegate. The AppDelegate now needs to inherit from MauiUIApplicationDelegate and again override the CreateMauiApp function. MAUIs namespaces differ from those of Xamarin Forms. Hence we need to update the namespaces accordingly. 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 using Xamarin.Essentials => Microsoft.Maui.Essentials The easiest way is to search through the whole solution (Cmd+Shift+F) and replace all occurences at once. If you used RelativeLayout in your project, you have to adapt the namespace for it as it is now part of Maui Compatibility Controls. Add the new namespace to your XAML File then use it instead of the regular RelativeLayout Now some adjustments in the nuget packages. First of all remove all Xamarin.Forms references from the projects as well as Xamarin.Essentials (if used) If you are using the Xamarin.Community Toolkit, replace it with the Maui Community Toolkit https://github.com/CommunityToolkit/Maui If you are using SkiaSharp, replace it with the Maui version of SkiaSharp Now to the annoying part ;) As each project is individual and has specific set ups, the last thing to do is to fix any build errors that occur. As they are specific to your project, it is not possible to cover them in this article. Those are the basic steps to migrate from Xamarin Forms to the new Maui Framework. It is normal if you encounter issues not covered here as every project is unique and Maui is evolving quickly to a stable release. We can expect a smoother and more stable migration process in the future.