DEV Community

Cover image for From Xamarin to .NET MAUI: An Enterprise Migration Playbook
NuvyntraLabs
NuvyntraLabs

Posted on Originally published at Medium

From Xamarin to .NET MAUI: An Enterprise Migration Playbook

#xamarin #maui #migration #nuvyntralabs

Migrating a small Xamarin.Forms application to .NET MAUI can be relatively straightforward.

Migrating a large enterprise mobile application is a completely different problem.

Enterprise applications often contain years of accumulated business logic, hundreds of screens, custom renderers, native Android and iOS integrations, third-party SDKs, background services, push notifications, offline synchronization, authentication systems, CI/CD pipelines, and production dependencies.

Simply converting the .csproj file and fixing compilation errors is not an enterprise migration strategy.

A successful migration should be treated as a controlled transformation program.

The objective isn't to convert Xamarin code to MAUI. The objective is to move a production application to a modern platform without disrupting the business.

This guide presents a practical approach for migrating large Xamarin/Xamarin.Forms enterprise applications to .NET MAUI.

1. Why Enterprise Migration Is Different

A typical Xamarin application may look like:

Mobile Application
 ├── Pages
 ├── ViewModels
 ├── Services
 ├── API
 └── Local Storage
Enter fullscreen mode Exit fullscreen mode

A large enterprise application can look more like:

Enterprise Mobile Platform
│
├── Presentation
│   ├── 100+ Pages
│   ├── Custom Controls
│   ├── Renderers
│   └── Behaviors
│
├── Business Layer
│   ├── Domain Logic
│   ├── Workflows
│   └── Validation
│
├── Infrastructure
│   ├── REST APIs
│   ├── Database
│   ├── Caching
│   └── Synchronization
│
├── Platform Services
│   ├── Push Notifications
│   ├── Location
│   ├── Bluetooth
│   ├── Background Services
│   └── File System
│
├── Native Integrations
│   ├── Android SDKs
│   ├── iOS SDKs
│   └── Third-party SDKs
│
└── DevOps
    ├── CI/CD
    ├── Signing
    ├── Distribution
    └── Monitoring
Enter fullscreen mode Exit fullscreen mode

Every one of these areas can introduce migration risk.

Therefore, the migration needs to be planned before the first code change.

2. The Migration Mindset

The traditional approach is:

Xamarin
   ↓
Upgrade Project
   ↓
Fix Compilation Errors
   ↓
Fix Runtime Errors
   ↓
Release
Enter fullscreen mode Exit fullscreen mode

For an enterprise application, a better approach is:

ASSESS
   ↓
BASELINE
   ↓
DECOUPLE
   ↓
BUILD MAUI FOUNDATION
   ↓
PILOT
   ↓
MIGRATE IN WAVES
   ↓
VALIDATE
   ↓
CANARY RELEASE
   ↓
FULL ROLLOUT
   ↓
RETIRE XAMARIN
Enter fullscreen mode Exit fullscreen mode

This creates checkpoints throughout the migration rather than discovering major problems near the end.

3. Phase 1 — Assess the Existing Application

Before migrating anything, create a Migration Inventory.

Document:

  • Xamarin.Forms version
  • .NET/Xamarin versions
  • Target Android/iOS versions
  • NuGet dependencies
  • Custom renderers
  • Effects
  • Behaviors
  • Custom controls
  • Native Android code
  • Native iOS code
  • Background services
  • Push notification implementation
  • Authentication
  • Local database
  • Offline synchronization
  • File handling
  • Deep links
  • Analytics
  • Crash reporting
  • CI/CD
  • Signing and provisioning
  • Automated tests

The goal is to answer:

What parts of this application are actually dependent on Xamarin?

4. Build a Dependency Risk Matrix

Not every dependency deserves the same migration strategy.

Classify dependencies into three categories.

Green

Already compatible with the target .NET/MAUI environment.

