So You Want to Migrate a Xamarin.Forms App to .NET MAUI

.NET MAUI is out, Xamarin.Forms support will end on May 1, 2024, and you are probably thinking “How can I migrate my Xamarin.Forms app to this new .NET MAUI framework?”

Fear not, my fellow developers! I shall provide an example of how we can migrate an app to .NET MAUI. However, there are some requirements you need to meet first before you can migrate an app, and those are:

  • Your Xamarin.Forms app needs to use Xamarin.Forms 5.0 or higher, Android 5.0 (API 21) or higher, and iOS 10 or higher
  • You need to have installed the complete environment setup for .NET MAUI including all necessary workloads. (And just in case, you might want to verify that you can create and run a default .NET MAUI application first)

For some older applications, those might not be trivial upgrades, so make sure you account for that in your planning. Once you have met the requirements listed above, you can begin with the upgrade! However, it’s recommended that you perform the migration in a separate branch of your code so you can roll back to the previous state just in case you break something. A large portion of the migration process involves fixing your code to adjust it for this new framework.

For this example, I’ll use the default Xamarin.Forms project template and name it MauiMigration. I created it using Visual Studio 2019 Version 16.11.18. The migration will be performed in Visual Studio 2022 Version 17.3.4.

The Automatic Part

You can manually migrate your app, but there are some tools to make our life easier. This awesome upgrade assistant can take care of those basic or repetitive tasks for you.

To get the latest version of the assistant, you can clone the repo linked above, load it in VS 2022, and open this file:
“upgrade-assistant\src\cli\Microsoft.DotNet.UpgradeAssistant.Cli\Properties\launchSettings.json”.

The “launchSettings.json” file is where we configure which solution we would like to migrate. As you might have guessed, we need to modify what’s in the “Upgrade” block of this file. Conserve the commandName and change the commandLineArgs to your solution’s .sln file path:

"Upgrade": {
   "commandName": "Project",
   "commandLineArgs": "upgrade C:\\Repos\\MauiMigration\\MauiMigration.sln",
   "environmentVariables": {
      "DOTNET_ENVIRONMENT": "Development"
   }
},

Set Microsoft.DotNet.UpgradeAssistant.Cli as your Startup Project, Select the Upgrade option from the dropdown to run the solution, and it will open a terminal. What you need to do first is select the entry point. Select the first option by typing 1 and then Enter. It will show the available projects in the solution. In this case, I’ll begin with my Android application so I’ll select the second option.

The assistant is pretty straightforward to use. Usually, you only need to select the “Apply next step” option and it will mainly take care of changing the namespaces, removing the unsupported libraries, and adding new .Net Maui packages. Once the tool has performed all the steps you should see this message informing you it’s done making changes in the Android project and it will begin with the Shared project.

Once it’s done updating the Forms project, it will finish the update process. You can repeat these steps for the iOS project.

Now, let’s look at the changes:

  • You will notice you won’t find any reference to the Xamarin.Forms or Xamarin.Essentials NuGet packages. The using aliases for them should have been replaced by Microsoft.Maui and Microsoft.Maui.Controls as well.
  • If you check the .csproj files, you will see the TargetFramework element has net6.0-android;net6.0-ios instead of netstandard2.0 and it has a new element called UseMaui with true.
  • There is a new file called MauiProgram.cs. Each platform entry point calls a CreateMauiApp method on the static MauiProgram class in your app project, and returns a MauiApp, which is the entry point for your app
  • The Android csproj and iOS csproj files have been mostly rewritten. They no longer need to keep a reference for each platform-specific dependency.

The Manual Part

You have had fun watching the Upgrade Assistant do most of the work for you, but now it’s time to get your hands dirty. You will need some specific changes in our code to complete the migration.

First, open the “AppShell.xaml.cs” file and change the inheritance from “Xamarin.Forms.Shell” to “Shell”.

Next, open the MauiProgram.cs file and add the UseMauiCompatibility() method to the MauiApp builder.

Replace all instances of the xmlns=”http://xamarin.com/schemas/2014/forms” namespaces in your solution with xmlns=”http://schemas.microsoft.com/dotnet/2021/maui”.

