Migrating from Xamarin.Forms to MAUI

If you want to convert your Xamarin.Forms apps to .Net MAUI (Multi-platform App UI), then no need to rewrite code. You just need to change some basic code in each app. Here are some basic steps to convert your app into MAUI.

Steps to Migrate Xamarin.Forms to MAUI:

1. Convert the projects from .NET Framework to .NET SDK style.
2. Update namespaces.
3. Update any incompatible NuGet packages.
4. Address any breaking API changes.
5. Run the converted app and verify that it functions correctly.

• Use Xamarin.Forms using Xamarin.Forms 5.0 or higher
  • iOS project
  • Android project
  • UWP project
  • iOS App extension and other extension types, for example, the Share Extension project
• Install and set up all necessary workloads for .NET MAUI. Test your environment can build and run a .NET MAUI demo app.

Follow the below steps before starting the migration process:

• Create a backup of your project before starting working on migration. If you are using source control, create a branch to work on migration. You will refer to that as a copy and compare the original project.
• Use VSCode for global updates like namespace etc. It makes it easy to convert.
• Use Visual Studio 2022 Previews for Migration on Windows. Using this, you can easily and quickly build the project and find namespace, alias code, or references that need fixing. If you have installed all necessary workloads, you can migrate your Android and iOS projects to Windows. After Code compiles you can run and test the app on respective platforms.
• Use Visual Studio 2022 for Mac Preview 8 or newer previews for Migration on Mac. After Initializing the project, you can open sln in the IDE, then build the project and find them and fix it easily. After Code compiles you can run and test the app on respective platforms.
• Clean and build your project after every change you make, and it’s better to delete the bin/obj folders manually to make sure you are always testing the most recent changes.

Migration Steps

Step 1: .csproj files updates

• [Xamarin.Forms Project -> now .NET MAUI Project] Make the following updates to your project .csproj  
  • Important new Project properties:                    
• [Xamarin.iOS Project -> now .NET MAUI iOS Project] and [Xamarin.Android Project -> now .NET MAUI Android Project] Make the following updates to your project .csproj
  • Important new Project properties:
  • Copy over the project reference to the .NET MAUI Project using the old csproj file ProjectReference 

Step 2: Source Code Updates

• In your updated .NET MAUI project, add a new .cs file “MauiProgram.cs” and add the code for the MauiAppBuilder by referencing this file. 
• Refer to this official documentation For more information on App Startup.
• If you didn't have MainApplication.cs In the .NET MAUI Android project, add or edit your existing file and match this file.
• Edit MainActivity.cs to inherit from MauiAppCompatActivity and match this file.
• Update the android:targetSdkVersion="31" in AndroidManifest in the .NET MAUI Android project.
• Update AppDelegate.cs in the .NET MAUI iOS project, to inherit from MauiUIApplicationDelegate and match this file.
• Update Info.plist MinimumOSVersion to 15.2 in the .NET MAUI iOS project.
• Delete or comment out All three project heads in AssemblyInfo.cs files. You can re-enable all properties once you build and run an application without errors.
• Most of these properties are available now on .csproj properties as part of the new .NET MAUI .csproj, so be sure to check which ones you still need.
• Update the Global namespace, do a find and replace (best done in VSCode) for the following namespace changes:

• Remove Xamarin.Essentials because it’s distributed to various new namespaces. So, remove that and resolve each type individually.
• Check the Migrating documents per the preview version. Below are some known API changes, this is common ones you will see while migrating:
  • Colors is in Microsoft.Maui.Graphics
  • Shapes is in Microsoft.Maui.Controls
  • Color.Default DOES NOT EXIST == use ClearValue 
  • Color == Colors For example, Colors.Red;
  • Frame: BorderColor= "Accent" DOES NOT EXIST
  • ToolbarItem: Icon == IconImageSource
  • Button: Image == ImageSource
  • Span ForegroundColor DOES NOT EXIST
  • OSTheme == AppTheme

• For XAML update, please refer to the documentation. 

Step 3: Nuggets Updates

• Delete Xamarin.Forms and Xamarin.Essentials nuget references
• Replace Xamarin.Community Toolkit with the latest preview of .NET MAUI Community Toolkit

Step 4: Manually fix other build errors via IDE

After completing these changes successfully, you can open your main .sln file in VS2022 or VSM and continue to make further fixes. Build a project and check if there are any errors, if you have any errors, then you can work file-by-file to fix an error. Please use the sample projects as guidelines if you need them.

A common type of error seen is ambiguous, for example, error CS0104: 'ViewExtensions' is an ambiguous reference between 'Microsoft.Maui.Controls.ViewExtensions' and 'Microsoft.Maui.ViewExtensions' which can be fixed via explicit path or alias-ing.

Once the projects are compiled, run the migrated projects via dotnet cli using the following commands: (  -t: Run will run the app, so to only build, remove that from the command)

• iOS: dotnet build <path_to_iOS_csproj_file> -f net6.0-ios -c Debug -t:Run
• Android: dotnet build <path_to_Android_csproj_file> -f net6.0-ios -c Debug -t: Run

Limitations

• Must be on Xamarin.Forms 4.8 or higher
• Works only with Xamarin.Forms .slns (For Xamarin.Android and Xamarin.iOS solutions coming later)
• It will not work with binding or library projects
• You’ll still have to do some manual changes

Conclusion

Hence MAUI is new technology but in near future, it will be the leading technology, and migration of xamarin to maui will be required for the older apps. Always be sure to check the .NET MAUI site for the latest and upcoming changes.