.NET libraries
Modern NuGet packages
Pure business logic
Enter fullscreen mode Exit fullscreen mode

Yellow

Requires configuration or code changes.

Older NuGet packages
Custom controls
Navigation libraries
Storage libraries
Enter fullscreen mode Exit fullscreen mode

Red

Requires replacement or significant redesign.

Xamarin-only packages
Unsupported renderers
Old native bindings
Unmaintained SDKs
Enter fullscreen mode Exit fullscreen mode

This gives the team a migration backlog before implementation begins.

5. Phase 2 — Establish a Production Baseline

One of the most overlooked parts of migration is establishing measurable baseline data.

Before migration, measure:

Metric Xamarin Baseline MAUI Target
Cold startup
Warm startup
Memory usage
Application size
Login time
Screen load time
API failure rate
Crash rate
ANR rate
Database performance

Also document critical business workflows.

For example:

Login
Search Customer
Open Customer
Create Order
Submit Order
Offline
Synchronize
Receive Notification
Logout
Enter fullscreen mode Exit fullscreen mode

These become migration acceptance criteria.

Without a baseline, "migration completed" can mean nothing more than "the application builds."

6. Phase 3 — Stabilize Xamarin Before Migration

If the existing application is on an older Xamarin.Forms version, stabilize it before starting the MAUI migration.

A useful sequence is:

Legacy Xamarin.Forms
        ↓
Latest stable Xamarin.Forms version
        ↓
Update dependencies
        ↓
Fix existing issues
        ↓
Production baseline
        ↓
MAUI migration
Enter fullscreen mode Exit fullscreen mode

Do not combine an unstable legacy application with a platform migration.

Otherwise, you won't know whether a problem was introduced by the migration or already existed.

7. Don't Automatically Convert Everything

A common mistake is assuming that every piece of existing code should survive.

Ask three questions:

Does this code contain business logic?

Keep and modernize it.

Does this code exist only because Xamarin required it?

Consider removing it.

Is this code solving a problem that MAUI already solves?

Delete it.

Migration is an opportunity to reduce technical debt, but not an excuse for a complete rewrite.

8. Decouple the Business Layer

Before migrating large amounts of UI, separate the business logic from the Xamarin-specific code.

A target architecture could look like:

Presentation
      ↓
ViewModels
      ↓
Application Services
      ↓
Domain
      ↓
Infrastructure
      ↓
Platform
Enter fullscreen mode Exit fullscreen mode

For example:

MyCompany.Mobile
MyCompany.Mobile.Core
MyCompany.Mobile.Domain
MyCompany.Mobile.Application
MyCompany.Mobile.Infrastructure
Enter fullscreen mode Exit fullscreen mode

The objective is simple:

The less Xamarin-dependent your business layer is, the easier the migration becomes.

9. PCL Migration: Don't Create Unnecessary Intermediate Work

Many older applications use Portable Class Libraries.

A common migration path is:

PCL
 ↓
.NET Standard
 ↓
.NET
Enter fullscreen mode Exit fullscreen mode

This can be useful, but it should not automatically become a mandatory intermediate step.

Instead, inspect what is actually inside the PCL.

If it contains:

Models
Business Rules
Validation
API Clients
Utilities
Enter fullscreen mode Exit fullscreen mode

move these into modern reusable libraries.

If it contains:

Xamarin.Forms
Xamarin.Essentials
Platform-specific APIs
Enter fullscreen mode Exit fullscreen mode

separate those dependencies first.

The goal is not:

"Convert the PCL."

The goal is:

"Extract reusable application logic from the PCL."

10. Build the MAUI Foundation First

Before migrating hundreds of screens, establish the new MAUI foundation.

MyCompany.Mobile
│
├── Configuration
├── DependencyInjection
├── Navigation
├── Resources
│
├── Core
├── Domain
├── Application
├── Infrastructure
│
└── Platforms
    ├── Android
    ├── iOS
    ├── Windows
    └── MacCatalyst
