Microsoft officially ended support for Xamarin in May 2024. If you're still running a Xamarin.Forms app in production, you're not just on borrowed time — you're accumulating security debt, watching NuGet dependencies fall behind, and operating on a platform the community has already moved on from.
I've led three Xamarin-to-MAUI migrations in the past 18 months: a healthcare app with 40 screens, a retail inventory platform with custom barcode scanning, and an enterprise field-service tool. Here's the structured migration path I'd use again — and the parts that tripped us up.
Why This Migration Can't Wait
The Xamarin EOL announcement isn't just a support calendar entry. In practice it means:
- No more security patches — vulnerabilities discovered in Xamarin after May 2024 won't be fixed
- NuGet package rot — popular libraries are dropping Xamarin targets; you'll start hitting incompatibilities in coming months
- iOS/Android API gaps — new OS features require updated platform bindings that Xamarin will never receive
- Developer hiring — engineers who work with Xamarin are a shrinking pool; MAUI talent is growing
The longer you wait, the larger the delta between your Xamarin app and what MAUI supports — and the harder the migration becomes.
What Changes Between Xamarin and MAUI
MAUI is Xamarin's successor, not a rewrite. The programming model is familiar — C#, XAML, MVVM — but several structural things changed that matter for migration planning:
| Concept | Xamarin.Forms | .NET MAUI |
|---|---|---|
| Project structure | Shared + platform projects | Single multi-target project |
| UI customisation | Custom Renderers | Handlers (lighter, faster) |
| Namespace | Xamarin.Forms.* | Microsoft.Maui.* |
| DI container | Manual / 3rd party | Microsoft.Extensions.DI (built-in) |
| App bootstrap | App.xaml.cs + platform code | MauiProgram.cs (single entry point) |
| Device APIs | Xamarin.Essentials | Microsoft.Maui.Essentials (built-in) |
| Shell Navigation | Optional | First-class, recommended |
How to Audit Your App Before You Start
Never start a migration cold. Spend one day doing this audit first — it reveals the true scope and prevents nasty surprises mid-migration.
- List all Custom Renderers. Each one needs to be migrated to a Handler or replaced. This is almost always the longest part.
- Check every NuGet package for MAUI compatibility. Visit nuget.org, look for
net8.0-iosandnet8.0-androidtargets. - Inventory platform-specific code in iOS/Android head projects. Map each item to how it'll be handled in a single MAUI project.
- Count your XAML pages and views. Namespace changes affect every file — good to know this before estimating timeline.
- Review Xamarin.Essentials usage. Most APIs map 1:1 to MAUI Essentials, but a few changed signatures.
Step-by-Step Migration Guide
Step 1: Use the .NET Upgrade Assistant
Microsoft's .NET Upgrade Assistant (CLI tool) handles a significant portion of the mechanical migration automatically: project file restructuring, namespace replacements, and some NuGet package updates. Install it and run it first before touching code manually.
dotnet tool install -g upgrade-assistant
upgrade-assistant upgrade ./YourApp.sln --target-tfm-support LTS
This won't get you to 100% — but it'll handle the scaffolding so you can focus on the logic-heavy parts.
Step 2: Update Namespaces
Every file that imports Xamarin.Forms needs to be updated to Microsoft.Maui and Microsoft.Maui.Controls. The Upgrade Assistant handles most of this, but do a final project-wide search for Xamarin.Forms to catch strays.
Step 3: Consolidate the Project Structure
Xamarin uses a shared project plus separate iOS/Android head projects. MAUI uses a single multi-targeted project with a Platforms/ folder for platform-specific code. Move your platform code into the correct Platforms/iOS, Platforms/Android, and Platforms/Windows folders.
Step 4: Rewrite the App Entry Point
Xamarin uses App.xaml.cs as the bootstrap. MAUI uses MauiProgram.cs — a builder pattern that registers services, configure fonts, handlers, and app settings. Rewrite this file first; it gives you the foundation for everything else.
public static class MauiProgram
{
public static MauiApp CreateMauiApp()
{
var builder = MauiApp.CreateBuilder();
builder
.UseMauiApp<App>()
.ConfigureFonts(fonts => {
fonts.AddFont("Inter-Regular.ttf", "InterRegular");
});
builder.Services.AddSingleton<IMyService, MyService>();
return builder.Build();
}
}
The Custom Renderers Problem — and How to Solve It
This is where most migrations hit their first wall. If you have custom renderers in your Xamarin app, they don't translate directly to MAUI. You have three options:
- Migrate to a Handler — the right long-term answer. Handlers are more performant and the MAUI way. The API surface is different, but the concept is the same: you're mapping a virtual control to a native view.
- Use compatibility shims temporarily — MAUI offers a Xamarin.Forms compatibility layer (
XamlCompatibilitymode) that allows some renderers to continue working. Use this to unblock the initial migration, then replace renderers with handlers in a follow-up sprint. - Replace with a community control — for common use cases (signature pads, charts, PDF viewers), a MAUI-native community library likely already exists. Check MAUI Community Toolkit and Telerik UI for MAUI first.
On migration projects, I always tackle the custom renderers before the namespace sweeps. Knowing exactly which renderers you have — and which migration path each will take — gives you a reliable time estimate. Renderers with complex gesture handling or drawing contexts are 4–6 hours each. Simple styling renderers are 1–2 hours.
Common Migration Mistakes to Avoid
- Skipping the audit phase. Teams that dive into the Upgrade Assistant without an audit end up blocked by renderer and NuGet issues they didn't anticipate.
- Trying to migrate and refactor simultaneously. Keep the migration scope tight: get a working MAUI app first, then modernise the architecture in a subsequent sprint.
- Ignoring iOS provisioning. MAUI changes some iOS project settings; confirm your signing certificates and provisioning profiles still work on the migrated project before you call it done.
- Not testing on physical devices. Several rendering and performance issues only appear on hardware — especially on lower-end Android devices and older iPhones. Test early.
- Forgetting Android manifest and iOS info.plist permissions. These don't always migrate automatically — audit them against what your app actually needs.
How Long Does a Migration Actually Take?
Based on the three migrations I've led, here's an honest breakdown:
| App Complexity | Screens | Custom Renderers | Timeline (1 dev) |
|---|---|---|---|
| Small | 10–20 | 0–3 | 1–2 weeks |
| Medium | 20–50 | 3–10 | 3–5 weeks |
| Large / Enterprise | 50+ | 10+ | 8–14 weeks |
The biggest variable is always custom renderers and third-party library compatibility. If you've got a well-structured Xamarin app with few renderers and mainstream NuGet packages, you'll be at the low end. Complex drawing or platform-native integrations push you toward the high end.
"Migration is a technical project, not a rewrite. Treat it like one. Define scope, measure progress, and resist the urge to 'fix everything while you're in there.' The goal is a working MAUI app — improvements come after."
If your team is resource-constrained or this is your first MAUI project, bringing in a MAUI specialist for the migration often halves the timeline and eliminates the guesswork on edge cases.
Sarah has led Xamarin-to-MAUI migrations for healthcare, retail, and enterprise clients. She specialises in custom UI components, REST API integrations, and iOS/Android feature parity. She's a regular contributor to the MAUI Community Toolkit on GitHub.
