This is what I had to do to get my app converted to MAUI
TLDR; It was a less than optimal experience.
0. All old projects where updated
For this the Visual Studio Upgrade Assistant was used. It helped a lot with the upgrade, but missed a few referenced NuGet packages for Xamarin.Forms and did not sort the usings in any of the files (the added usings are not even sorted).
1. First try was to keep the current structure with separate project
But after fixing a few of the issues below and it did still not work satisfactory, I started over with a new project. Since the MAUI project template in Visual Studio uses one project for all platforms, that will probably be more used and have higher priority for Microsoft.
2. A referenced .NET Standard project had a space in the <PackageId>
That was a misstake from my side, but that space had been there for seven years, when the project was first created in 2017. At that time it was using .NET Standard 1.4 and none of the project upgrades since then has had any problem with that space.
And the error in Visual Studio for this issue was:
Error CS0006 Metadata file ‘D:[path to .NET Standard project]\obj\Debug\net8.0-android\ref\[project-name].dll’ could not be found
When comparing with other MAUI projects that did compile with proper PackageId (or no PackageId), that net8.0-android folder does not exist in the referenced project. Also when trouble shooting by removing and re-adding the invalid PackageId is somewhat inconsistent since the project has to be cleaned before the changes had any effect.
3. Upgraded old NuGet packages
Some NuGet packages in the project was targeting Xamarin.Froms and had to be updated or removed.
4. Created a new MAUI project
Since the new MAUI template is a single project and the old Xamarin project is four separate projects I started from scratch with a new project and copied the code manually to the new project.
5. Fixed compiler errors
Because of the new folder structure in the new MAUI project there was a few namespace collisions, which had to be fixed manually.
6. The app shows first page on Android
To check that the app starts properly on Android I changed the startup to only show the About page and that worked. After the previous issues this was a big relief.
7. The Windows app does not start
Now the app starts fine on Android, but on Windows it just starts and then crashes with a strange hex-code error.
The program ‘[4780] app.exe’ has exited with code 3762504530 (0xe0434352).
This was because the .gitignore was not updated for several years and the “launchSettings.json” was still ignored, so during the trouble shooting for the issue with the PackageId that file was removed. But I could not find any information on the web about this error. I found the error code, but none of the issues had anything to do with MAUI.
8. Switch the menu from MasterDetailPage to FlyoutPage
Yes, this should have been done a long time ago, but from what I can remember there was some issues when trying to switch earlier. And I think well tested code (that has been in production for a long time) is better than new code.
9. NavigationPage Title does not update
Now when a new page is loaded from FlyoutPage, the Title is not updated in the NavigationPage when a new page is pushed. The first page title that is shown when the app starts, stays there.
10. Switching to AppShell
So to get the page titles to work I switched to AppShell. AppShell is what Microsoft recommends and therefore will it probably higher prioritized in functionality and bug fixes. Switching to AppShell was easier than expected and a new version with new navigation made.
11. AppShell does not support TabbedPage
Now when the app is started every thing looks fine. But the most important pages in the app are tabbed pages and they do not load as expected. Not until i debug the app in Windows I get a proper exception that says that TabbedPage is not supported in an AppShell app.
That important information can will not appear until the runtime exception is hit.
To use AppShell, the TabbedPages must be rewritten. That means new untested code that could cause problems with the current stable app.
12. Switching back to NavigationPage
Re-writing the tabbed page or a bad title bar? Bad title bar seems like a more stable way to go. Tried several workarounds without any success. Then I found that the ToolbarItems are not updated either when a new page is pushed. So the filtering in the app will not work either.
Then at last I found that it was a bug that was fixed. The Visual Studio template for MAUI Apps references the NuGet package Microsoft.Maui.Controls with version “$(MauiVersion)”. It took a long time before I found the blog post that explained what $(MauiVersion) is and how it is supposed to work.
For some reason the Microsoft.Maui.Controls should not be updated like other NuGet packages, it is updated by changing the “<MauiVersion>8.0.6</MauiVersion>” in the project file. And of course, that property is not in the MAUI App template in Visual Studio.
13. Acr.UserDialogs does not work with WinUI
This is not a big issue, the project Acr.UserDialogs is no longer maintained. And the CommunityToolkit.Maui seems to have good replacements for this, but then it is new untested code again.
But it is yet another bump in the road towards the new MAUI App.
14. FlyoutPage crashes in WinUI
When using FlyoutPage (and MasterDetailPage) the code examples show that IsPresented should be set to false when the page has been shown.
But in WinUI the FlyoutPage is always visible and “IsPresented = false” throws a runtime exception. It looks like there is no way to detect if the FlyoutPage is always visible or not, because that property is always set to “Default”.
15. App initialization changed from Xamarin.Forms
In Xamarin.Forms the app had all the Android specific initialization in MainActivity.OnCreate(), but switching to MAUI that initialization is done after the MAUI App constructor is called and some things was not set up when the generic code was initialized.
16. Layout is inconsistent with Xamarin.Forms
When all these issues where fixed the migrated app is still unusable because of the xaml changes that was made between Xamarin.Forms and MAUI. There are changes in the grid layout and stack layout. For some reason that I haven’t found yet, most of the colors are wrong. Lots of text in the layouts are missing or cut off. Other text is stacked ontop of each others. Also, the padding has been intentionally changed in some of the controls, making buttons and text to shrink and be unusable.
17. CollectionView loads all items from ItemSource
All CollectionViews in the app was placed in StackLayouts. This was mostly because before the CollectionView, that was an easy way to add a header and a footer to a ListView.
In MAUI those CollectionViews stopped working (didn’t really stop, but it took minutes to load and used 1 GB extra of memory). After some debugging it turned out that the collection view in MAUI loaded all 600 items in ItemSource into memory, when Xamarin.Forms only loaded the first 30.
After some more digging it shows that it was another design change and CollectionView shall not be placed in StackLayouts anymore. Changing the StackLayouts to Grid fixed this problem.