From maui-skills
Guides Xamarin.Forms to .NET MAUI migration including project setup, namespace renames, layout fixes, renderer-to-handler migration, effects-to-behaviors redesign, NuGet updates, data migration, and troubleshooting.
How this skill is triggered — by the user, by Claude, or both
Slash command
/maui-skills:xamarin-forms-migrationThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
For project templates, namespace tables, API deprecation tables, and reference code, see `references/forms-migration-api.md`.
For project templates, namespace tables, API deprecation tables, and reference code, see references/forms-migration-api.md.
⚠️ Do not use the .NET Upgrade Assistant. Apply namespace renames, project file updates, and package replacements directly. Build after each batch of changes and use compiler errors to guide the next round of fixes.
Platforms/<platform>/references/forms-migration-api.md)Microsoft.Maui.Controls.Compatibility packagebin//obj//Resource.designer.cs, build, test iterativelyStrategy: Create a new project and copy code into it — don't edit the existing project file in place.
MAUI zeroes out spacing that Xamarin.Forms set to 6. Your layouts will break silently:
<!-- ❌ Looks fine in Xamarin.Forms, cramped in MAUI -->
<Grid>...</Grid>
<StackLayout>...</StackLayout>
<!-- ✅ Add explicit values or restore via implicit styles in App.xaml -->
<Style TargetType="Grid">
<Setter Property="ColumnSpacing" Value="6"/>
<Setter Property="RowSpacing" Value="6"/>
</Style>
Field advice: Specify all layout values explicitly — don't rely on platform defaults.
*AndExpand Is Obsolete — No Silent Warning<!-- ❌ Silently ignored in MAUI — image won't expand -->
<StackLayout>
<Label Text="Hello world!"/>
<Image VerticalOptions="FillAndExpand" Source="dotnetbot.png"/>
</StackLayout>
<!-- ✅ Convert to Grid with star sizing -->
<Grid RowDefinitions="Auto, *">
<Label Text="Hello world!"/>
<Image Grid.Row="1" Source="dotnetbot.png"/>
</Grid>
Field advice: Flatten layout trees. Replace nested hierarchies with single Grid layouts.
ScrollView inside StackLayout expands to full content height (no scroll). Place ScrollView in a Grid with a constrained row instead.
| Issue | Fix |
|---|---|
| Grid columns/rows not declared → layout broken | Always add explicit ColumnDefinitions/RowDefinitions |
Frame measures differently | Migrate to Border with StrokeShape |
BoxView invisible (default 0×0 in MAUI) | Set explicit WidthRequest/HeightRequest |
RelativeLayout | Replace with Grid (compatibility namespace only) |
⚠️ Migrate all renderers to handlers. Do NOT use shimmed renderers — they create parent wrapper views that hurt performance.
Preferred: Customize existing handlers with mapper methods:
// ✅ Extend existing handler — no new class needed
Microsoft.Maui.Handlers.EntryHandler.Mapper.AppendToMapping("NoBorder", (handler, view) =>
{
#if ANDROID
handler.PlatformView.Background = null;
#elif IOS || MACCATALYST
handler.PlatformView.BorderStyle = UIKit.UITextBorderStyle.None;
#endif
});
For completely new native views, create a full handler (see maui-custom-handlers skill).
⚠️ Effects are now Behaviors — this requires redesign, not just renaming.
For new development, prefer behaviors or handler mapper customizations over effects.
Microsoft.Maui.Controls.Compatibility causes cascading incompatibilities. Remove it and rebuild layouts natively.
Migration is the perfect time to skip deprecated APIs entirely. Don't migrate Xamarin.Forms code to a MAUI API that's already on its way out. See the full deprecated API table in references/forms-migration-api.md and run the maui-current-apis skill.
| Issue | Fix |
|---|---|
Xamarin.* namespace doesn't exist | Update to Microsoft.Maui.* equivalent |
| CollectionView doesn't scroll | Place in Grid (not StackLayout) to constrain size |
| Pop-up under page on iOS | Use DisplayAlert from the ContentPage |
| Missing padding/margin/spacing | Add explicit values or implicit styles |
| Custom renderer broken | Migrate to handler |
| SkiaSharp broken | Update to SkiaSharp.Views.Maui package |
| Can't access App.Properties data | Migrate to Preferences |
http://schemas.microsoft.com/dotnet/2021/mauiXamarin.Forms.* → Microsoft.Maui.* namespacesXamarin.Essentials → split MAUI namespacesColumnDefinitions/RowDefinitions*AndExpand with Grid layoutsMicrosoft.Maui.Controls.Compatibility packagebin/, obj/, and Resource.designer.csnpx claudepluginhub davidortinau/maui-skills --plugin maui-skillsGuides migration of Xamarin.Android native apps to .NET for Android, covering SDK-style projects, MSBuild properties, AndroidManifest.xml updates, NuGet dependencies, binding libraries, and gotchas.
Building .NET MAUI apps. Project structure, XAML/MVVM, platform services, current caveats.
Migrate WPF apps to WinUI 3: namespace replacement, control mapping, threading, imaging, MVVM conversion. Use for converting WPF code or fixing migration build errors.