Xamarin.Forms to .NET MAUI: A Worked Migration with Shared Tests

Support for Xamarin ended on May 1, 2024, and the documented way forward is .NET MAUI. Most descriptions of that upgrade are lists of renamed namespaces. This case answers a different question: after the upgrade, how do you know the app still behaves the same? It contains a Xamarin.Forms app, the same app on .NET MAUI, and one set of tests that runs against both.

The code is on GitHub: chudovo/application-modernization, case 03. The app tracks shipments and is a client of the service from the WCF to Web API case.

At a glance

BeforeAfter
FrameworkXamarin.Forms 5.NET MAUI on .NET 10
Projectsshared project plus one per platformone app project plus a core library
DependenciesDependencyService as a service locatorconstructor injection
Platform servicesone implementation per platformone implementation on .NET MAUI APIs
MessagingMessagingCenter with string keystyped messages
Navigationview models create and push pagesShell routes behind an interface
Custom controlone custom renderer per platformone handler mapping
View modelsreference Xamarin.Formsreference no UI framework

The starting point

The app has three screens: a list of shipments with a status filter and an offline mode, a detail screen where a shipment can be marked as in transit or delivered, and a form for a new shipment with a rate quote. It is written the way many Xamarin.Forms apps were written, with the framework’s global objects used directly from view models:

public class BaseViewModel : INotifyPropertyChanged
{
    // Every view model reaches for its dependencies through the service locator.
    protected IShipmentApi Api { get { return DependencyService.Get<IShipmentApi>(); } }
    protected IConnectivityService Connectivity { get { return DependencyService.Get<IConnectivityService>(); } }

    // Navigation and dialogs go through the global application object, so the view model creates pages itself.
    protected INavigation Navigation { get { return Application.Current.MainPage.Navigation; } }
}

OpenCommand = new Command<Shipment>(async s => await Navigation.PushAsync(new ShipmentDetailPage(s.TrackingNumber)));
MessagingCenter.Subscribe<BaseViewModel>(this, "ShipmentChanged", async sender => await LoadAsync());

Code like this cannot be compiled without Xamarin.Forms and cannot be tested without an application object, a navigation stack and a registered set of services. That is the real obstacle in a migration, more than the renamed namespaces.

Step 1: tests that run against the old app

The scenarios are written at screen level: appear, tap, type, check what the screen shows. The surprise was that they can run against the Xamarin.Forms app at all. Its shared project, with all pages and view models, still compiles as a .NET Standard library and runs on .NET 10 on Linux with a mocked platform layer. No device, no emulator, no Xamarin toolchain.

[Fact]
public async Task Marking_as_delivered_updates_the_detail_and_the_list_behind_it()
{
    await using var app = await AppHarness.StartAsync();
    await app.Appear();
    await app.Run(app.List.OpenCommand, app.List.Items[1]);
    await app.Appear();

    await app.Run(app.Detail.MarkDeliveredCommand);

    Assert.Equal("Delivered", app.Detail.StatusLabel);
    Assert.Equal("Delivered 2026-02-10 12:00 UTC", app.Detail.DeliveredText);
    Assert.Equal("Delivered", app.List.Items[1].Status);
}

The tests do not fake the API. Each one starts the real shipment service on a free port, and the app talks to it over HTTP. There are 11 scenarios, covering the list, the filter, both offline cases, the detail actions, a conflict with a change made elsewhere, client-side validation, a decimal comma on a German device, and creating a shipment.

What the scenarios found in the old app

  • The list loaded several times per appearance. A trace showed two loads before the page had appeared and more when it did. The status picker wrote its selection back into the view model, whose setter reloaded without checking whether the value had changed. The pull-to-refresh control ran the load command again every time the busy flag became true. On a device this is redundant network traffic. In the first test run, without a UI thread, the overlapping loads duplicated the list items and then hung the run.
  • An alert shown from a view model never completed. Xamarin.Forms queues an alert until the page is attached to a platform renderer, so the test waited forever until the harness marked the page as attached.

Neither is caused by the migration. Both are why the old view models were hard to test, and both disappear in the new version.

Step 2: view models that reference no UI framework

The view models move into a plain .NET library. Everything they took from global objects becomes a constructor parameter behind a small interface: navigation, dialogs, connectivity, settings, messaging.

public partial class ShipmentListViewModel : ObservableObject, IRecipient<ShipmentChangedMessage>
{
    public ShipmentListViewModel(IShipmentApi api, INetworkStatus connectivity, ISettings settings, INavigator navigator, IMessenger messenger)
    {
        (_api, _connectivity, _settings, _navigator) = (api, connectivity, settings, navigator);
        messenger.Register(this);   // a weak, typed subscription instead of a string key
    }