Enter fullscreen mode Exit fullscreen mode

Set up:

  • Dependency Injection
  • Configuration
  • Logging
  • Navigation
  • API clients
  • Authentication
  • Storage
  • Telemetry
  • Error handling
  • Environment management

This creates the platform on which the migrated features can run.

11. Migrate One Vertical Slice

This is one of the most important changes to the traditional migration approach.

Do not migrate:

Page 1
Page 2
Page 3
...
Page 200
Enter fullscreen mode Exit fullscreen mode

Instead, migrate a complete business capability.

For example:

Login
   ↓
Dashboard
   ↓
Customer Search
   ↓
Customer Details
   ↓
Create Order
   ↓
Submit Order
   ↓
Offline Sync
Enter fullscreen mode Exit fullscreen mode

This single workflow exercises:

  • UI
  • ViewModels
  • Navigation
  • Dependency Injection
  • API
  • Authentication
  • Storage
  • Offline support
  • Platform services
  • Telemetry
  • Error handling

If the vertical slice works, your migration architecture has been validated.

12. Renderers → Handlers

One of the major Xamarin.Forms migration areas is the transition from renderers to MAUI handlers.

But don't blindly convert every renderer.

Classify each renderer:

Custom Renderer
      │
      ├── Styling
      │      ↓
      │    Styles
      │
      ├── Behavior
      │      ↓
      │    Behavior
      │
      ├── Property mapping
      │      ↓
      │    Handler Mapper
      │
      └── Native control
             ↓
         Custom Handler
Enter fullscreen mode Exit fullscreen mode

You may discover that some old renderers are no longer necessary.

13. Create Platform Abstractions

Avoid spreading platform-specific code throughout ViewModels and business logic.

Instead of:

#if ANDROID
...
#endif
Enter fullscreen mode Exit fullscreen mode

everywhere, create interfaces.

For example:

public interface IPushNotificationService
{
    Task InitializeAsync();
    Task<string?> GetTokenAsync();
}
Enter fullscreen mode Exit fullscreen mode

Then implement:

IPushNotificationService
        │
        ├── Android
        └── iOS
Enter fullscreen mode Exit fullscreen mode

The same pattern can be applied to:

IBiometricsService
ILocationService
IFileService
IAudioService
IDeviceService
IBackgroundService
Enter fullscreen mode Exit fullscreen mode

This keeps platform-specific code isolated.

14. Treat Native Functionality as a Separate Migration Track

Native functionality deserves its own checklist.

Android 

MainActivity
Services
Broadcast Receivers
Firebase Messaging
Permissions
Intents
Background Processing
Enter fullscreen mode Exit fullscreen mode

iOS 

AppDelegate
Push Notifications
Background Tasks
Extensions
Permissions
Native SDKs
Enter fullscreen mode Exit fullscreen mode

Don't consider the migration complete until these areas have been individually validated.

15. Firebase and Push Notifications

Push notification migration can be more complicated than expected.

Validate:

App running
App backgrounded
App terminated
App restored
Token refresh
Notification tap
Deep link
Data payload
Notification payload
Enter fullscreen mode Exit fullscreen mode

Test both:

Android
iOS
Enter fullscreen mode Exit fullscreen mode

And test different OS versions and device manufacturers.

Push functionality should be considered a production-critical capability, not just another NuGet package migration.

16. Authentication Must Be Tested End-to-End

Enterprise applications frequently use:

  • OAuth
  • OpenID Connect
  • Microsoft Entra ID
  • SSO
  • biometric authentication
  • refresh tokens
  • secure storage

Validate:

Login
 ↓
Token
 ↓
API
 ↓
Token Refresh
 ↓
Logout
 ↓
Re-login
Enter fullscreen mode Exit fullscreen mode

