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
- 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.
- 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.
- Move shared code first: models, services, view models, converters, resources,
and XAML. Keep platform code out until shared code builds.
- Update namespaces and APIs using
maui-current-apis; do not introduce new
Xamarin.Forms or Xamarin.Essentials references.
- Migrate app startup to
MauiProgram.cs, CreateMauiApp, DI registration,
fonts, handlers, lifecycle events, and platform services.
- Migrate UI and navigation incrementally. Keep Shell route names, modal flows,
and deep-link behavior explicit.
- 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.
- Validate each migrated slice with build, platform launch, and accessibility or
performance checks for changed UI.
Common API Replacements
| Xamarin.Forms-era pattern |
MAUI direction |
using Xamarin.Forms |
using Microsoft.Maui.Controls |
using Xamarin.Essentials |
Microsoft.Maui.ApplicationModel, Microsoft.Maui.Devices, Microsoft.Maui.Storage, or the specific MAUI namespace |
Device.BeginInvokeOnMainThread |
MainThread.BeginInvokeOnMainThread or Dispatcher.Dispatch |
Device.StartTimer |
Dispatcher.StartTimer or IDispatcherTimer |
Device.RuntimePlatform |
DeviceInfo.Platform, OnPlatform, partial classes, or DI services |
Color.Red, Color.FromHex |
Colors.Red, Color.FromArgb, or resource colors |
Application.Current.MainPage = ... |
Window.Page for intentional resets, or Shell/navigation abstractions for routine navigation |
DependencyService.Get<T>() |
Constructor-injected services registered in MauiProgram.cs |
MessagingCenter |
WeakReferenceMessenger, events, observable state, or explicit domain services |
ExportRenderer / CustomRenderer |
Handler mapper customization or ViewHandler<TVirtualView,TPlatformView> |
DependencyService to DI
Move the cross-platform contract to shared code:
public interface IClipboardAuditService
{
Task TrackCopyAsync(string source, CancellationToken cancellationToken = default);
}
Implement each platform in Platforms/<Platform>/ or target-specific files.
Register the implementation in MauiProgram.cs with AddSingleton,
AddScoped, or AddTransient based on lifetime needs.
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:
| Existing use |
Replacement |
| View model updates a bound page |
Observable properties and binding |
| Domain event across features |
WeakReferenceMessenger or an app event aggregator |
| One service asks another to work |
Inject the target service and call a method |
| Navigation trigger |
Navigation service or Shell route call |
| Platform callback |
Platform service event or IObservable<T> exposed through DI |
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:
| Renderer shape |
MAUI migration |
| Changes one native property on an existing MAUI control |
Handler.Mapper.AppendToMapping scoped to a subclass or named mapping |
| Needs a cross-platform custom control with bindable properties |
Custom handler with PropertyMapper and optional CommandMapper |
| Subscribes to native events |
Handler ConnectHandler/DisconnectHandler with explicit unsubscribe cleanup |
| Calls camera, health, maps, payment, or other SDK APIs |
Platform service or slim binding; do not hide SDK workflow in a visual handler |
| Uses Xamarin.Forms effects only for styling |
Prefer styles, visual states, or a handler mapper |
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.
1---2name: xamarin-forms-migration3description: Plan Xamarin.Forms to MAUI migrations. USE FOR: audits, fresh `dotnet new maui`, namespace updates, `DependencyService` to DI, `MessagingCenter` replacement, renderer triage, `MauiProgram`, permissions, parity planning. DO NOT USE FOR: brand-new MAUI apps, native SDK bindings, backend.4---56# Xamarin.Forms Migration78Use this skill to move a Xamarin.Forms app to .NET MAUI without blindly copying9obsolete patterns. Treat migration as an audit and phased rebuild on a fresh10MAUI project unless the user explicitly needs a small tactical port.1112## Response Checklist1314- Call out the migration audit first (`DependencyService`, `MessagingCenter`,15 custom renderers/effects, permissions, and platform capabilities).16- Prefer a fresh MAUI project workflow and `MauiProgram.cs` DI setup.17- Explicitly classify renderer replacements into mapper customization, custom18 handler, platform service, or slim binding.1920## Migration Tooling2122Before migrating manually, check whether the .NET Upgrade Assistant can cover23the mechanical parts of the app:2425```bash26dotnet tool install -g upgrade-assistant27upgrade-assistant upgrade <your-solution>.sln28```2930Upgrade Assistant can help with project conversion and namespace/API rewrites.31Use this skill for decisions tooling cannot safely automate: renderer32classification, `DependencyService` lifetimes, `MessagingCenter` replacement,33platform capability parity, and validation planning.3435## Migration Workflow36371. Inventory the current app:38 - Xamarin.Forms version, target platforms, platform projects, NuGet packages,39 renderers, effects, `DependencyService`, `MessagingCenter`, and native SDKs.40 - App startup, navigation, resource dictionaries, images/fonts, and platform41 entitlements/permissions.422. Create a new .NET MAUI project or solution structure that matches the target43 app shape. Prefer this over editing the Xamarin.Forms project in place.443. Move shared code first: models, services, view models, converters, resources,45 and XAML. Keep platform code out until shared code builds.464. Update namespaces and APIs using `maui-current-apis`; do not introduce new47 `Xamarin.Forms` or `Xamarin.Essentials` references.485. Migrate app startup to `MauiProgram.cs`, `CreateMauiApp`, DI registration,49 fonts, handlers, lifecycle events, and platform services.506. Migrate UI and navigation incrementally. Keep Shell route names, modal flows,51 and deep-link behavior explicit.527. Plan custom renderer/effect replacements:53 - simple native property tweak -> handler mapper customization;54 - reusable custom control -> custom handler;55 - non-visual platform API -> platform service via DI;56 - third-party native SDK surface -> slim binding.578. Validate each migrated slice with build, platform launch, and accessibility or58 performance checks for changed UI.5960## Common API Replacements6162| Xamarin.Forms-era pattern | MAUI direction |63| --- | --- |64| `using Xamarin.Forms` | `using Microsoft.Maui.Controls` |65| `using Xamarin.Essentials` | `Microsoft.Maui.ApplicationModel`, `Microsoft.Maui.Devices`, `Microsoft.Maui.Storage`, or the specific MAUI namespace |66| `Device.BeginInvokeOnMainThread` | `MainThread.BeginInvokeOnMainThread` or `Dispatcher.Dispatch` |67| `Device.StartTimer` | `Dispatcher.StartTimer` or `IDispatcherTimer` |68| `Device.RuntimePlatform` | `DeviceInfo.Platform`, `OnPlatform`, partial classes, or DI services |69| `Color.Red`, `Color.FromHex` | `Colors.Red`, `Color.FromArgb`, or resource colors |70| `Application.Current.MainPage = ...` | `Window.Page` for intentional resets, or Shell/navigation abstractions for routine navigation |71| `DependencyService.Get<T>()` | Constructor-injected services registered in `MauiProgram.cs` |72| `MessagingCenter` | `WeakReferenceMessenger`, events, observable state, or explicit domain services |73| `ExportRenderer` / `CustomRenderer` | Handler mapper customization or `ViewHandler<TVirtualView,TPlatformView>` |7475## DependencyService to DI76771. Move the cross-platform contract to shared code:7879 ```csharp80 public interface IClipboardAuditService81 {82 Task TrackCopyAsync(string source, CancellationToken cancellationToken = default);83 }84 ```85862. Implement each platform in `Platforms/<Platform>/` or target-specific files.873. Register the implementation in `MauiProgram.cs` with `AddSingleton`,88 `AddScoped`, or `AddTransient` based on lifetime needs.894. Inject the service into view models or services. Avoid service locator calls90 from pages unless the app already uses that pattern and you are containing91 migration risk.9293## MessagingCenter Replacement9495Choose the smallest explicit communication pattern:9697| Existing use | Replacement |98| --- | --- |99| View model updates a bound page | Observable properties and binding |100| Domain event across features | `WeakReferenceMessenger` or an app event aggregator |101| One service asks another to work | Inject the target service and call a method |102| Navigation trigger | Navigation service or Shell route call |103| Platform callback | Platform service event or `IObservable<T>` exposed through DI |104105Do not migrate `MessagingCenter` by adding global static events everywhere.106Document message names, payload types, sender/receiver lifetimes, and threading107before replacing them.108109## Renderer to Handler Planning110111Audit each renderer and classify it before writing code:112113| Renderer shape | MAUI migration |114| --- | --- |115| Changes one native property on an existing MAUI control | `Handler.Mapper.AppendToMapping` scoped to a subclass or named mapping |116| Needs a cross-platform custom control with bindable properties | Custom handler with `PropertyMapper` and optional `CommandMapper` |117| Subscribes to native events | Handler `ConnectHandler`/`DisconnectHandler` with explicit unsubscribe cleanup |118| Calls camera, health, maps, payment, or other SDK APIs | Platform service or slim binding; do not hide SDK workflow in a visual handler |119| Uses Xamarin.Forms effects only for styling | Prefer styles, visual states, or a handler mapper |120121## Platform Capability Parity122123For each target platform, record:124125- required permissions, entitlements, manifests, Info.plist keys, and app126 capabilities;127- Essentials API coverage and behavioral differences;128- native SDK availability and version requirements;129- background tasks, push/deep link, secure storage, file picker, and biometric130 differences;131- UI parity risks such as safe areas, keyboard/soft input, gestures, and desktop132 pointer behavior.133134## Cross-Skill Routing135136- Use `maui-current-apis` for version-specific MAUI API replacements.137- Use `maui-custom-handlers` for handler mapper/custom handler implementation.138- Use `maui-platform-invoke` for non-visual platform services, partial classes,139 permissions, and lifecycle hooks.140- Use `android-slim-bindings` or `ios-slim-bindings` when a native SDK needs a141 maintainable binding surface.142- Use `maui-accessibility` and `maui-performance` for migrated UI risk areas.143144## Validation Checklist145146- The migration plan starts from an audited Xamarin.Forms solution, not guesses.147- New code targets MAUI namespaces and current APIs.148- Platform capabilities and permissions are mapped for every retained platform.149- Renderers/effects are classified before migration.150- `DependencyService` and `MessagingCenter` replacements have explicit lifetimes.151- Each migrated slice builds and runs on at least one intended platform.
.NET (Microsoft)