xamarin to maui migration
How to upgrade Xamarin to Maui
(for proper apps)
The clock is ticking
You've got
days!
Microsoft’s transition from Xamarin to Maui is fully underway and the clock is ticking on us poor devs to get our codebases updated. We have already spent time converting our apps over to Maui – this guide is based on the things we’ve learned. We hope it helps you in your upgrade process!
How you upgrade your code will obviously depend a lot on your current codebase. If it’s a really simple app, it may take a day or two. If it’s 10 years old with lots of legacy code, Xamarin.Native, Xamarin.Forms, Native Binding Libraries etc, it’ll probably be a bit more complex, and might take weeks.
What we cover in this blog:
Here are some things to consider – feel free to jump around and read the bits that apply to you:
Simple conversion
The Microsoft Upgrade Assistant can update Xamarin code bases to Maui. There are some good guides out there for using it. You point it at your codebase and it does things like updating some system Nugets, changing target frameworks, and adding in some Maui specific code files.
In our view, this might work on a fairly simple codebase but, if your app is a bit more complex, this quickly becomes quite a messy approach. You can give it a go by creating a fresh Xamarin.Forms app and then running the converter on it to see the changes.
If your codebase is a bit more complex, we’d recommend avoiding the tool, particularly if you currently make use of any custom navigation or Mvvm structures e.g. MvvmCross.
More complex apps
So your app has more than one button?! Here are some things to consider if you’re upgrading a more complex app.
Create a fresh Maui project
We’ve found it much easier to start with a fresh Maui project rather than to try to update an existing Xamarin.Forms project. Whilst this gives you more work in copying/moving things around, you end up with a much cleaner codebase. The other benefit is that you get the new Maui project structure e.g. Resources split into helpful sections.
The way we approach this is to:
- Create a new Maui Solution next to the existing Xamarin Solution.
- Create a new Maui page for each Xamarin page and copy the Xaml across.
This approach means that very quickly you’ll have a basic app with your first page which builds and runs, instead of a vast app with 1000 build errors! We find it’s much easier to start with something which works than to try to fix all the issues at once. (An obvious disadvantage is that you lose your source control history for the files – we had to weigh this up against the cleaner resulting code)
Navigation might be a challenge
If you’re using the Mvvm pattern, you’ve probably got code in your ViewModels for navigating between screens (e.g. user selects an item in a list, which fires a Command in the ViewModel, which checks some business logic and then makes a call to show the detail page for the selected item). In our apps we’ve used MvvmCross quite extensively for structuring our Mvvm code and navigation, but it looks as though MvvmCross won’t be carried forward into Maui. Regardless of how you’ve managed your Mvvm structure, upgrading to Maui might provide you with an opportunity to rethink this. However, if you do, this might be one of the more complex parts of your conversion process.
Consider using AppShell
Many of our apps were started before AppShell existed, but having tried it out, we like it! Therefore, whilst converting, we’ve sometimes changed tabs and navigation flow to work with AppShell. It works for standard use-cases, and abstracts a lot of messy code away. Another strong positive for us is that Microsoft seems to be strongly pushing it, which gives us confidence that it’s worth building on.
Images are getting easier
Getting your image sizes correct has always been a battle with mobile apps. Back in the day there would be thousands of image files with @3x everywhere on iOS, and on Android you’d have some xxxxxxxxxhdpi folders. Good times. As things have progressed, they’ve gotten a bit easier – we’ve sometimes used the excellent Resizetizer to make life better. Maui takes it a step further, allowing you to put vector-based svg files directly into the project for automatic generation of PNGs. For app conversion, we stuck with the PNG files we already had, but one gotcha was that the image filenames need to all be in lowercase – that led to some fairly intense renaming.
Our free upgrade report tool
We’ve created a free Maui upgrade report tool – just answer some simple questions about your codebase to get a bespoke report on things that you should be considering when upgrading.
3 ways to improve your codebase whilst upgrading
If you’re going to invest some time in upgrading your codebase, it’s perhaps a good opportunity to simplify, tidy or refactor code. Here are some suggestions
Consider using the inbuilt IoC
There’s an inbuilt IoC in Maui. You’ve probably used or looked at a whole bunch of IoC approaches over the years, and often the one you chose will (to some degree) affect the way you structure your code. The one Microsoft has given us seems to work well and removes the complexity of another dependency/library. (NOTE: a key consideration here might be how you’ve structured your Unit Tests)
C# 10 namespaces and usings
C# 10 introduces a couple of ways to keep your code files a little neater. Firstly, you can filescope your namespace declaration. This reduces the amount of nesting you need, making things slightly neater. Secondly, you can apply global usings across your codebase. This means that you can avoid adding repetitive and obvious usings at the top of each code file.
Consider AppShell
We mentioned it earlier – AppShell might not suit everyone’s needs, but if it does fit your scenario, it might be a great way to tidy up your code structure and simplify things.
Class libraries
You’ll likely have class libraries in your app solution in addition to your Xamarin projects. These might contain things you wanted to separate out for clarity and easier Unit Testing, or code that needs to be shared with other solutions. (e.g. repositories, services, ViewModels, Models, DTOs etc).
When converting, you’ve got a couple of options:
- a basic class library,
- a .NET MAUI class library
A .NET MAUI class library allows you to separate out code whilst still accessing the Maui namespace functionality.
The MAUI class library provides a structure for creating platform specific class code as shown below.
As you consider upgrading your code base, you might want to consider how a MAUI class library might play a part. One key consideration might be how your current Unit Tests need to interact with your codebase.
How long will it take?
There are a lot of things to consider when upgrading your codebase from Xamarin to Maui – how long it takes is a tricky question to answer. Are there parts of your codebase that will cause unexpected problems? Will all your libraries be supported? We’ve created a package to help you easily identify the risks and make the right choices for you.
How it works:
We’ll analyse your codebase and produce a report for you including:
- A list of all your Nugets/dependencies, highlighting any that may have compatibility issues
- An analysis of your navigation flow with suggestions for any issues spotted
- An analysis of your UI/renderers, looking for areas that might need attention
- Suggestions around device specific functionality e.g. storage, GPS, connectivity etc
- A suggested project plan describing the order and steps that we’d recommend you follow to upgrade
Once you’ve had a chance to read through the report, we’ll set up an hour-long video call with a senior dev where you can ask any questions you may have.
The report will help you skip the learning curve and allow you to focus on writing great software. If you’re interested in this, Sol would love to explain more.