Also test:

  • expired tokens
  • revoked sessions
  • offline behavior
  • device restart
  • application restart

17. Keep Xamarin and MAUI Side-by-Side

For a very large application, a side-by-side migration can significantly reduce risk.

                 Shared Core
                     │
          ┌──────────┴──────────┐
          ↓                     ↓
       Xamarin                MAUI
          │                     │
      Legacy UI             New UI
Enter fullscreen mode Exit fullscreen mode

Migrate functionality progressively.

Eventually:

Xamarin
   ↓
Remaining modules
   ↓
Zero modules
   ↓
Retire Xamarin
Enter fullscreen mode Exit fullscreen mode

This approach allows the existing application to continue receiving releases while migration continues.

18. Use Feature Flags

Feature flags allow old and new implementations to coexist.

CustomerDetails.Maui
        │
        ├── false → Xamarin
        │
        └── true  → MAUI
Enter fullscreen mode Exit fullscreen mode

A feature can then be enabled for:

Internal testers
      ↓
Pilot users
      ↓
Small production group
      ↓
Larger production group
      ↓
Everyone
Enter fullscreen mode Exit fullscreen mode

If a problem occurs, disable the MAUI implementation without necessarily rolling back the entire application.

19. CI/CD Should Be Migrated Early

Do not wait until the application is fully converted.

Build the pipeline early:

Pull Request
      ↓
Build
      ↓
Unit Tests
      ↓
Static Analysis
      ↓
Android Build
      ↓
iOS Build
      ↓
Integration Tests
      ↓
Artifact
Enter fullscreen mode Exit fullscreen mode

Then:

Development
     ↓
QA
     ↓
UAT
     ↓
Internal
     ↓
Canary
     ↓
Production
Enter fullscreen mode Exit fullscreen mode

Validate early:

  • Android signing
  • iOS signing
  • provisioning
  • certificates
  • app identifiers
  • push configuration
  • environment configuration
  • crash reporting
  • symbol upload

A migration that works only on a developer's machine is not complete.

20. Automated Testing Is a Migration Requirement

Create three levels of validation.

Unit tests 

Business rules
Validation
Domain logic
Enter fullscreen mode Exit fullscreen mode

Integration tests 

API
Authentication
Database
Synchronization
Enter fullscreen mode Exit fullscreen mode

Device tests 

Android
iOS
Enter fullscreen mode Exit fullscreen mode

Critical workflows should be automated before migration begins.

Otherwise, the team will spend enormous amounts of time manually comparing old and new applications.

21. Performance Testing

Don't assume that moving to MAUI automatically improves performance.

Compare the old and new applications.

Measure:

Startup
Memory
Navigation
Scrolling
API operations
Database operations
Synchronization
Battery usage
Application size
Enter fullscreen mode Exit fullscreen mode

Test on:

  • low-end Android devices
  • popular Android manufacturers
  • supported iPhones
  • slow networks
  • offline mode
  • application restart
  • background/foreground transitions

The goal is measurable equivalence or improvement, not simply successful compilation.

22. Observability During Migration

Add migration-specific telemetry.

For example:

MigrationFeature = CustomerDetails
MigrationVersion = 5.2
Platform = Android
Implementation = MAUI
Enter fullscreen mode Exit fullscreen mode

Track:

Crash rate
API failures
Navigation failures
Startup time
Feature failures
User workflow completion
Enter fullscreen mode Exit fullscreen mode

Now you can compare:

Xamarin production
       VS
MAUI production
Enter fullscreen mode Exit fullscreen mode

using actual data.

23. Don't Combine Migration With a Major Rewrite

This is probably the most important practical recommendation.

Avoid:

Xamarin → MAUI
       +
New UI
       +
New architecture
       +
New API
       +
New database
       +
New authentication
Enter fullscreen mode Exit fullscreen mode

Instead:

Release 1 — Migration 

Xamarin
   ↓
