.NET MAUI is a cross-platform framework that came to replace Xamarin.Forms. Today more and more Xamarin developers thinking about migration of their Xamarin projects to MAUI. This guide will help you to make this migration easier.
Before migration
First of all you need to check supported project types and minimum requirements. For today it's Xamarin forms apps that uses Xamarin.Forms 5.0 or higher and supported project types are iOS and Android (iOS App extension and other extension types currently not supported). Also it's better check whether nuget packages you currently using have updates or similar plugins that you can use with MAUI. The last thing to do is to make sure that your environment is ready to build MAUI projects. All you need to do is create blank MAUI project and check that it can run.
Project file changes
The first step of the migration is to make changes in .csproj according to MAUI project template so Xamarin project becomes .Net MAUI projects. The final result should look something like this:
For Xamarin.Forms project:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<TargetFrameworks>net6.0-ios;net6.0-android</TargetFrameworks>
<UseMaui>True</UseMaui>
<OutputType>Library</OutputType>
<ImplicitUsings>enable</ImplicitUsings>
</PropertyGroup>
<PropertyGroup Condition="'$(Configuration)|$(TargetFramework)|$(Platform)'=='Debug|net6.0-ios|AnyCPU'">
<CreatePackage>false</CreatePackage>
</PropertyGroup>
</Project>For Xamarin.iOS project:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<UseMaui>true</UseMaui>
<TargetFrameworks>net6.0-ios</TargetFrameworks>
<OutputType>Exe</OutputType>
<SupportedOSPlatformVersion>15.0</SupportedOSPlatformVersion>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\MauiMigrationApp\MauiMigrationApp.csproj">
</ProjectReference>
</ItemGroup>
</Project>For Xamarin.Android project:
<Project Sdk="Microsoft.NET.Sdk">
<PropertyGroup>
<UseMaui>true</UseMaui>
<TargetFrameworks>net6.0-android</TargetFrameworks>
<OutputType>Exe</OutputType>
<ImplicitUsings>true</ImplicitUsings>
</PropertyGroup>
<ItemGroup>
<ProjectReference Include="..\MauiMigrationApp\MauiMigrationApp.csproj">
</ProjectReference>
</ItemGroup>
</Project>! Possible issue
After migration of android I faced error:
/usr/local/share/dotnet/packs/Microsoft.Android.Sdk.Darwin/32.0.485/tools/Xamarin.Android.D8.targets(5,5): Error: java.lang.RuntimeException: com.android.tools.r8.CompilationFailedException: Compilation failed to complete, origin: /Users/user/.nuget/packages/xamarin.google.guava.listenablefuture/The possible ways to solve the problem are:
Set Target Framework to net7.0
Try to update plugins to the latest version
For iOS and Android projects you need to set references to main .Net MAUI project. Project references stay the same as they were in Xamarin projects so you can simply copy project references from old csproj files.
Code updates
MAUI Project
For the MAUI project you need to create file MauiProgram.cs and add the code for the MauiAppBuilder
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>()
.ConfigureFonts(fonts =>
{
fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
});
return builder.Build();
}
}MAUI Android Project
First you need to set android target sdk version to 31 in AndroidManifest (android:targetSdkVersion="31")
<manifest xmlns:android="http://schemas.android.com/apk/res/android" android:versionCode="1" android:versionName="1.0" package="com.companyname.migrationapp">
<uses-sdk android:minSdkVersion="21" android:targetSdkVersion="31" />
</manifest>The second step is to add or edit MainApplication.cs
[Application]
public class MainApplication : MauiApplication
{
public MainApplication(IntPtr handle, JniHandleOwnership ownership) : base(handle, ownership)
{
}
protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}Then you need to edit MainActivity so it would inherit from MauiAppCompatActivity
public class MainActivity : MauiAppCompatActivity
{
protected override void OnCreate(Bundle savedInstanceState)
{
base.OnCreate(savedInstanceState);
}
}MAUI iOS Project
The first step for iOS project is to edit AppDelegate.cs file so it would inherit from
[Register("AppDelegate")]
public partial class AppDelegate : MauiUIApplicationDelegate
{
protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}Then you just need to set MinimumOSVersion in info.plist to 15.2.
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
......
<key>MinimumOSVersion</key>
<string>15.2</string>
......
</dict>
</plist>List of iOS 15.2 supported devices:
iPhone 13, iPhone 13 Mini, iPhone 13 Pro, iPhone 13 Pro Max
iPhone 12, iPhone 12 Mini, iPhone 12 Pro, iPhone 12 Pro Max
iPhone 11, iPhone 11 Pro, iPhone 11 Pro Max
iPhone XS, iPhone XS Max, iPhone X, iPhone XR
iPhone 8 and 8 Plus
iPhone 7 and 7 Plus
iPhone 6s and 6s Plus
iPhone SE (1st and 2nd generation)
iPod touch (7th generation)
The remaining step for csproj files is to find and replace following namespaces:
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
Also you have to now that there was changes in API and Layouts and you need to resolve them individually. You can face problems with default spacing values because they were changed. List of all changes you can find there: https://gist.github.com/rachelkang/1297094190441a8ae5bb505343856bbe
Nuget Packages Updates
First of all you need to Delete Xamarin.Forms nuget references. If you using Xamarin Essential you have to delete this nuget reference too and namespaces and resolve them individually.
Then you have to update or replace other nuget packages.
Update your custom Nuget to MAUI
To upgrade your nuget package from Xamarin.Forms to .Net MAUI you need to change target framework to .Net 6 and replace all dependencies of Xamarin.Forms on .Net MAUI. Before it it's better to check all dependencies you have in your library and check whether they can be migrated/replaced too or not. After changing target framework to .Net 6 you can face some issues you'll need to fix. The complexity of migration highly depends on issues you get after changing to .Net 6 and dependencies on other libraries or projects you have.
The last step
The last step is to go through the list of build errors you have and fix them one by one. The most fixes in this section are some using statement resolving and small fixes.
Summary
In conclusion, I want to note that the migration itself is not very difficult and largely depends on the size of the project and the number of nuget packages that will have to be replaced or updated on MAUI. You can use Upgrade Assistant (https://github.com/dotnet/upgrade-assistant) to make first steps of the migration more comfortable but you still need to make manual changes. This tool is still under development so be aware of using it. After all of this steps you can consider to step to a single project instead of having android and iOS separately to correspond MAUI architecture
Comments