Xamarin to .NET MAUI Migration: What Actually Has to Change?

If you have a Xamarin.Forms application that needs to move to .NET MAUI, the word migration can make the project sound like a complete rewrite.

Usually, it isn't.

A Xamarin-to-.NET MAUI migration typically involves modernizing the project structure and runtime, updating APIs and namespaces, replacing incompatible dependencies, adapting custom renderers and platform-specific integrations, and rebuilding your test and release processes around current .NET tooling. Much of the application's C# business logic can often remain.

Microsoft's own guidance makes the distinction explicit: Xamarin projects can run on modern .NET after an upgrade, projects do not necessarily need to be rewritten, and multi-project applications do not have to become single-project solutions.

The difficulty depends less on the number of lines of code than on where those lines of code live and what they depend on.

These aren’t purely theoretical migration concerns. Art+Logic recently worked through them while modernizing a long-standing Xamarin application to .NET MAUI, including legacy dependencies, platform-specific behavior, UX changes, and the challenge of preserving critical functionality throughout the transition.

Here is what actually changes.

1. The project structure and target frameworks change

Older Xamarin.Forms solutions commonly contain a shared .NET Standard project plus separate Xamarin.Android and Xamarin.iOS projects.

.NET MAUI introduced a simplified single-project model that can target Android, iOS, macOS, and Windows while sharing resources, application metadata, and much of the build configuration. Platform-specific code lives under Platforms when this structure is used.

But converting everything into one project is not mandatory.

Microsoft also documents migration paths for multi-project MAUI solutions. What is required is moving Xamarin projects to the modern SDK-style .NET project format.

That makes project structure an architectural decision rather than a checkbox.

For a straightforward Xamarin.Forms application, moving to the standard MAUI single-project structure can simplify future maintenance. For a large solution with significant platform separation, a more incremental structure may reduce migration risk.

As of August 2026, .NET 10 is the current active LTS release, with support scheduled through November 2028, making the supported .NET baseline itself very different from the frozen Xamarin environment.

2. Xamarin.Forms namespaces and APIs move to .NET MAUI

A lot of migration work is mechanical.

References such as Xamarin.Forms move to Microsoft.Maui and Microsoft.Maui.Controls. The default XAML namespace changes. Xamarin.Essentials functionality is incorporated into .NET MAUI rather than installed as the separate Xamarin.Essentials package used by older applications.

Microsoft's Upgrade Assistant can automate a portion of this work, including converting projects to SDK style, replacing common namespaces, removing Xamarin.Forms and Xamarin.Essentials packages, and updating certain well-known dependencies.

But a successful automated conversion is not the same thing as a completed migration.

The compiler can identify missing APIs. It cannot necessarily tell you whether an interaction now behaves differently, whether a platform-specific workaround is still necessary, or whether a generated change preserved an important business rule.

That is why migration needs functional validation, not just a green build.

3. NuGet packages and third-party SDKs need to be audited

Dependencies are often where a seemingly easy migration becomes complicated.

A Xamarin.Forms application may depend on packages for charts, scanning, mapping, authentication, local databases, media, push notifications, analytics, Bluetooth, payments, or custom UI controls.

Some will have direct .NET MAUI versions.

Some will have different APIs.

Some will have been abandoned.

Some Xamarin-targeted packages simply are not compatible with current .NET target frameworks and must be upgraded, replaced, recompiled, or removed. Microsoft specifically recommends updating dependencies before migration and replacing packages that do not have compatible modern .NET versions.

This makes a dependency inventory one of the most valuable early migration tasks.

For each package, ask:

• Is there a supported .NET MAUI version?
• Does the replacement expose the same behavior?
• Is the package still actively maintained?
• Does upgrading it create downstream code changes?
• Could the dependency now be eliminated entirely?

A ten-line integration around an abandoned native library can be more difficult to migrate than thousands of lines of ordinary C#.

4. Custom renderers may need to become handlers

This is one of the most recognizable architectural changes between Xamarin.Forms and .NET MAUI.

Xamarin.Forms commonly uses custom renderers to change the native behavior or appearance of controls. .NET MAUI introduced handlers, which provide a newer model for connecting cross-platform controls to their native implementations.

Handlers reduce the amount of visual hierarchy involved and decouple the platform control more cleanly from the framework.

Not every custom renderer has to be rewritten immediately. Microsoft provides mechanisms for reusing certain renderers during migration. However, the long-term direction is toward MAUI handlers and current controls, and Microsoft is already removing portions of the old compatibility surface as .NET continues evolving.

That means renderer inventory matters.

Simple visual customizations may translate cleanly. Complex controls wrapping native iOS or Android APIs can require meaningful engineering work.

This is one of the areas where migration estimates based purely on screen count often go wrong.

5. Platform-specific code still exists. It just has a new home

.NET MAUI is cross-platform. That does not mean every mobile application suddenly becomes platform-independent.

Real applications still need platform-specific behavior for capabilities such as notifications, permissions, background execution, deep linking, biometric authentication, file handling, Bluetooth, location, camera access, and native SDK integrations.

In a MAUI single-project application, Android- and iOS-specific code generally moves into the corresponding directories under Platforms. Microsoft recommends moving relevant code from the old Xamarin platform “head” projects into these platform-specific locations during migration.

This code deserves careful review rather than blind translation.

A workaround written for Android eight years ago may no longer be needed. An iOS API may have changed. Permission models may be different. A native library may have a modern alternative.

Migration is a good opportunity to distinguish business logic that should be preserved from historical platform code that merely needs to be understood.

6. App startup, configuration, and dependency injection change

A modern .NET MAUI application is bootstrapped through MauiProgram and MauiApp.

That creates a central place to configure the application, register services, configure handlers, initialize libraries, and use .NET's built-in dependency injection model. Microsoft describes MauiProgram.CreateMauiApp() as the cross-platform application entry point used by the individual platforms.