MAUI
Enter fullscreen mode Exit fullscreen mode

Focus on functional equivalence.

Release 2 — Stabilization 

MAUI
 ↓
Performance
 ↓
Reliability
 ↓
Operational improvements
Enter fullscreen mode Exit fullscreen mode

Release 3 — Modernization 

MAUI
 ↓
New UI
 ↓
Architecture improvements
 ↓
New features
Enter fullscreen mode Exit fullscreen mode

This makes failures easier to isolate.

24. Track Migration Debt

Not everything needs to be modernized immediately.

Create migration tasks such as:

MAUI-MIG-001
Replace legacy renderer

MAUI-MIG-002
Remove Xamarin compatibility dependency

MAUI-MIG-003
Modernize navigation

MAUI-MIG-004
Replace legacy native binding

MAUI-MIG-005
Remove platform-specific conditional logic
Enter fullscreen mode Exit fullscreen mode

This prevents temporary migration compromises from becoming permanent architecture.

25. Enterprise Migration Scorecard

Track every module.

Module Core UI Native Tests Performance Status
Login ✅ ✅ ✅ ✅ ✅ Complete
Dashboard ✅ 🟡 ✅ 🟡 🟢 In Progress
Orders ✅ 🟢 🔴 🟡 🟡 Blocked
Reports ✅ 🟢 🟢 🟢 🟢 Complete

This creates a common language between developers, QA, architects, DevOps and management.

26. Recommended Migration Roadmap

A practical enterprise migration can be organized into these phases:

Phase 0
Assessment
       ↓
Phase 1
Baseline & Stabilization
       ↓
Phase 2
Architecture Decoupling
       ↓
Phase 3
MAUI Foundation
       ↓
Phase 4
Pilot Vertical Slice
       ↓
Phase 5
Platform & Native Migration
       ↓
Phase 6
Feature Migration Waves
       ↓
Phase 7
Regression & Performance
       ↓
Phase 8
Canary Production
       ↓
Phase 9
Full Production Rollout
       ↓
Phase 10
Xamarin Retirement
       ↓
Phase 11
Application Modernization
Enter fullscreen mode Exit fullscreen mode

27. The Golden Rules

If I had to reduce the entire migration strategy to ten rules:

1. Don't start with the .csproj

Start with an assessment.

2. Establish a baseline

Measure the existing production application.

3. Don't migrate everything at once

Use incremental migration.

4. Decouple business logic

Reduce platform dependency.

5. Migrate vertical slices

Move complete business workflows.

6. Isolate native code

Keep Android/iOS implementation behind abstractions.

7. Don't blindly convert renderers

Determine whether they are still necessary.

8. Use feature flags

Keep rollback paths available.

9. Automate validation

Build tests before the migration becomes large.

10. Separate migration from modernization

First move to MAUI. Then improve the application.

Conclusion

A Xamarin-to-.NET MAUI migration for a large enterprise application should not be considered a simple framework upgrade.

It is an application transformation project.

The most effective strategy is to create a stable baseline, understand the application's dependencies, separate business logic from platform-specific code, establish the MAUI foundation, and then migrate complete business capabilities incrementally.

The migration should look like:

        ASSESS
           ↓
        BASELINE
           ↓
        DECOUPLE
           ↓
      MAUI FOUNDATION
           ↓
       PILOT SLICE
           ↓
    FEATURE MIGRATION
           ↓
      VALIDATE
           ↓
     CANARY RELEASE
           ↓
    FULL PRODUCTION
           ↓
    RETIRE XAMARIN
           ↓
      MODERNIZE
Enter fullscreen mode Exit fullscreen mode

The most important mindset shift is this:

Don't ask, "How do we convert our Xamarin application to .NET MAUI?"

Ask:

"How do we move our enterprise application to .NET MAUI while keeping the business running?"

That question leads to a very different—and much safer—migration strategy.

By Niladri

Top comments (0)