Xamarin support ended on May 1, 2024, making .NET MAUI migration non-optional. This guide walks you through 7 critical steps — from auditing your Xamarin codebase and assessing project compatibility, to choosing migration tools, handling platform-specific code, running cross-platform tests, and deploying your first MAUI build. Follow the sequence: skipping the audit or dependency check is the most common cause of failed migrations.
- Step 1: Pre-Migration Audit — inventory apps, Xamarin.Forms version, target frameworks
- Step 2: Code Assessment — identify Xamarin.Essentials, custom renderers, dependency services
- Step 3: Dependency Check — verify NuGet packages support .NET 8+ / MAUI
- Step 4: Migration Tools — .NET Upgrade Assistant, manual project conversion
- Step 5: Platform-Specific Handling — renderers → handlers, custom controls
- Step 6: Testing Strategy — device coverage, UI automation, performance baselines
- Step 7: Deployment — CI/CD pipelines, store submissions, rollback plan
01 Overview: Why Migrate from Xamarin to .NET MAUI?
Xamarin.Forms reached end of support on May 1, 2024, and Microsoft has shifted all cross-platform mobile and desktop development to .NET MAUI (Multi-platform App UI). MAUI is not a minor upgrade — it is a reimagining of the Xamarin stack built on .NET 8+, offering a single project structure, unified handler architecture, Blazor Hybrid support, and native performance improvements. If your team maintains production Xamarin apps, migration is now a compliance and maintainability issue, not a feature decision.
The migration path is well-documented by Microsoft but is not fully automated. Teams that attempt a one-click upgrade without preparation consistently hit build failures, broken NuGet references, and runtime crashes from renderer-to-handler mismatches. The 7-step process below is designed to surface risks before they become blockers.
There is no automatic path from a complex Xamarin.Forms app to MAUI. The .NET Upgrade Assistant handles scaffolding, but custom renderers, dependency services, platform-specific code, and third-party plugins require manual intervention. Budget at least 4–8 weeks for a mid-size production app, longer if you have heavy custom native code.
02 The 7 Critical Migration Steps
Each step below builds on the previous one. Do not reorder them — the audit informs the code assessment, which informs the dependency check, and so on. Skipping ahead to the Upgrade Assistant without completing steps 1–3 is the single most common reason migrations stall.
- Pre-Migration Audit — Document what you have: apps, target frameworks, Xamarin versions, platform targets.
- Code Assessment — Identify migration-sensitive patterns: custom renderers, DependencyService, Effects, platform-specific code.
- Dependency Check — Verify every NuGet package and library supports .NET 8+ and MAUI.
- Migration Tools — Run the .NET Upgrade Assistant, then manually fix what it cannot.
- Platform-Specific Handling — Convert renderers to handlers, migrate Effects, update DependencyService registrations.
- Testing — Establish device coverage, UI automation, and performance baselines before and after migration.
- Deployment — Update CI/CD, submit to stores, prepare a rollback plan.
03 Step 1: Pre-Migration Audit
Before touching any code, you need a complete inventory of your Xamarin solution. This audit becomes the migration checklist you will work through. Create a document (spreadsheet or markdown) tracking every project, its target frameworks, Xamarin packages, and known custom native code.
What to Document
| Item | Details to Capture | Why It Matters |
|---|---|---|
| Project list | Shared project, platform projects (iOS/Android), test projects | Determines scope and parallelization |
| Target frameworks | netstandard2.0, xamarin.ios10, xamarin.android, monoandroid | Must convert to net8.0-ios, net8.0-android |
| Xamarin.Forms version | 4.x, 5.x — latest stable used | API surface differences from MAUI |
| Xamarin.Essentials | Version, APIs used (geolocation, secure storage, etc.) | Becomes Microsoft.Maui.Essentials |
| Platform targets | iOS minimum, Android minimum SDK, UWP? | Determines if MAUI covers all targets |
| Custom native code | Custom renderers, dependency services, effects | Highest manual effort in migration |
Teams often forget to audit build pipelines and CI/CD. Your current YAML pipelines reference MSBuild for Xamarin, xamarin.ios workloads, and Xamarin-specific NuGet feeds. These all need updating. Capture pipeline scripts as part of the audit.
04 Step 2: Code Assessment
With the audit complete, now assess your codebase for migration-sensitive patterns. These are the areas that require manual work beyond what the Upgrade Assistant handles. Search your solution systematically for each pattern.
Every custom renderer (e.g., EntryRenderer, ButtonRenderer) must be converted to a handler using the new Microsoft.Maui.Handlers pattern. Renderers no longer exist in MAUI. Count them — each one is a manual conversion task.
DependencyService still works in MAUI but the recommended approach is dependency injection via MauiProgram.cs. Identify all [Dependency] attributes and plan the DI registration migration.
Effects have a rough equivalent in MAUI but the architecture changed. Many teams replace Effects with handler modifications or platform-specific code in the handler. Audit every RoutingEffect and platform effect.
Code in .iOS and .Android projects referencing Xamarin.Forms namespaces must update to Microsoft.Maui. Also check for Xamarin.Essentials usage — namespaces shift to Microsoft.Maui.Essentials.
Every XAML file has xmlns declarations pointing to Xamarin.Forms. These must change to Microsoft.Maui.Controls. The Upgrade Assistant handles most, but conditional XAML and custom namespaces need manual review.
Controls from Syncfusion, Telerik, DevExpress, or GrapeCity need MAUI-compatible versions. Confirm MAUI editions are licensed and available before migration. Some controls may have API differences.
05 Step 3: Dependency Check
Every NuGet package in your Xamarin solution must be verified for .NET 8+ and MAUI compatibility. Packages targeting only netstandard2.0 often work, but packages with platform-specific binaries targeting xamarin.ios or monoandroid may not resolve correctly under MAUI’s unified project.
Dependency Verification Process
| Package Category | Examples | MAUI Status | Action |
|---|---|---|---|
| Microsoft frameworks | Xamarin.Forms, Xamarin.Essentials | Replaced | Remove and replace with Microsoft.Maui.* |
| UI control libraries | Syncfusion, Telerik, DevExpress | MAUI editions available | Upgrade to MAUI-specific packages |
| Networking / serialization | Newtonsoft.Json, System.Net.Http | Compatible | Update to latest stable |
| Local databases | sqlite-net-pcl, Realm | MAUI-compatible versions exist | Update and verify platform init |
| Analytics / crash reporting | AppCenter, Firebase, Sentry | Most have MAUI SDKs | Check for MAUI packages; may need platform-specific setup |
| Legacy / abandoned packages | Plugins no longer maintained | No MAUI support | Find alternatives or fork and port |
The most common migration blocker is a single unmaintained NuGet package with no .NET 8 / MAUI equivalent. Identify these during the dependency check, not during the build phase. If a package is abandoned, you may need to find an alternative, write a wrapper, or port the source yourself. This can add days or weeks to your timeline.
06 Step 4: Migration Tools
Microsoft provides the .NET Upgrade Assistant as the primary automated migration tool. It handles project file conversion, namespace updates, and basic scaffolding — but it does not handle custom renderers, complex effects, or platform-specific logic. Run it, expect it to get you 60–80% of the way, then plan for manual work.
Running the Upgrade Assistant
- Install the tool:
dotnet tool install -g upgrade-assistant - Ensure .NET 8 SDK and MAUI workloads are installed:
dotnet workload install maui - Back up your solution and create a new git branch.
- Run:
upgrade-assistant upgrade <YourSolution.sln> - Select the MAUI target framework option when prompted.
- Let the tool process each project — it will update TFM, namespaces, and package references.
- Review the generated migration report (HTML) for items requiring manual attention.
What the Tool Handles vs. What You Handle Manually
| Automated by Upgrade Assistant | Requires Manual Work |
|---|---|
| Project file TFM conversion | Custom renderer → handler conversion |
| Xamarin.Forms → Microsoft.Maui namespace updates | Effect migration to handlers or platform code |
| Xamarin.Essentials → Microsoft.Maui.Essentials | DependencyService → DI registration in MauiProgram |
| Basic package reference updates | Resolving incompatible NuGet packages |
| XAML xmlns declaration updates | Platform-specific API replacements |
| Resource dictionary structure migration | Custom control logic and property mapping |
For some teams, creating a fresh MAUI project and porting code file-by-file is cleaner than running the Upgrade Assistant on an existing solution. This works well for smaller apps or when the existing solution has deep structural issues. You maintain full control but lose the automated namespace and package updates.
07 Step 5: Platform-Specific Handling
This is where the bulk of manual migration work happens. The architecture changed from renderers (one per control, tied to the Forms framework) to handlers (lighter, composable, decoupled from the controls layer). Understanding this shift is essential.
Renderer to Handler Conversion
In Xamarin.Forms, a custom renderer subclasses a platform-specific renderer (e.g., Xamarin.Forms.Platform.iOS.EntryRenderer) and overrides OnElementChanged. In MAUI, you create a handler that implements IViewHandler and maps properties via PropertyMapper.
| Xamarin.Forms Renderer Pattern | MAUI Handler Pattern |
|---|---|
| Subclass platform renderer | Implement IViewHandler or use base handler |
| Override OnElementChanged | Add PropertyMapper entries |
| Override OnElementPropertyChanged | PropertyMapper handles property changes |
| ExportRenderer assembly attribute | AddHandler registration in MauiProgram |
| Direct access to platform control | Access via handler.VirtualView and platform view |
Not every custom renderer needs a full handler. MAUI’s built-in handlers support modification via AppendToMapping. If your custom renderer only tweaks a single property (e.g., removes underline from Entry), you can modify the existing handler instead of creating a new one. This is far less code to maintain.
DependencyService to Dependency Injection
MAUI includes a built-in DI container via Microsoft.Extensions.DependencyInjection. While DependencyService still functions for backward compatibility, the recommended approach is registering services in MauiProgram.cs:
- Remove
[Dependency]assembly attributes from platform implementations. - Register interfaces and implementations in
MauiProgram.CreateMauiApp()viabuilder.Services. - Inject services via constructor injection in view models and pages.
- For platform-specific services, use
AddSingleton<TInterface>()with conditional registration per platform.
08 Step 6: Testing
Testing is not optional in migration. A successful build does not mean a working app. You need a testing strategy that covers unit tests, UI automation, device coverage, and performance baselines. Ideally, you captured performance baselines from the Xamarin app before migration so you can compare.
Testing Layers
| Test Layer | Scope | Tools |
|---|---|---|
| Unit tests | View models, services, business logic | xUnit, NUnit, Moq |
| UI automation | Navigation, user flows, rendering | Appium, XUITest, .NET MAUI Test Cloud |
| Platform-specific tests | Native API calls, handler behavior | Platform unit test projects |
| Performance testing | Startup time, memory, scroll performance | Profiler, Xamarin.UITest benchmarks |
| Regression testing | Feature parity with Xamarin version | Test plan from audit phase |
Test on minimum and latest iOS and Android versions. MAUI may behave differently on older OS versions due to handler changes. At minimum: iOS 14+, Android 8.0 (API 26)+, plus a tablet form factor.
Build a checklist from your audit: every feature in the Xamarin app must have a corresponding test in the MAUI app. Pay special attention to custom controls and platform-specific features — these are the highest regression risk.
Measure startup time, memory usage, and scroll frame rates on the Xamarin app before migration. Compare with the MAUI build. MAUI should be equal or better. If it is worse, investigate handler overhead or unnecessary DI registrations.
Do not rely solely on the simulator/emulator. MAUI handler changes can surface only on physical devices, especially around rendering, gestures, and lifecycle events. Always include physical device testing before deployment.
09 Step 7: Deployment
With testing complete, the final step is updating your deployment pipeline and submitting to app stores. Your CI/CD pipelines reference Xamarin-specific build steps and workloads — these must be updated for MAUI.
CI/CD Pipeline Updates
- Update build agents to .NET 8 SDK with MAUI workloads installed.
- Replace
MSBuildXamarin-specific targets withdotnet build -f net8.0-android/net8.0-ios. - Update iOS signing to use the MAUI workload and provisioning profiles.
- Update Android build to produce AAB (Android App Bundle) for Play Store.
- Update Azure DevOps / GitHub Actions YAML to reference MAUI build steps.
- Run a full pipeline test build before the first production submission.
Store Submission Considerations
| Platform | Consideration | Action |
|---|---|---|
| iOS App Store | App uses new framework (MAUI), not Xamarin.iOS | Verify TestFlight build, review privacy manifest |
| Google Play | Target API level requirements may have changed | Update targetSdk, verify AAB upload format |
| Versioning | MAUI build is a new app or in-place update? | In-place update is supported; same bundle ID |
| Rollback plan | If MAUI build has critical issues post-launch | Keep Xamarin build artifact ready for fast rollback |
Keep your last stable Xamarin build archived and ready for immediate re-submission. If the MAUI version ships with a critical regression, you can roll back by re-submitting the Xamarin build (same version number incremented). Test this rollback path before the MAUI launch — do not assume it will work under pressure.
10 Action: Your Migration Checklist
You now have the full picture. Here is a consolidated checklist to drive your migration from start to finish. Work through each item sequentially, and do not move to the next phase until the current one is complete.
- Audit — Document all projects, TFMs, Xamarin versions, custom code, CI/CD pipelines.
- Assess — Count custom renderers, DependencyService usages, Effects, platform-specific code blocks.
- Verify dependencies — Confirm every NuGet package has a .NET 8+ / MAUI-compatible version. Find alternatives for abandoned packages.
- Install tooling — .NET 8 SDK, MAUI workloads, Upgrade Assistant.
- Run Upgrade Assistant — Let it scaffold the migration. Review the report.
- Convert renderers to handlers — Manual work, one renderer at a time. Use
AppendToMappingwhere possible. - Migrate DependencyService to DI — Register in MauiProgram, update constructors.
- Update Effects — Replace with handler modifications or platform code.
- Fix XAML and namespaces — Verify all xmlns and type references.
- Build and resolve errors — Iterative; expect multiple build-fix cycles.
- Unit test — Run existing tests, fix failures, add coverage for handler logic.
- UI test — Run automation suite on simulator and physical devices.
- Performance test — Compare baselines. Investigate regressions.
- Update CI/CD — MAUI workloads, build steps, signing, distribution.
- Store submission — TestFlight + internal Play track first, then production rollout.
- Monitor post-launch — Crash reporting, performance metrics, user feedback for 2 weeks.
Xamarin to .NET MAUI migration is a project, not a task. The teams that succeed treat it like a mini-refactor: they audit first, migrate incrementally, test rigorously, and deploy with a rollback plan. The teams that fail try to one-click upgrade a production app on a Friday afternoon. Follow the 7 steps in order, and you will have a stable, future-proof MAUI app running on .NET 8+ before Xamarin support gaps become security liabilities.
Serving Clients Across the US & UK
Dev Station Technology partners with startups, enterprises, and development teams throughout the United States and the United Kingdom. Our Vietnam-based engineering teams offer significant time-zone overlap with both US Eastern/Pacific and UK GMT business hours, ensuring real-time collaboration and faster delivery cycles. We bill in USD and GBP, comply with US regulations (SOC 2, HIPAA) and UK/EU standards (GDPR, ISO 27001), and provide dedicated account management for North American and British clients.
Want an AI assistant to summarize or cite this guide?
Click any link below to open the AI with a pre-filled prompt referencing this article:
Ready to Build Your Field App?
Contact Dev Station Technology to discuss your project requirements and receive a development roadmap within 48 hours.
Get a Quote →