    [RelayCommand]
    private Task OpenAsync(Shipment shipment) => _navigator.ShowDetailAsync(shipment.TrackingNumber);
}

The member names stay the same on purpose. That is what lets one source file of scenarios compile against both versions. All 11 scenarios pass against the Xamarin.Forms app and against the new view models.

Step 3: the .NET MAUI app around them

With the logic out of the way, the app project is mostly a mechanical translation:

Xamarin.Forms.NET MAUI
DependencyService.Register, [assembly: Dependency]service registrations in MauiProgram
MainPage = new NavigationPage(…)CreateWindow returning a Shell with routes
a renderer class per platformone handler mapping
connectivity and settings implemented per platformone implementation each on Connectivity and Preferences
Device.BeginInvokeOnMainThread around collection updatesremoved, the code after await already runs on the UI thread
Color.FromHex, StackLayout, FontSize=”Large”Color.FromArgb, VerticalStackLayout, a numeric font size

The custom renderers are the clearest example. Two classes in two projects become one mapping:

// Replaces the two custom renderers (one per platform project) for BorderlessEntry.
EntryHandler.Mapper.AppendToMapping("Borderless", (handler, view) =>
{
    if (view is not BorderlessEntry) return;
#if ANDROID
    handler.PlatformView.Background = null;
#elif IOS || MACCATALYST
    handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
#endif
});

Two details that decide whether users notice the update

The application identifier is unchanged, so the stores treat the new build as an update and not as a new app. And the new app keeps reading what the old one stored on the device. The Xamarin app kept the device identity and the offline cache in an Android preferences file with its own name. .NET MAUI uses a different file by default, so the old name is passed explicitly:

public class PreferencesSettings : ISettings
{
#if ANDROID
    // The Xamarin app used a SharedPreferences file with this name. Without it, Preferences would use its own file.
    private const string SharedName = "parceltracker";
#else
    private const string? SharedName = null;
#endif

    public string? Get(string key) => Preferences.Default.Get<string?>(key, null, SharedName);
}

Without that line, every user would lose the offline cache and the device identity on update. This is the kind of thing the mobile app modernization guide means by migrating what is stored on the device.

What is verified, and what is not

CheckResult
11 scenarios against the Xamarin.Forms pages and view models11 / 11
11 scenarios against the .NET MAUI view models11 / 11
.NET MAUI app builds for Androidbuilds, produces a signed APK
.NET MAUI app builds for Windowsbuilds
.NET MAUI app builds for iOSnot built: the build agents had an older Xcode than the iOS SDK requires
  • The Xamarin platform projects were not compiled. The Xamarin toolchain is not available on current build agents. The Android and iOS sources of the old app are reference code. The shared project, which holds all pages and view models, is compiled and tested.
  • Nothing was run on a device. The scenarios exercise view models, and for the old version the real pages on a mocked platform. Layout, the borderless entry and the reading of old settings are implemented as described but were not observed on a phone.

One thing went wrong on the new side: version 8.4.0 of the MVVM toolkit generated nothing for partial properties under the .NET 10 SDK, and the build failed. Version 8.4.2 works.

Run it yourself

Both test suites need only the .NET 10 SDK and run on any operating system:

git clone https://github.com/chudovo/application-modernization
cd application-modernization/cases/03-xamarin-forms-to-maui
dotnet test before/tests/ParcelTracker.ScenarioTests
dotnet test after/tests/ParcelTracker.ScenarioTests

Building the app itself needs the .NET MAUI workload. Details are in the README of the case.

What happens when this .NET MAUI app is rewritten in another framework is the subject of the next case: .NET MAUI to React Native: A Worked Rewrite Checked by the Same Scenarios.

When this path fits

Moving from Xamarin.Forms to .NET MAUI is an upgrade in place: the language stays and most logic carries over. It is the cheapest way back onto a supported framework, and it fits when the team works in .NET. When to choose a different framework or native development instead is covered in Mobile App Modernization: Choosing a Path for Xamarin, Native and Cross-Platform Apps.

If you need a team for a migration like this, see our comparison of top .NET modernization companies.

Eugene started his career at Chudovo in 2015. The expert is responsible for advisory services that include but are not limited to close communication with the clients, analyzing their needs, designing tailored software strategies, etc. Throughout the practice at Chudovo, an IT consultant took part in over 17 projects, covering a wide range of client services and solving customer pains from the business perspective. With Eugene’s involvement, the customers were able to build an efficient strategy for business growth as well as to set up a long-term technology roadmap. Eugene takes an active part in software development projects in the role of IT consultant and composes proposals for the customers.