News
New .NET MAUI Docs Detail How to Migrate from Xamarin.Forms
Among a raft of recent improvements to .NET MAUI, Microsoft has published new docs, including guidance on how to migrate from Xamarin.Forms.
Standing for .NET Multi-platform App UI, .NET MAUI has been described by the company as the "evolution of Xamarin.Forms" with said evolution including the ability to create desktop apps in addition to the traditional mobile targets of Xamarin, iOS and Android.
The new documentation was but one topic of yesterday's .NET MAUI Community Standup, which is regularly broadcast live on YouTube. Featuring Microsoft's Maddy Montaquila and David Ortinau, senior and principal .NET product managers for .NET, respectively, the standup presented the top five things developers might not know about .NET MAUI -- or might not be using already -- that they think are useful.
The new docs referenced were published on Microsoft's Learn site, with the titled ".NET Multi-platform App UI (.NET MAUI) docs: What's new for September 2023."
Three documents presented include:
"We have published some updated docs, in, particular help with migrating from Xamarin.Forms -- or upgrade as we like to say -- so if you are using the properties dictionary and you need to then move to .NET MAUI preferences, this is the doc for you," said Ortinau, pointing to the first item in the list that was actually published today, Oct. 6.
It explains how Xamarin.Forms has a Properties dictionary that can be used to store data, but when migrating a Xamarin.Forms app that stores data in the app properties dictionary to .NET MAUI, devs should migrate this data to .NET MAUI preferences.
Of the second item, Ortinau said: "I have gotten that request several times, and so I'm glad that we now have documentation for it, as well as how to use Essentials Secure Storage to now be MAUI Secure Storage."
That new guidance points out that while Xamarin.Essentials and .NET MAUI both have a SecureStorage class that helps devs securely store simple key/value pairs, there are implementation differences between the SecureStorage class in Xamarin.Essentials and .NET MAUI:
[Click on image for larger view.] Implementation Differences Between the SecureStorage Class in Xamarin.Essentials and .NET MAUI (source: Microsoft).
"And then if you want to collapse your multiple projects into a single project you can you now have a guide specifically about that," Ortinau said of the third item about manually upgrading a Xamarin.Forms app to a single project.
The documentation goes on to show how to simplify the upgrade process by creating a new .NET MAUI app of the same name as your Xamarin.Forms app, and then coping in your code, configuration and resources.
"And then a few up updates as well, more docs coming of course with the .NET 8 release, so excited to see more updates here," Ortinau said."
Docs receiving updates include:
For the former, the list of Xamarin project types that can be upgraded to .NET include:
[Click on image for larger view.] Xamarin Project Types that Can Be Upgraded to .NET (source: Microsoft).
The second item, concerning manually updating a Xamarin.Forms app to a muli-project .NET MAUI app (as opposed to doc above guidance about migrating to a single .NET MAUI project) is a task that comes with a lengthy list of things a developer must do first:
- Update your Xamarin.Forms app to use Xamarin.Forms 5.
- Update the app's dependencies to the latest versions.
- Ensure the app still works.
- Create a .NET MAUI app.
- Copy code and configuration from the Xamarin.Forms app to the .NET MAUI app.
- Copy resources from your Xamarin.Forms app to the .NET MAUI app.
- Update namespaces.
- Address any API changes.
- Upgrade or replace incompatible dependencies with .NET 7+ versions.
- Compile and test your app.
"Before upgrading your Xamarin.Forms app to .NET MAUI, you should first update your Xamarin.Forms app to use Xamarin.Forms 5 and ensure that it still runs correctly," the guidance says. "In addition, you should update the dependencies that your app uses to the latest versions.
"This will help to simplify the rest of the migration process, as it will minimize the API differences between Xamarin.Forms and .NET MAUI, and will ensure that you are using .NET compatible versions of your dependencies if they exist."
Ortinau welcomed more requests for new and better documentation, but noted the dev team needs as much information as possible when such requests are made. "One of the top feedback that we get through surveys is we need more docs, we need better docs, we need more samples, and that sort of thing," he said. "So if you are one that provides that feedback on a regular basis, my encouragement to you, please -- my pleading to you -- be specific. Tell me exactly the thing that you want us to show you and we can we can do that."
[Click on image for larger view.] .NET MAUI Upgrade (source: Microsoft).
One tool that might help in any migration efforts might be the .NET Upgrade Assistant, as detailed in recent Visual Studio Magazine articles, ".NET Upgrade Assistant Boosts MAUI as .NET 8 Nears GA" from last month and ".NET Upgrade Assistant Now Works with .NET MAUI, Azure Functions" from May.
"If you prefer to upgrade your Xamarin.Forms to .NET MAUI manually, we have added automatic code fixers to help you update your code," Microsoft is quoted as saying in last month's article. "Now you can paste your Xamarin.Forms files into a .NET MAUI project and our new Upgrade Assistant C# analyzer will offer to fix your code to make it compatible with .NET MAUI. You can see a light bulb near Xamarin namespaces that offers to fix the entire document or optionally project or solution."
About the Author
David Ramel is an editor and writer at Converge 360.