So much has changed in the mobile development world in the past few years, and it continues to evolve at a breakneck speed. Microsoft's updates to .NET MAUI from Xamarin have been one of those things that I've kept pushing off while we can support apps. The time is coming, very rapidly, with Xamarin/Xamarin.Forms identifying iOS 16 as its final supported version we MUST upgrade. In this post, we will explore what was needed to migrate a project to .NET MAUI from Xamarin Forms as of June 2023.
Prerequisites to Upgrade
Microsoft continues to invest in tooling and guidance for the upgrade; however, a bit of pre-work on your side will make things easier. The Upgrade Assistant suggests a minimum of Xamarin.Forms 4.8, but recommends an upgrade to 5.0. In my experience, get to 5.0 first!
I also strongly recommend that you clean up anything extraneous in your project before starting a migration. During cleanup, I specifically focus on removing unused code, fixing build warnings, removing TODO comments, or other similar elements. More than anything, the cleaner your build is, the cleaner the upgrade will be, and the faster you can take action within your build warnings.
Step 1: Using the Upgrade Assistant
Thankfully, with current releases, the Upgrade Assistant is a huge help; however, the usage of the upgrade assistant is more complex than one might think. With existing Xamarin projects, you will have a `MobileProject,` `MobileProject.Android`, and a `MobileProject.iOS` project. Although you can point the upgrade assistant tool at the solution, you must execute the tool once per project to complete the upgrade.
Be sure to save the output of the process as you may have steps that you must take after.
Step 2: Perform Manual Migration Steps
The migration tool only gets you a portion of the way there. Microsoft has provided Manual Migration steps that should also be followed. These are steps that may not have been fully completed by the Migration tool, and it will save you time to run through this list first, then you can try to build your solution.
Step 3: Try to Build & Fix Warnings
The upgrade assistant does as much as possible, and in some cases where items were removed, it may leave incorrect code. Attempting to build your project is a quick method to get an understanding of what you might need to do. Additionally, you can use the "Task List" in Visual Studio and look for TODO comments, such as this one TODO Xamarin.Forms.Device.SetFlags is no longer supported., which we encountered on a project for a feature that was not supported anymore.
Resolve, update, or otherwise remove the items that impact your project. This is where sometimes an intermediate step of upgrading to 5.0 Xamarin.Forms before can help reduce the effort.
Optional Step 4: Switch to Single Project
Having migrated a few applications, I find that to get the full value of a Migration to .NET MAUI getting to the Single Project structure is a huge win for the long-term management of the projects. Images, Fonts, and other elements are so much easier to manage. I haven't found a great guide for this process, but I've found that you can do a little bit of detective work with a "File -> New Project" example and complete the tasks quickly.
Using a New Project alongside your existing project, I went through the following steps.
- Updated .csproj file to match the format of the new project structure. This did require multiple elements to be updated.
- Move files to their new homes in the single project structure. Specifically, the "Resource" elements, which MAY require you to find alternative-sized items to work with the auto-sizing completed by .NET MAUI
- Move the files from your iOS project to its proper Platform folder
- Move the files from your Android Project to its proper Platform folder
Doing this, at the same time, gets your project cleaned up even more and can result in a very rewarding future.
Common issues
Once I followed all of the steps, including the manual ones, the process went along pretty smoothly, currently averaging about 4-8 hours per project to transition. However, I did encounter some regular issues, especially during the intermediate steps that now that I am aware of I can quickly resolve, but lots loads of hours on before.
- Watch for Visual Studio explicitly adding files to the projects. This seemed to happen when moving files around, and the most unusual build errors occurred afterward. Simply deleting the entries from the .csproj, and all was right with the world.
- Don't forget to register fonts after you move them.
- When in doubt, "Clean" the project and restart Visual Studio. More than a handful of things were resolved by doing this.
- If your Apple Certificate includes a comma in the name, be on the lookout for another blog post!
In Summary
Migrations are going well; there are a lot of manual steps, but completing ALL of them before trying to run the application can really make the process easy. Application performance and startup on-device is superior, and your users will think you did amazing things without real change.
What has your experience been? Happy upgrading!