Remove all the old references to Xamarin.Forms and look for replacements in MAUI. The “NewItemPage.xaml” page has some iOS specific platform configurations in Xamarin.Forms we should now migrate to MAUI (https://learn.microsoft.com/en-us/dotnet/maui/ios/platform-specifics/picker-selection).

Replace
“clr-namespace:Xamarin.Forms.PlatformConfiguration.iOSSpecific;assembly=Xamarin.Forms.Core”
with
“clr-namespace:Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;assembly=Microsoft.Maui.Controls”

Go to your MainActivity.cs file in the Android project and update the inheritance from “global::Xamarin.Forms.Platform.Android.FormsAppCompatActivity” to “MauiAppCompatActivity”. Then, delete the LoadApplication() call and everything related to Xamarin in the OnCreate method. Remove the OnRequestPermissionsResult method as well.

Remove the “Resource.designer.cs” file from your Android project.

Change your AndroidManifest to target SDK version 31.

Finally, for iOS, you only need to modify the iOS.csproj file like this:

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <UseMaui>true</UseMaui>
    <TargetFramework>net6.0-ios</TargetFramework>
    <OutputType>Exe</OutputType>
    <ImplicitUsings>enable</ImplicitUsings>

  </PropertyGroup>

  <ItemGroup>
    <ProjectReference Include="..\MauiMigration\MauiMigration.csproj">
      <Project>{B70FC50C-9208-4D8E-AA8B-0F0FB805FCCB}</Project>
      <Name>MauiMigration</Name>
    </ProjectReference>
  </ItemGroup>
</Project>

Replace my ProjectReference with your own in the code above. The data should be at the end of the unmodified iOS.csproj file.

That should be enough to make the app work with .NET MAUI! You can review more about the steps recommended by Microsoft here. You can also check out my repo if you want to take a look at the specific changes I made for this mini-guide.

Conclusion

And that’s it! Remember each project is different and the steps performed here may vary for you somewhat. Always be sure to check the .NET MAUI site for the latest changes!

Happy coding!

Related Blog Posts

We hope you’ve found this to be helpful and are walking away with some new, useful insights. If you want to learn more, here are a couple of related articles that others also usually find to be interesting:

Manage Your Windows Applications With Winget

Winget, Microsoft’s native package manager for Windows 10 (version 1709 and later) and Windows 11, offers a streamlined CLI for efficient application management. This blog post introduces Winget’s installation and basic commands for installing, updating, and removing software. It highlights the tool’s ability to manage non-Winget-installed apps and explores curated package lists for batch installations. The post also recommends top Winget packages, noting some may require a paid subscription.

Read More

Our Gear Is Packed and We're Excited to Explore With You

Ready to come with us? 

Together, we can map your company’s software journey and start down the right trails. If you’re set to take the first step, simply fill out our contact form. We’ll be in touch quickly – and you’ll have a partner who is ready to help your company take the next step on its software journey. 

We can’t wait to hear from you! 

Main Contact

This field is for validation purposes and should be left unchanged.

Together, we can map your company’s tech journey and start down the trails. If you’re set to take the first step, simply fill out the form below. We’ll be in touch – and you’ll have a partner who cares about you and your company. 

We can’t wait to hear from you! 

Montage Portal

Montage Furniture Services provides furniture protection plans and claims processing services to a wide selection of furniture retailers and consumers.

Project Background

Montage was looking to build a new web portal for both Retailers and Consumers, which would integrate with Dynamics CRM and other legacy systems. The portal needed to be multi tenant and support branding and configuration for different Retailers. Trailhead architected the new Montage Platform, including the Portal and all of it’s back end integrations, did the UI/UX and then delivered the new system, along with enhancements to DevOps and processes.

Logistics

We’ve logged countless miles exploring the tech world. In doing so, we gained the experience that enables us to deliver your unique software and systems architecture needs. Our team of seasoned tech vets can provide you with:

Custom App and Software Development

We collaborate with you throughout the entire process because your customized tech should fit your needs, not just those of other clients.

Cloud and Mobile Applications

The modern world demands versatile technology, and this is exactly what your mobile and cloud-based apps will give you.

User Experience and Interface (UX/UI) Design

We want your end users to have optimal experiences with tech that is highly intuitive and responsive.

DevOps

This combination of Agile software development and IT operations provides you with high-quality software at reduced cost, time, and risk.

Trailhead stepped into a challenging project – building our new web architecture and redeveloping our portals at the same time the business was migrating from a legacy system to our new CRM solution. They were able to not only significantly improve our web development architecture but our development and deployment processes as well as the functionality and performance of our portals. The feedback from customers has been overwhelmingly positive. Trailhead has proven themselves to be a valuable partner.

– BOB DOERKSEN, Vice President of Technology Services
at Montage Furniture Services

Technologies Used

When you hit the trails, it is essential to bring appropriate gear. The same holds true for your digital technology needs. That’s why Trailhead builds custom solutions on trusted platforms like .NET, Angular, React, and Xamarin.

Expertise

We partner with businesses who need intuitive custom software, responsive mobile applications, and advanced cloud technologies. And our extensive experience in the tech field allows us to help you map out the right path for all your digital technology needs.

  • Project Management
  • Architecture
  • Web App Development
  • Cloud Development
  • DevOps
  • Process Improvements
  • Legacy System Integration
  • UI Design
  • Manual QA
  • Back end/API/Database development

We partner with businesses who need intuitive custom software, responsive mobile applications, and advanced cloud technologies. And our extensive experience in the tech field allows us to help you map out the right path for all your digital technology needs.

Our Gear Is Packed and We're Excited to Explore with You

Ready to come with us? 

Together, we can map your company’s tech journey and start down the trails. If you’re set to take the first step, simply fill out the contact form. We’ll be in touch – and you’ll have a partner who cares about you and your company. 

We can’t wait to hear from you! 

Thank you for reaching out.

You’ll be getting an email from our team shortly. If you need immediate assistance, please call (616) 371-1037.