/xamarin-forms-migration

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