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.
npx claudepluginhub davidortinau/maui-skills --plugin maui-skillsThis skill uses the workspace's default tool permissions.
For project templates, namespace tables, API deprecation tables, and reference code, see `references/forms-migration-api.md`.
Guides 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.
Guides .NET MAUI XAML/C# data bindings: compiled x:DataType, INotifyPropertyChanged/ObservableObject, converters, modes, relative bindings, fallbacks, and MVVM practices.
Maps UWP APIs to WinUI 3 equivalents with before/after code snippets for app migration. Covers namespaces, threading, dialogs, windowing, and Copilot mistakes.
Share bugs, ideas, or general feedback.
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.cs