Xamarin.Forms Migration

Use this skill to move a Xamarin.Forms app to .NET MAUI without blindly copying obsolete patterns. Treat migration as an audit and phased rebuild on a fresh MAUI project unless the user explicitly needs a small tactical port.

Response Checklist

• Call out the migration audit first (DependencyService, MessagingCenter, custom renderers/effects, permissions, and platform capabilities).
• Prefer a fresh MAUI project workflow and MauiProgram.cs DI setup.
• Explicitly classify renderer replacements into mapper customization, custom handler, platform service, or slim binding.

Migration Tooling

Before migrating manually, check whether the .NET Upgrade Assistant can cover the mechanical parts of the app:

dotnet tool install -g upgrade-assistant
upgrade-assistant upgrade <your-solution>.sln

Upgrade Assistant can help with project conversion and namespace/API rewrites. Use this skill for decisions tooling cannot safely automate: renderer classification, DependencyService lifetimes, MessagingCenter replacement, platform capability parity, and validation planning.

Migration Workflow

1. Inventory the current app:
   • Xamarin.Forms version, target platforms, platform projects, NuGet packages, renderers, effects, DependencyService, MessagingCenter, and native SDKs.
   • App startup, navigation, resource dictionaries, images/fonts, and platform entitlements/permissions.
2. Create a new .NET MAUI project or solution structure that matches the target app shape. Prefer this over editing the Xamarin.Forms project in place.
3. Move shared code first: models, services, view models, converters, resources, and XAML. Keep platform code out until shared code builds.
4. Update namespaces and APIs using maui-current-apis; do not introduce new Xamarin.Forms or Xamarin.Essentials references.
5. Migrate app startup to MauiProgram.cs, CreateMauiApp, DI registration, fonts, handlers, lifecycle events, and platform services.
6. Migrate UI and navigation incrementally. Keep Shell route names, modal flows, and deep-link behavior explicit.
7. Plan custom renderer/effect replacements:
   • simple native property tweak -> handler mapper customization;
   • reusable custom control -> custom handler;
   • non-visual platform API -> platform service via DI;
   • third-party native SDK surface -> slim binding.
8. Validate each migrated slice with build, platform launch, and accessibility or performance checks for changed UI.

Common API Replacements

DependencyService to DI

1. Move the cross-platform contract to shared code:

   public interface IClipboardAuditService
   {
       Task TrackCopyAsync(string source, CancellationToken cancellationToken = default);
   }
   

2. Implement each platform in Platforms/<Platform>/ or target-specific files.
3. Register the implementation in MauiProgram.cs with AddSingleton, AddScoped, or AddTransient based on lifetime needs.
4. Inject the service into view models or services. Avoid service locator calls from pages unless the app already uses that pattern and you are containing migration risk.

MessagingCenter Replacement

Choose the smallest explicit communication pattern:

Do not migrate MessagingCenter by adding global static events everywhere. Document message names, payload types, sender/receiver lifetimes, and threading before replacing them.

Renderer to Handler Planning

Audit each renderer and classify it before writing code:

Platform Capability Parity

For each target platform, record:

• required permissions, entitlements, manifests, Info.plist keys, and app capabilities;
• Essentials API coverage and behavioral differences;
• native SDK availability and version requirements;
• background tasks, push/deep link, secure storage, file picker, and biometric differences;
• UI parity risks such as safe areas, keyboard/soft input, gestures, and desktop pointer behavior.

Cross-Skill Routing

• Use maui-current-apis for version-specific MAUI API replacements.
• Use maui-custom-handlers for handler mapper/custom handler implementation.
• Use maui-platform-invoke for non-visual platform services, partial classes, permissions, and lifecycle hooks.
• Use android-slim-bindings or ios-slim-bindings when a native SDK needs a maintainable binding surface.
• Use maui-accessibility and maui-performance for migrated UI risk areas.

Validation Checklist

• The migration plan starts from an audited Xamarin.Forms solution, not guesses.
• New code targets MAUI namespaces and current APIs.
• Platform capabilities and permissions are mapped for every retained platform.
• Renderers/effects are classified before migration.
• DependencyService and MessagingCenter replacements have explicit lifetimes.
• Each migrated slice builds and runs on at least one intended platform.