Xamarin Forms Migration

Xamarin.Forms → .NET MAUI Migration

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.

Migration Workflow

1. Create new .NET MAUI project (single-project — multi-project causes AOT/build errors) 2. Copy cross-platform code + platform code into Platforms/<platform>/ 3. Update namespaces (XAML + C# + Essentials — see references/forms-migration-api.md) 4. Fix layout behavior changes (see below) 5. Migrate renderers → handlers (not shimmed renderers) 6. Migrate effects → behaviors 7. Remove Microsoft.Maui.Controls.Compatibility package 8. Update NuGet dependencies 9. Migrate app data stores 10. Delete bin//obj//Resource.designer.cs, build, test iteratively 11. Verify against .NET 10 deprecated API list

Strategy: Create a new project and copy code into it — don't edit the existing project file in place.

Critical Layout Pitfalls

⚠️ Default Spacing Changed to Zero

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 in StackLayout Doesn't Scroll

ScrollView inside StackLayout expands to full content height (no scroll). Place ScrollView in a Grid with a constrained row instead.

Other Layout Traps

Renderer → Handler Migration

⚠️ 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 → Behaviors

⚠️ Effects are now Behaviors — this requires redesign, not just renaming.

For new development, prefer behaviors or handler mapper customizations over effects.

⚠️ Do NOT Use the Compatibility Package

Microsoft.Maui.Controls.Compatibility causes cascading incompatibilities. Remove it and rebuild layouts natively.

Retired Dependencies

• App Center is retired → Replace with Sentry, Azure Monitor, or similar
• Visual Studio for Mac is retired → Use VS Code or Rider

Android-Specific Warnings

• Android migration is significantly harder than iOS — expect more UI bugs
• OEM-specific rendering differences not reproducible on emulators — test on physical devices
• Shadow rendering varies across OEMs/API levels — implement in platform-specific handler code
• Handler-level property changes don't auto-update on theme switch — manually handle theme changes

.NET 10 API Currency Warning

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.

Common Troubleshooting

Quick Checklist

1. ☐ Created new .NET MAUI project (single-project) 2. ☐ Copied cross-platform and platform code 3. ☐ Updated XAML namespace to http://schemas.microsoft.com/dotnet/2021/maui 4. ☐ Replaced Xamarin.Forms.* → Microsoft.Maui.* namespaces 5. ☐ Replaced Xamarin.Essentials → split MAUI namespaces 6. ☐ Added explicit Grid ColumnDefinitions/RowDefinitions 7. ☐ Replaced *AndExpand with Grid layouts 8. ☐ Added explicit spacing/padding values (MAUI defaults to 0) 9. ☐ Migrated renderers to handlers (not shimmed renderers) 10. ☐ Migrated effects to behaviors or MAUI effects 11. ☐ Removed Microsoft.Maui.Controls.Compatibility package 12. ☐ Updated NuGet dependencies for .NET compatibility 13. ☐ Migrated App.Properties, SecureStorage, VersionTracking data 14. ☐ Deleted bin/, obj/, and Resource.designer.cs 15. ☐ Tested on physical Android device 16. ☐ Profiled performance 17. ☐ Verified no .NET 10 deprecated APIs (run maui-current-apis skill)

Xamarin.Forms Migration API Reference

SDK-Style Project File Template

<!-- .NET MAUI single-project csproj -->
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
    <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">
      $(TargetFrameworks);net8.0-windows10.0.19041.0
    </TargetFrameworks>
    <OutputType>Exe</OutputType>
    <UseMaui>true</UseMaui>
    <SingleProject>true</SingleProject>
    <Nullable>enable</Nullable>
    <ImplicitUsings>enable</ImplicitUsings>
  </PropertyGroup>
</Project>

Replace net8.0 with net9.0 or net10.0 as appropriate for your target version.

---

XAML Namespace Changes

---

C# Namespace Changes

---

Xamarin.Essentials → .NET MAUI Namespaces

In .NET MAUI, Xamarin.Essentials functionality is built in. Remove the Xamarin.Essentials NuGet package and update using directives:

---

Default Spacing Value Changes

<!-- Implicit styles to restore Xamarin.Forms defaults (add to App.xaml) -->
<Style TargetType="Grid">
    <Setter Property="ColumnSpacing" Value="6"/>
    <Setter Property="RowSpacing" Value="6"/>
</Style>
<Style TargetType="StackLayout">
    <Setter Property="Spacing" Value="6"/>
</Style>

---

Layout Behavior Differences

Converting *AndExpand to Grid

<!-- BEFORE (Xamarin.Forms) -->
<StackLayout>
    <Label Text="Hello world!"/>
    <Image VerticalOptions="FillAndExpand" Source="dotnetbot.png"/>
</StackLayout>

<!-- AFTER (.NET MAUI) -->
<Grid RowDefinitions="Auto, *">
    <Label Text="Hello world!"/>
    <Image Grid.Row="1" Source="dotnetbot.png"/>
</Grid>

---

Renderer to Handler Migration

Mapper Methods

Customize Existing Handlers (Preferred)

// In MauiProgram.cs
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
});

Shimmed Renderers (Fallback Only)

.NET MAUI provides shims for renderers deriving from FrameRenderer, ListViewRenderer, ShellRenderer, TableViewRenderer, and VisualElementRenderer:

1. Move code to Platforms/<platform>/ folders 2. Change Xamarin.Forms.* namespaces to Microsoft.Maui.* 3. Remove [assembly: ExportRenderer(...)] attributes 4. Register with ConfigureMauiHandlers / AddHandler

---

Effects Migration

// MauiProgram.cs
builder.ConfigureEffects(effects =>
{
    effects.Add<FocusRoutingEffect, FocusPlatformEffect>();
});

Effects migration steps: 1. Remove ResolutionGroupNameAttribute and ExportEffectAttribute 2. Remove Xamarin.Forms and Xamarin.Forms.Platform.* using directives 3. Combine RoutingEffect + PlatformEffect implementations into a single file with conditional compilation 4. Register with ConfigureEffects in MauiProgram.cs

---

NuGet Dependency Compatibility

---

App Data Migration

---

MauiProgram.cs Entry Point

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiApp<App>()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });
        return builder.Build();
    }
}

---

.NET 10 Deprecated API Table