Applications that relied on older initialization patterns, service locators, static dependencies, or platform-specific startup classes may therefore need architectural cleanup.

This can be mostly mechanical in a well-structured application.

In a legacy application where initialization logic has accumulated over many years, it can reveal hidden coupling that deserves more deliberate refactoring.

7. Resources, manifests, and platform configuration change

Icons, splash screens, fonts, images, raw assets, permissions, entitlements, manifests, signing configuration, and application identifiers all need attention.

The MAUI single-project system simplifies many shared resources, but existing Xamarin assets still need to be moved and validated against the new build process.

Do not treat this as cosmetic work.

Mobile application configuration has direct consequences for permissions, privacy declarations, deep links, notifications, store submissions, signing, and device behavior.

A migration that renders every screen correctly but breaks push notifications is not finished.

8. The build and release pipeline needs modernization too

The application code is only part of the system.

Xamarin-era projects may rely on older Visual Studio configurations, retired Xamarin tooling, specific macOS build machines, historical Xcode versions, custom scripts, or CI/CD workflows that have not changed in years.

Those processes need to move with the application.

This matters even more now because Xamarin's final supported targets are Android API 34 and Xcode 15, while current store requirements have advanced beyond them.

A migration should therefore include the complete path from source code to a signed, tested build that can actually be submitted to Apple and Google—not simply an application that runs on a developer's laptop.

9. Testing needs to focus on behavior, not just compilation

This may be the most important part of the migration.

The fact that a migrated application compiles tells you that the compiler is satisfied. It does not tell you that the application still behaves the same way.

Test workflows that involve:

• Authentication
• Offline behavior
• Navigation
• Data synchronization
• Notifications
• Deep links
• Device permissions
• Background processing
• Purchases or licensing
• Platform-specific controls
• Accessibility
• Different screen sizes and OS versions

Pay particular attention to areas built around custom renderers, native integrations, or older workarounds.

Art+Logic saw the importance of this during a Xamarin-to-.NET MAUI modernization project for a long-standing mobile platform. Early attempts at wholesale AI conversion could produce code that compiled while removing or disabling important functionality. The successful approach broke the migration into manageable pieces, using AI for repetitive implementation work while engineers continuously validated architecture, application behavior, and quality.

That is a useful lesson whether AI is involved or not: migration correctness is behavioral, not syntactic.

What can usually stay?

A migration is not about changing code simply because it is old.

Depending on the architecture, you may be able to preserve significant portions of:

• Business rules
• Domain models
• Data-transfer objects
• API clients
• Validation logic
• Data-access abstractions
• View models
• Utility libraries
• Tests around platform-independent logic

Microsoft explicitly notes that Xamarin projects do not inherently need to be rewritten to move to modern .NET.

The real question is which parts are coupled to Xamarin itself.

The more cleanly an application separates business logic from UI and platform-specific behavior, the more of it is likely to survive migration relatively unchanged.

A practical Xamarin-to-.NET MAUI migration sequence

For most nontrivial applications, a controlled migration is safer than trying to convert the entire codebase in one operation.

Start by establishing that the existing Xamarin application builds and behaves correctly. Inventory dependencies, custom renderers, platform-specific integrations, build infrastructure, and business-critical workflows.

Then establish the target architecture and supported .NET baseline. Create the modern project structure, migrate foundational services and reusable business logic, and address dependencies before moving deeply into UI work.

From there, migrate functionality in testable slices. Replace or adapt native integrations as they are encountered. Continuously compare behavior against the existing application.

Finally, validate the complete release path on real target devices and through current store tooling.

That sequence does something important: it keeps the old application available as a reference while the new one becomes trustworthy.

Migration is less about replacing Xamarin than removing constraints

A Xamarin-to-.NET MAUI project can look straightforward from a distance: update the project, change some namespaces, fix compilation errors, ship.

Real applications are rarely that simple.

The meaningful work is usually concentrated in dependencies, custom controls, native platform integrations, accumulated workarounds, deployment infrastructure, and behavioral validation.

But that does not make migration equivalent to rebuilding the product.

The right goal is to preserve the business logic and workflows that still create value while replacing the parts of the application that tie you to an unsupported ecosystem.

That is what actually has to change.

FAQs

Is Xamarin to .NET MAUI migration a complete rewrite?

Usually not. Microsoft explicitly states that Xamarin projects do not necessarily need to be rewritten to run on modern .NET. The amount of reusable code depends heavily on the application's architecture and dependencies.

Can Xamarin.Forms code be reused in .NET MAUI?

Often, yes. Business logic, models, services, view models, and other platform-independent C# code may require relatively little change. UI code, dependencies, custom renderers, platform integrations, and project configuration typically require more attention.

Do Xamarin custom renderers work in .NET MAUI?

Some renderers can be reused through migration compatibility mechanisms, but .NET MAUI's modern customization model uses handlers. Complex renderers should be evaluated individually, particularly as older compatibility APIs are being phased out in newer .NET versions.

Do we have to convert a Xamarin app to a single MAUI project?

No. .NET MAUI supports its streamlined single-project model, but Microsoft's migration guidance explicitly says existing multi-project solutions do not have to become a single multi-targeted project.

Can the .NET Upgrade Assistant migrate Xamarin automatically?

It can automate useful mechanical work such as project conversion, namespace updates, target framework changes, and certain dependency replacements. Microsoft also notes that additional work is required after the tool runs. Functional testing and manual remediation remain necessary.

What is usually the hardest part of a Xamarin-to-MAUI migration?

The most difficult areas are often third-party dependencies, custom renderers and controls, native platform integrations, old workarounds, and release infrastructure—not ordinary cross-platform C# business logic.