Upgrading from .NET MAUI 9 to .NET MAUI 10

This guide helps you upgrade your .NET MAUI application from .NET 9 to .NET 10 by focusing on the critical breaking changes and obsolete APIs that require code updates.

Quick Start
Update Target Framework
Breaking Changes (P0 - Must Fix)
- MessagingCenter Made Internal
- ListView and TableView Deprecated
Deprecated APIs (P1 - Fix Soon)
Recommended Changes (P2)
Bulk Migration Tools
Testing Your Upgrade
Troubleshooting

Quick Start

Five-Step Upgrade Process:

Update TargetFramework to net10.0
Update CommunityToolkit.Maui to 12.3.0+ (if you use it) - REQUIRED
Fix breaking changes - MessagingCenter (P0)
Migrate ListView/TableView to CollectionView (P0 - CRITICAL)
Fix deprecated APIs - Animation methods, DisplayAlert, IsBusy, MediaPicker (P1)

⚠️ Major Breaking Changes:

CommunityToolkit.Maui must be version 12.3.0 or later

ListView and TableView are now obsolete (most significant migration effort)

Update Target Framework

Single Platform

xml

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0</TargetFramework>
  </PropertyGroup>
</Project>

Multi-Platform

xml

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFrameworks>net10.0-android;net10.0-ios;net10.0-maccatalyst;net10.0-windows10.0.19041.0</TargetFrameworks>
  </PropertyGroup>
</Project>

Optional: Linux Compatibility (GitHub Copilot, WSL, etc.)

💡 For Linux Development: If you're building on Linux (e.g., GitHub Codespaces, WSL, or using GitHub Copilot), you can make your project compile on Linux by conditionally excluding iOS/Mac Catalyst targets:

xml

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <!-- Start with Android (always supported) -->
    <TargetFrameworks>net10.0-android</TargetFrameworks>
    
    <!-- Add iOS/Mac Catalyst only when NOT on Linux -->
    <TargetFrameworks Condition="!$([MSBuild]::IsOSPlatform('linux'))">$(TargetFrameworks);net10.0-ios;net10.0-maccatalyst</TargetFrameworks>
    
    <!-- Add Windows only when on Windows -->
    <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net10.0-windows10.0.19041.0</TargetFrameworks>
  </PropertyGroup>
</Project>

Benefits:

✅ Compiles successfully on Linux (no iOS/Mac tools required)
✅ Works with GitHub Codespaces and Copilot
✅ Automatically includes correct targets based on build OS
✅ No changes needed when switching between OS environments

Reference: dotnet/maui#32186

Update Required NuGet Packages

⚠️ CRITICAL: If you use CommunityToolkit.Maui, you must update to version 12.3.0 or later. Earlier versions are not compatible with .NET 10 and will cause compilation errors.

bash

# Update CommunityToolkit.Maui (if you use it)
dotnet add package CommunityToolkit.Maui --version 12.3.0

# Update other common packages to .NET 10 compatible versions
dotnet add package Microsoft.Maui.Controls --version 10.0.0

Check all your NuGet packages:

bash

# List all packages and check for updates
dotnet list package --outdated

# Update all packages to latest compatible versions
dotnet list package --outdated | grep ">" | cut -d '>' -f 1 | xargs -I {} dotnet add package {}

Breaking Changes (P0 - Must Fix)

MessagingCenter Made Internal

Status: 🚨 BREAKING - MessagingCenter is now internal and cannot be accessed.

Error You'll See:

text

error CS0122: 'MessagingCenter' is inaccessible due to its protection level

Migration Required:

Step 1: Install CommunityToolkit.Mvvm

bash

dotnet add package CommunityToolkit.Mvvm --version 8.3.0

Step 2: Define Message Classes

csharp

// OLD: No message class needed
MessagingCenter.Send(this, "UserLoggedIn", userData);

// NEW: Create a message class
public class UserLoggedInMessage
{
    public UserData Data { get; set; }
    
    public UserLoggedInMessage(UserData data)
    {
        Data = data;
    }
}

Step 3: Update Send Calls

csharp

// ❌ OLD (Broken in .NET 10)
using Microsoft.Maui.Controls;

MessagingCenter.Send(this, "UserLoggedIn", userData);
MessagingCenter.Send<App, string>(this, "StatusChanged", "Active");

// ✅ NEW (Required)
using CommunityToolkit.Mvvm.Messaging;

WeakReferenceMessenger.Default.Send(new UserLoggedInMessage(userData));
WeakReferenceMessenger.Default.Send(new StatusChangedMessage("Active"));

csharp

// ❌ OLD (Broken in .NET 10)
MessagingCenter.Subscribe<App, UserData>(this, "UserLoggedIn", (sender, data) =>
{
    // Handle message
    CurrentUser = data;
});

// ✅ NEW (Required)
WeakReferenceMessenger.Default.Register<UserLoggedInMessage>(this, (recipient, message) =>
{
    // Handle message
    CurrentUser = message.Data;
});

⚠️ Important Behavioral Difference: Duplicate Subscriptions

WeakReferenceMessenger throws an InvalidOperationException if you try to register the same message type multiple times on the same recipient (MessagingCenter allowed this):

csharp

// ❌ This THROWS InvalidOperationException in WeakReferenceMessenger
WeakReferenceMessenger.Default.Register<UserLoggedInMessage>(this, (r, m) => Handler1(m));
WeakReferenceMessenger.Default.Register<UserLoggedInMessage>(this, (r, m) => Handler2(m)); // ❌ THROWS!

// ✅ Solution 1: Unregister before re-registering
WeakReferenceMessenger.Default.Unregister<UserLoggedInMessage>(this);
WeakReferenceMessenger.Default.Register<UserLoggedInMessage>(this, (r, m) => Handler1(m));

// ✅ Solution 2: Handle multiple actions in one registration
WeakReferenceMessenger.Default.Register<UserLoggedInMessage>(this, (r, m) => 
{
    Handler1(m);
    Handler2(m);
});

Why this matters: If your code subscribes to the same message in multiple places (e.g., in a page constructor and in OnAppearing), you'll get a runtime crash.

Step 5: Unregister When Done

csharp

// ❌ OLD
MessagingCenter.Unsubscribe<App, UserData>(this, "UserLoggedIn");

// ✅ NEW (CRITICAL - prevents memory leaks)
WeakReferenceMessenger.Default.Unregister<UserLoggedInMessage>(this);

// Or unregister all messages for this recipient
WeakReferenceMessenger.Default.UnregisterAll(this);

Complete Before/After Example

Before (.NET 9):

csharp

// Sender
public class LoginViewModel
{
    public async Task LoginAsync()
    {
        var user = await AuthService.LoginAsync(username, password);
        MessagingCenter.Send(this, "UserLoggedIn", user);
    }
}

// Receiver
public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
        
        MessagingCenter.Subscribe<LoginViewModel, User>(this, "UserLoggedIn", (sender, user) =>
        {
            WelcomeLabel.Text = $"Welcome, {user.Name}!";
        });
    }
    
    protected override void OnDisappearing()
    {
        base.OnDisappearing();
        MessagingCenter.Unsubscribe<LoginViewModel, User>(this, "UserLoggedIn");
    }
}

After (.NET 10):

csharp

// 1. Define message
public class UserLoggedInMessage
{
    public User User { get; }
    
    public UserLoggedInMessage(User user)
    {
        User = user;
    }
}

// 2. Sender
public class LoginViewModel
{
    public async Task LoginAsync()
    {
        var user = await AuthService.LoginAsync(username, password);
        WeakReferenceMessenger.Default.Send(new UserLoggedInMessage(user));
    }
}

// 3. Receiver
public partial class MainPage : ContentPage
{
    public MainPage()
    {
        InitializeComponent();
        
        WeakReferenceMessenger.Default.Register<UserLoggedInMessage>(this, (recipient, message) =>
        {
            WelcomeLabel.Text = $"Welcome, {message.User.Name}!";
        });
    }
    
    protected override void OnDisappearing()
    {
        base.OnDisappearing();
        WeakReferenceMessenger.Default.UnregisterAll(this);
    }
}

Key Differences:

✅ Type-safe message classes
✅ No magic strings
✅ Better IntelliSense support
✅ Easier to refactor
⚠️ Must remember to unregister!

ListView and TableView Deprecated

Status: 🚨 DEPRECATED (P0) - ListView, TableView, and all Cell types are now obsolete. Migrate to CollectionView.

Warning You'll See:

text

warning CS0618: 'ListView' is obsolete: 'ListView is deprecated. Please use CollectionView instead.'
warning CS0618: 'TableView' is obsolete: 'Please use CollectionView instead.'
warning CS0618: 'TextCell' is obsolete: 'The controls which use TextCell (ListView and TableView) are obsolete. Please use CollectionView instead.'

Obsolete Types:

ListView → CollectionView
TableView → CollectionView (for settings pages, consider vertical StackLayout with BindableLayout)
TextCell → Custom DataTemplate with Label(s)
ImageCell → Custom DataTemplate with Image + Label(s)
EntryCell → Custom DataTemplate with Entry
SwitchCell → Custom DataTemplate with Switch
ViewCell → DataTemplate

Impact: This is a MAJOR breaking change. ListView and TableView are among the most commonly used controls in MAUI apps.

Why This Takes Time

Converting ListView/TableView to CollectionView is not a simple find-replace:

Different event model - ItemSelected → SelectionChanged with different arguments
Different grouping - GroupDisplayBinding no longer exists
Context actions - Must convert to SwipeView
Item sizing - HasUnevenRows handled differently
Platform-specific code - iOS/Android ListView platform configurations need removal
Testing required - CollectionView virtualizes differently, may affect performance

Migration Strategy

Step 1: Inventory Your ListViews

bash

# Find all ListView/TableView usages
grep -r "ListView\|TableView" --include="*.xaml" --include="*.cs" .

Step 2: Basic ListView → CollectionView

Before (ListView):

xaml

<ListView ItemsSource="{Binding Items}"
          ItemSelected="OnItemSelected"
          HasUnevenRows="True">
    <ListView.ItemTemplate>
        <DataTemplate>
            <TextCell Text="{Binding Title}"
                     Detail="{Binding Description}" />
        </DataTemplate>
    </ListView.ItemTemplate>
</ListView>

After (CollectionView):

xaml

<CollectionView ItemsSource="{Binding Items}"
                SelectionMode="Single"
                SelectionChanged="OnSelectionChanged">
    <CollectionView.ItemTemplate>
        <DataTemplate>
            <VerticalStackLayout Padding="10">
                <Label Text="{Binding Title}" 
                       FontAttributes="Bold" />
                <Label Text="{Binding Description}"
                       FontSize="12"
                       TextColor="{StaticResource Gray600}" />
            </VerticalStackLayout>
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

⚠️ Note: CollectionView has SelectionMode="None" by default (selection disabled). You must explicitly set SelectionMode="Single" or SelectionMode="Multiple" to enable selection.

Code-behind changes:

csharp

// ❌ OLD (ListView)
void OnItemSelected(object sender, SelectedItemChangedEventArgs e)
{
    if (e.SelectedItem == null)
        return;
        
    var item = (MyItem)e.SelectedItem;
    // Handle selection
    
    // Deselect
    ((ListView)sender).SelectedItem = null;
}

// ✅ NEW (CollectionView)
void OnSelectionChanged(object sender, SelectionChangedEventArgs e)
{
    if (e.CurrentSelection.Count == 0)
        return;
        
    var item = (MyItem)e.CurrentSelection.FirstOrDefault();
    // Handle selection
    
    // Deselect (optional)
    ((CollectionView)sender).SelectedItem = null;
}

Step 3: Grouped ListView → Grouped CollectionView

Before (Grouped ListView):

xaml

<ListView ItemsSource="{Binding GroupedItems}"
          IsGroupingEnabled="True"
          GroupDisplayBinding="{Binding Key}">
    <ListView.ItemTemplate>
        <DataTemplate>
            <TextCell Text="{Binding Name}" />
        </DataTemplate>
    </ListView.ItemTemplate>
</ListView>

After (Grouped CollectionView):

xaml

<CollectionView ItemsSource="{Binding GroupedItems}"
                IsGrouped="true">
    <CollectionView.GroupHeaderTemplate>
        <DataTemplate>
            <Label Text="{Binding Key}"
                   FontAttributes="Bold"
                   BackgroundColor="{StaticResource Gray100}"
                   Padding="10,5" />
        </DataTemplate>
    </CollectionView.GroupHeaderTemplate>
    
    <CollectionView.ItemTemplate>
        <DataTemplate>
            <VerticalStackLayout Padding="20,10">
                <Label Text="{Binding Name}" />
            </VerticalStackLayout>
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

Step 4: Context Actions → SwipeView

⚠️ Platform Note: SwipeView requires touch input. On Windows desktop, it only works with touch screens, not with mouse/trackpad. Consider providing alternative UI for desktop scenarios (e.g., buttons, right-click menu).

Before (ListView with ContextActions):

xaml

<ListView.ItemTemplate>
    <DataTemplate>
        <ViewCell>
            <ViewCell.ContextActions>
                <MenuItem Text="Delete" 
                         IsDestructive="True"
                         Command="{Binding Source={RelativeSource AncestorType={x:Type local:MyPage}}, Path=DeleteCommand}"
                         CommandParameter="{Binding .}" />
            </ViewCell.ContextActions>
            
            <Label Text="{Binding Title}" Padding="10" />
        </ViewCell>
    </DataTemplate>
</ListView.ItemTemplate>

After (CollectionView with SwipeView):

xaml

<CollectionView.ItemTemplate>
    <DataTemplate>
        <SwipeView>
            <SwipeView.RightItems>
                <SwipeItems>
                    <SwipeItem Text="Delete"
                              BackgroundColor="Red"
                              Command="{Binding Source={RelativeSource AncestorType={x:Type local:MyPage}}, Path=DeleteCommand}"
                              CommandParameter="{Binding .}" />
                </SwipeItems>
            </SwipeView.RightItems>
            
            <VerticalStackLayout Padding="10">
                <Label Text="{Binding Title}" />
            </VerticalStackLayout>
        </SwipeView>
    </DataTemplate>
</CollectionView.ItemTemplate>

Step 5: TableView for Settings → Alternative Approaches

TableView is commonly used for settings pages. Here are modern alternatives:

Option 1: CollectionView with Grouped Data

xaml

<CollectionView ItemsSource="{Binding SettingGroups}"
                IsGrouped="true"
                SelectionMode="None">
    <CollectionView.GroupHeaderTemplate>
        <DataTemplate>
            <Label Text="{Binding Title}" 
                   FontAttributes="Bold"
                   Margin="10,15,10,5" />
        </DataTemplate>
    </CollectionView.GroupHeaderTemplate>
    
    <CollectionView.ItemTemplate>
        <DataTemplate>
            <Grid Padding="15,10" ColumnDefinitions="*,Auto">
                <Label Text="{Binding Title}" 
                       VerticalOptions="Center" />
                <Switch Grid.Column="1" 
                        IsToggled="{Binding IsEnabled}"
                        IsVisible="{Binding ShowSwitch}" />
            </Grid>
        </DataTemplate>
    </CollectionView.ItemTemplate>
</CollectionView>

Option 2: Vertical StackLayout (for small settings lists)

xaml

<ScrollView>
    <VerticalStackLayout BindableLayout.ItemsSource="{Binding Settings}"
                        Spacing="10"
                        Padding="15">
        <BindableLayout.ItemTemplate>
            <DataTemplate>
                <Border StrokeThickness="0"
                       BackgroundColor="{StaticResource Gray100}"
                       Padding="15,10">
                    <Grid ColumnDefinitions="*,Auto">
                        <Label Text="{Binding Title}" 
                              VerticalOptions="Center" />
                        <Switch Grid.Column="1" 
                               IsToggled="{Binding IsEnabled}" />
                    </Grid>
                </Border>
            </DataTemplate>
        </BindableLayout.ItemTemplate>
    </VerticalStackLayout>
</ScrollView>

Step 6: Remove Platform-Specific ListView Code

If you used platform-specific ListView features, remove them:

csharp

// ❌ OLD - Remove these using statements (NOW OBSOLETE IN .NET 10)
using Microsoft.Maui.Controls.PlatformConfiguration;
using Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;
using Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;

// ❌ OLD - Remove ListView platform configurations (NOW OBSOLETE IN .NET 10)
myListView.On<iOS>().SetSeparatorStyle(SeparatorStyle.FullWidth);
myListView.On<Android>().IsFastScrollEnabled();

// ❌ OLD - Remove Cell platform configurations (NOW OBSOLETE IN .NET 10)
viewCell.On<iOS>().SetDefaultBackgroundColor(Colors.White);
viewCell.On<Android>().SetIsContextActionsLegacyModeEnabled(false);

Migration: CollectionView does not have platform-specific configurations in the same way. If you need platform-specific styling:

csharp

// ✅ NEW - Use conditional compilation
#if IOS
var backgroundColor = Colors.White;
#elif ANDROID
var backgroundColor = Colors.Transparent;
#endif

var grid = new Grid
{
    BackgroundColor = backgroundColor,
    // ... rest of cell content
};

Or in XAML:

xaml

<CollectionView.ItemTemplate>
    <DataTemplate>
        <Grid>
            <Grid.BackgroundColor>
                <OnPlatform x:TypeArguments="Color">
                    <On Platform="iOS" Value="White" />
                    <On Platform="Android" Value="Transparent" />
                </OnPlatform>
            </Grid.BackgroundColor>
            <!-- Cell content -->
        </Grid>
    </DataTemplate>
</CollectionView.ItemTemplate>

Common Patterns & Pitfalls

1. Empty View

xaml

<!-- CollectionView has built-in EmptyView support -->
<CollectionView ItemsSource="{Binding Items}">
    <CollectionView.EmptyView>
        <ContentView>
            <VerticalStackLayout Padding="50" VerticalOptions="Center">
                <Label Text="No items found" 
                       HorizontalTextAlignment="Center" />
            </VerticalStackLayout>
        </ContentView>
    </CollectionView.EmptyView>
    <!-- ... -->
</CollectionView>

2. Pull to Refresh

xaml

<RefreshView IsRefreshing="{Binding IsRefreshing}"
             Command="{Binding RefreshCommand}">
    <CollectionView ItemsSource="{Binding Items}">
        <!-- ... -->
    </CollectionView>
</RefreshView>

3. Item Spacing

xaml

<!-- Use ItemsLayout for spacing -->
<CollectionView ItemsSource="{Binding Items}">
    <CollectionView.ItemsLayout>
        <LinearItemsLayout Orientation="Vertical" 
                          ItemSpacing="10" />
    </CollectionView.ItemsLayout>
    <!-- ... -->
</CollectionView>

4. Header and Footer

xaml

<CollectionView ItemsSource="{Binding Items}">
    <CollectionView.Header>
        <Label Text="My List" 
               FontSize="24" 
               Padding="10" />
    </CollectionView.Header>
    
    <CollectionView.Footer>
        <Label Text="End of list" 
               Padding="10" 
               HorizontalTextAlignment="Center" />
    </CollectionView.Footer>
    
    <!-- ItemTemplate -->
</CollectionView>

5. Load More / Infinite Scroll

xaml

<CollectionView ItemsSource="{Binding Items}"
                RemainingItemsThreshold="5"
                RemainingItemsThresholdReachedCommand="{Binding LoadMoreCommand}">
    <!-- ItemTemplate -->
</CollectionView>

6. Item Sizing Optimization

CollectionView uses ItemSizingStrategy to control item measurement:

xaml

<!-- Default: Each item measured individually (like HasUnevenRows="True") -->
<CollectionView ItemSizingStrategy="MeasureAllItems">
    <!-- ... -->
</CollectionView>

<!-- Performance: Only first item measured, rest use same height -->
<CollectionView ItemSizingStrategy="MeasureFirstItem">
    <!-- Use this when all items have similar heights -->
</CollectionView>

💡 Performance Tip: If your list items have consistent heights, use ItemSizingStrategy="MeasureFirstItem" for better performance with large lists.

.NET 10 Handler Changes (iOS/Mac Catalyst)

ℹ️ .NET 10 uses new optimized CollectionView and CarouselView handlers on iOS and Mac Catalyst by default, providing improved performance and stability.

If you previously opted-in to the new handlers in .NET 9, you should now REMOVE this code:

csharp

// ❌ REMOVE THIS in .NET 10 (these handlers are now default)
#if IOS || MACCATALYST
builder.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler<CollectionView, CollectionViewHandler2>();
    handlers.AddHandler<CarouselView, CarouselViewHandler2>();
});
#endif

The optimized handlers are used automatically in .NET 10 - no configuration needed!

Only if you experience issues, you can revert to the legacy handler:

csharp

// In MauiProgram.cs - only if needed
#if IOS || MACCATALYST
builder.ConfigureMauiHandlers(handlers =>
{
    handlers.AddHandler<Microsoft.Maui.Controls.CollectionView, 
                        Microsoft.Maui.Controls.Handlers.Items.CollectionViewHandler>();
});
#endif

However, Microsoft recommends using the new default handlers for best results.

Testing Checklist

After migration, test these scenarios:

Item selection works correctly
Grouped lists display with proper headers
Swipe actions (if used) work on both iOS and Android
Empty view appears when list is empty
Pull to refresh works (if used)
Scroll performance is acceptable (especially for large lists)
Item sizing is correct (CollectionView auto-sizes by default)
Selection visual state shows/hides correctly
Data binding updates the list correctly
Navigation from list items works

Migration Complexity Factors

ListView to CollectionView migration is complex because:

Each ListView may have unique behaviors
Platform-specific code needs updating
Extensive testing required
Context actions need SwipeView conversion
Grouped lists need template updates
ViewModel changes may be needed

Quick Reference: ListView vs CollectionView

Feature	ListView	CollectionView
Selection Event	`ItemSelected`	`SelectionChanged`
Selection Args	`SelectedItemChangedEventArgs`	`SelectionChangedEventArgs`
Getting Selected	`e.SelectedItem`	`e.CurrentSelection.FirstOrDefault()`
Context Menus	`ContextActions`	`SwipeView`
Grouping	`IsGroupingEnabled="True"`	`IsGrouped="true"`
Group Header	`GroupDisplayBinding`	`GroupHeaderTemplate`
Even Rows	`HasUnevenRows="False"`	Auto-sizes (default)
Empty State	Manual	`EmptyView` property
Cells	TextCell, ImageCell, etc.	Custom DataTemplate

Deprecated APIs (P1 - Fix Soon)

These APIs still work in .NET 10 but show compiler warnings. They will be removed in future versions.

1. Animation Methods

Status: ⚠️ DEPRECATED - All sync animation methods replaced with async versions.

Warning You'll See:

text

warning CS0618: 'ViewExtensions.FadeTo(VisualElement, double, uint, Easing)' is obsolete: 'Please use FadeToAsync instead.'

Migration Table:

Old Method	New Method	Example
`FadeTo()`	`FadeToAsync()`	`await view.FadeToAsync(0, 500);`
`ScaleTo()`	`ScaleToAsync()`	`await view.ScaleToAsync(1.5, 300);`
`TranslateTo()`	`TranslateToAsync()`	`await view.TranslateToAsync(100, 100, 250);`
`RotateTo()`	`RotateToAsync()`	`await view.RotateToAsync(360, 500);`
`RotateXTo()`	`RotateXToAsync()`	`await view.RotateXToAsync(45, 300);`
`RotateYTo()`	`RotateYToAsync()`	`await view.RotateYToAsync(45, 300);`
`ScaleXTo()`	`ScaleXToAsync()`	`await view.ScaleXToAsync(2.0, 300);`
`ScaleYTo()`	`ScaleYToAsync()`	`await view.ScaleYToAsync(2.0, 300);`
`RelRotateTo()`	`RelRotateToAsync()`	`await view.RelRotateToAsync(90, 300);`
`RelScaleTo()`	`RelScaleToAsync()`	`await view.RelScaleToAsync(0.5, 300);`
`LayoutTo()`	`LayoutToAsync()`	See special note below

Migration Examples

Simple Animation:

csharp

// ❌ OLD (Deprecated)
await myButton.FadeTo(0, 500);
await myButton.ScaleTo(1.5, 300);
await myButton.TranslateTo(100, 100, 250);

// ✅ NEW (Required)
await myButton.FadeToAsync(0, 500);
await myButton.ScaleToAsync(1.5, 300);
await myButton.TranslateToAsync(100, 100, 250);

Sequential Animations:

csharp

// ❌ OLD
await image.FadeTo(0, 300);
await image.ScaleTo(0.5, 300);
await image.FadeTo(1, 300);

// ✅ NEW
await image.FadeToAsync(0, 300);
await image.ScaleToAsync(0.5, 300);
await image.FadeToAsync(1, 300);

Parallel Animations:

csharp

// ❌ OLD
await Task.WhenAll(
    image.FadeTo(0, 300),
    image.ScaleTo(0.5, 300),
    image.RotateTo(360, 300)
);

// ✅ NEW
await Task.WhenAll(
    image.FadeToAsync(0, 300),
    image.ScaleToAsync(0.5, 300),
    image.RotateToAsync(360, 300)
);

With Cancellation:

csharp

// NEW: Async methods support cancellation
CancellationTokenSource cts = new();

try
{
    await view.FadeToAsync(0, 2000);
}
catch (TaskCanceledException)
{
    // Animation was cancelled
}

// Cancel from elsewhere
cts.Cancel();

Special Case: LayoutTo

LayoutToAsync() is deprecated with a special message: "Use Translation to animate layout changes."

csharp

// ❌ OLD (Deprecated)
await view.LayoutToAsync(new Rect(100, 100, 200, 200), 250);

// ✅ NEW (Use TranslateToAsync instead)
await view.TranslateToAsync(100, 100, 250);

// Or animate Translation properties directly
var animation = new Animation(v => view.TranslationX = v, 0, 100);
animation.Commit(view, "MoveX", length: 250);

2. DisplayAlert and DisplayActionSheet

Status: ⚠️ DEPRECATED - Sync methods replaced with async versions.

Warning You'll See:

text

warning CS0618: 'Page.DisplayAlert(string, string, string)' is obsolete: 'Use DisplayAlertAsync instead'

Migration Examples

DisplayAlert:

csharp

// ❌ OLD (Deprecated)
await DisplayAlert("Success", "Data saved successfully", "OK");
await DisplayAlert("Error", "Failed to save", "Cancel");
bool result = await DisplayAlert("Confirm", "Delete this item?", "Yes", "No");

// ✅ NEW (Required)
await DisplayAlertAsync("Success", "Data saved successfully", "OK");
await DisplayAlertAsync("Error", "Failed to save", "Cancel");
bool result = await DisplayAlertAsync("Confirm", "Delete this item?", "Yes", "No");

DisplayActionSheet:

csharp

// ❌ OLD (Deprecated)
string action = await DisplayActionSheet(
    "Choose an action",
    "Cancel",
    "Delete",
    "Edit", "Share", "Duplicate"
);

// ✅ NEW (Required)
string action = await DisplayActionSheetAsync(
    "Choose an action",
    "Cancel",
    "Delete",
    "Edit", "Share", "Duplicate"
);

In ViewModels (with IDispatcher):

csharp

// If you're calling from a ViewModel, you'll need access to a Page
public class MyViewModel
{
    private readonly IDispatcher _dispatcher;
    private readonly Page _page;
    
    public MyViewModel(IDispatcher dispatcher, Page page)
    {
        _dispatcher = dispatcher;
        _page = page;
    }
    
    public async Task ShowAlertAsync()
    {
        await _dispatcher.DispatchAsync(async () =>
        {
            await _page.DisplayAlertAsync("Info", "Message from ViewModel", "OK");
        });
    }
}

3. Page.IsBusy

Status: ⚠️ DEPRECATED - Property will be removed in .NET 11.

Warning You'll See:

text

warning CS0618: 'Page.IsBusy' is obsolete: 'Page.IsBusy has been deprecated and will be removed in .NET 11'

Why It's Deprecated:

Inconsistent behavior across platforms
Limited customization options
Doesn't work well with modern MVVM patterns

Migration Examples

Simple Page:

xaml

<!-- ❌ OLD (Deprecated) -->
<ContentPage IsBusy="{Binding IsLoading}">
    <StackLayout>
        <Label Text="Content here" />
    </StackLayout>
</ContentPage>

<!-- ✅ NEW (Recommended) -->
<ContentPage>
    <Grid>
        <!-- Main content -->
        <StackLayout>
            <Label Text="Content here" />
        </StackLayout>
        
        <!-- Loading indicator overlay -->
        <ActivityIndicator IsRunning="{Binding IsLoading}"
                          IsVisible="{Binding IsLoading}"
                          Color="{StaticResource Primary}"
                          VerticalOptions="Center"
                          HorizontalOptions="Center" />
    </Grid>
</ContentPage>

With Loading Overlay:

xaml

<!-- ✅ Better: Custom loading overlay -->
<ContentPage>
    <Grid>
        <!-- Main content -->
        <ScrollView>
            <VerticalStackLayout Padding="20">
                <Label Text="Your content here" />
            </VerticalStackLayout>
        </ScrollView>
        
        <!-- Loading overlay -->
        <Grid IsVisible="{Binding IsLoading}"
              BackgroundColor="#80000000">
            <VerticalStackLayout VerticalOptions="Center"
                               HorizontalOptions="Center"
                               Spacing="10">
                <ActivityIndicator IsRunning="True"
                                 Color="White" />
                <Label Text="Loading..."
                       TextColor="White" />
            </VerticalStackLayout>
        </Grid>
    </Grid>
</ContentPage>

In Code-Behind:

csharp

// ❌ OLD (Deprecated)
public partial class MyPage : ContentPage
{
    async Task LoadDataAsync()
    {
        IsBusy = true;
        try
        {
            await LoadDataFromServerAsync();
        }
        finally
        {
            IsBusy = false;
        }
    }
}

// ✅ NEW (Recommended)
public partial class MyPage : ContentPage
{
    async Task LoadDataAsync()
    {
        LoadingIndicator.IsVisible = true;
        LoadingIndicator.IsRunning = true;
        try
        {
            await LoadDataFromServerAsync();
        }
        finally
        {
            LoadingIndicator.IsVisible = false;
            LoadingIndicator.IsRunning = false;
        }
    }
}

In ViewModel:

csharp

public class MyViewModel : INotifyPropertyChanged
{
    private bool _isLoading;
    public bool IsLoading
    {
        get => _isLoading;
        set
        {
            _isLoading = value;
            OnPropertyChanged();
        }
    }
    
    public async Task LoadDataAsync()
    {
        IsLoading = true;
        try
        {
            await LoadDataFromServerAsync();
        }
        finally
        {
            IsLoading = false;
        }
    }
}

4. MediaPicker APIs

Status: ⚠️ DEPRECATED - Single-selection methods replaced with multi-selection variants.

Warning You'll See:

text

warning CS0618: 'MediaPicker.PickPhotoAsync(MediaPickerOptions)' is obsolete: 'Switch to PickPhotosAsync which also allows multiple selections.'
warning CS0618: 'MediaPicker.PickVideoAsync(MediaPickerOptions)' is obsolete: 'Switch to PickVideosAsync which also allows multiple selections.'

What Changed:

PickPhotoAsync() → PickPhotosAsync() (returns List<FileResult>)
PickVideoAsync() → PickVideosAsync() (returns List<FileResult>)
New SelectionLimit property on MediaPickerOptions (default: 1)
Old methods still work but are marked obsolete

Key Behavior:

Default behavior preserved: SelectionLimit = 1 (single selection)
Set SelectionLimit = 0 for unlimited multi-select
Set SelectionLimit > 1 for specific limits

Platform Notes:

✅ iOS: Selection limit enforced by native picker UI
⚠️ Android: Not all custom pickers honor SelectionLimit - be aware!
⚠️ Windows: SelectionLimit not supported - implement your own validation

Migration Examples

Simple Photo Picker (maintain single-selection behavior):

csharp

// ❌ OLD (Deprecated)
var photo = await MediaPicker.PickPhotoAsync(new MediaPickerOptions
{
    Title = "Pick a photo"
});

if (photo != null)
{
    var stream = await photo.OpenReadAsync();
    MyImage.Source = ImageSource.FromStream(() => stream);
}

// ✅ NEW (maintains same behavior - picks only 1 photo)
var photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions
{
    Title = "Pick a photo",
    SelectionLimit = 1  // Explicit: only 1 photo
});

var photo = photos.FirstOrDefault();
if (photo != null)
{
    var stream = await photo.OpenReadAsync();
    MyImage.Source = ImageSource.FromStream(() => stream);
}

Simple Video Picker (maintain single-selection behavior):

csharp

// ❌ OLD (Deprecated)
var video = await MediaPicker.PickVideoAsync(new MediaPickerOptions
{
    Title = "Pick a video"
});

if (video != null)
{
    VideoPlayer.Source = video.FullPath;
}

// ✅ NEW (maintains same behavior - picks only 1 video)
var videos = await MediaPicker.PickVideosAsync(new MediaPickerOptions
{
    Title = "Pick a video",
    SelectionLimit = 1  // Explicit: only 1 video
});

var video = videos.FirstOrDefault();
if (video != null)
{
    VideoPlayer.Source = video.FullPath;
}

Photo Picker without Options (uses defaults):

csharp

// ❌ OLD (Deprecated)
var photo = await MediaPicker.PickPhotoAsync();

// ✅ NEW (default SelectionLimit = 1, so same behavior)
var photos = await MediaPicker.PickPhotosAsync();
var photo = photos.FirstOrDefault();

Multi-Photo Selection (new capability):

csharp

// ✅ NEW: Pick up to 5 photos
var photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions
{
    Title = "Pick up to 5 photos",
    SelectionLimit = 5
});

foreach (var photo in photos)
{
    var stream = await photo.OpenReadAsync();
    // Process each photo
}

// ✅ NEW: Unlimited selection
var allPhotos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions
{
    Title = "Pick photos",
    SelectionLimit = 0  // No limit
});

Multi-Video Selection (new capability):

csharp

// ✅ NEW: Pick up to 3 videos
var videos = await MediaPicker.PickVideosAsync(new MediaPickerOptions
{
    Title = "Pick up to 3 videos",
    SelectionLimit = 3
});

foreach (var video in videos)
{
    // Process each video
    Console.WriteLine($"Selected: {video.FileName}");
}

Handling Empty Results:

csharp

// NEW: Returns empty list if user cancels (not null)
var photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions
{
    SelectionLimit = 1
});

// ✅ Check for empty list
if (photos.Count == 0)
{
    await DisplayAlertAsync("Cancelled", "No photo selected", "OK");
    return;
}

var photo = photos.First();
// Process photo...

With Try-Catch (same as before):

csharp

try
{
    var photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions
    {
        Title = "Pick a photo",
        SelectionLimit = 1
    });
    
    if (photos.Count > 0)
    {
        await ProcessPhotoAsync(photos.First());
    }
}
catch (PermissionException)
{
    await DisplayAlertAsync("Permission Denied", "Camera access required", "OK");
}
catch (Exception ex)
{
    await DisplayAlertAsync("Error", $"Failed to pick photo: {ex.Message}", "OK");
}

Migration Checklist

When migrating to the new MediaPicker APIs:

Replace PickPhotoAsync() with PickPhotosAsync()
Replace PickVideoAsync() with PickVideosAsync()
Set SelectionLimit = 1 to maintain single-selection behavior
Change FileResult? to List<FileResult> (or use .FirstOrDefault())
Update null checks to empty list checks (photos.Count == 0)
Test on Android - ensure custom pickers respect limit (or add validation)
Test on Windows - add your own limit validation if needed
Consider if multi-select would improve your UX (optional)

Platform-Specific Validation (Windows & Android)

csharp

// ✅ Recommended: Validate selection limit on platforms that don't enforce it
var photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions
{
    Title = "Pick up to 5 photos",
    SelectionLimit = 5
});

// On Windows and some Android pickers, the limit might not be enforced
if (photos.Count > 5)
{
    await DisplayAlertAsync(
        "Too Many Photos", 
        $"Please select up to 5 photos. You selected {photos.Count}.", 
        "OK"
    );
    return;
}

// Continue processing...

Capture Methods (unchanged)

Note: Capture methods (CapturePhotoAsync, CaptureVideoAsync) are NOT deprecated and remain unchanged:

csharp

// ✅ These still work as-is (no changes needed)
var photo = await MediaPicker.CapturePhotoAsync();
var video = await MediaPicker.CaptureVideoAsync();

Quick Migration Pattern

For all existing single-selection code, use this pattern:

csharp

// ❌ OLD
var photo = await MediaPicker.PickPhotoAsync(options);
if (photo != null)
{
    // Process photo
}

// ✅ NEW (drop-in replacement)
var photos = await MediaPicker.PickPhotosAsync(options ?? new MediaPickerOptions { SelectionLimit = 1 });
var photo = photos.FirstOrDefault();
if (photo != null)
{
    // Process photo (same code as before)
}

Recommended Changes (P2)

These changes are recommended but not required immediately. Consider migrating during your next refactoring cycle.

Application.MainPage

Status: ⚠️ DEPRECATED - Property will be removed in future version.

Warning You'll See:

text

warning CS0618: 'Application.MainPage' is obsolete: 'This property is deprecated. Initialize your application by overriding Application.CreateWindow...'

Migration Example

csharp

// ❌ OLD (Deprecated)
public partial class App : Application
{
    public App()
    {
        InitializeComponent();
        MainPage = new AppShell();
    }
    
    // Changing page later
    public void SwitchToLoginPage()
    {
        MainPage = new LoginPage();
    }
}

// ✅ NEW (Recommended)
public partial class App : Application
{
    public App()
    {
        InitializeComponent();
    }
    
    protected override Window CreateWindow(IActivationState? activationState)
    {
        return new Window(new AppShell());
    }
    
    // Changing page later
    public void SwitchToLoginPage()
    {
        if (Windows.Count > 0)
        {
            Windows[0].Page = new LoginPage();
        }
    }
}

Benefits of CreateWindow:

Better multi-window support
More explicit initialization
Cleaner separation of concerns
Works better with Shell

Bulk Migration Tools

Use these find/replace patterns to quickly update your codebase.

Visual Studio / VS Code

Regex Mode - Find/Replace

Animation Methods

regex

Find:    \.FadeTo\(
Replace: .FadeToAsync(

Find:    \.ScaleTo\(
Replace: .ScaleToAsync(

Find:    \.TranslateTo\(
Replace: .TranslateToAsync(

Find:    \.RotateTo\(
Replace: .RotateToAsync(

Find:    \.RotateXTo\(
Replace: .RotateXToAsync(

Find:    \.RotateYTo\(
Replace: .RotateYToAsync(

Find:    \.ScaleXTo\(
Replace: .ScaleXToAsync(

Find:    \.ScaleYTo\(
Replace: .ScaleYToAsync(

Find:    \.RelRotateTo\(
Replace: .RelRotateToAsync(

Find:    \.RelScaleTo\(
Replace: .RelScaleToAsync(

Display Methods

regex

Find:    DisplayAlert\(
Replace: DisplayAlertAsync(

Find:    DisplayActionSheet\(
Replace: DisplayActionSheetAsync(

MediaPicker Methods

⚠️ Note: MediaPicker migration requires manual code changes due to return type changes (FileResult? → List<FileResult>). Use these searches to find instances:

bash

# Find PickPhotoAsync usages
grep -rn "PickPhotoAsync" --include="*.cs" .

# Find PickVideoAsync usages
grep -rn "PickVideoAsync" --include="*.cs" .

Manual Migration Pattern:

csharp

// Find: await MediaPicker.PickPhotoAsync(
// Replace with:
var photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions { SelectionLimit = 1 });
var photo = photos.FirstOrDefault();

// Find: await MediaPicker.PickVideoAsync(
// Replace with:
var videos = await MediaPicker.PickVideosAsync(new MediaPickerOptions { SelectionLimit = 1 });
var video = videos.FirstOrDefault();

ListView/TableView Detection (Manual Migration Required)

⚠️ Note: ListView/TableView migration CANNOT be automated. Use these searches to find instances:

bash

# Find all ListView usages in XAML
grep -r "<ListView" --include="*.xaml" .

# Find all TableView usages in XAML
grep -r "<TableView" --include="*.xaml" .

# Find ListView in C# code
grep -r "new ListView\|ListView " --include="*.cs" .

# Find Cell types in XAML
grep -r "TextCell\|ImageCell\|EntryCell\|SwitchCell\|ViewCell" --include="*.xaml" .

# Find ItemSelected handlers (need to change to SelectionChanged)
grep -r "ItemSelected=" --include="*.xaml" .
grep -r "ItemSelected\s*\+=" --include="*.cs" .

# Find ContextActions (need to change to SwipeView)
grep -r "ContextActions" --include="*.xaml" .

# Find platform-specific ListView code (needs removal)
grep -r "PlatformConfiguration.*ListView" --include="*.cs" .

Create a Migration Inventory:

bash

# Generate a report of all ListView/TableView instances
echo "=== ListView/TableView Migration Inventory ===" > migration-report.txt
echo "" >> migration-report.txt
echo "XAML ListView instances:" >> migration-report.txt
grep -rn "<ListView" --include="*.xaml" . >> migration-report.txt
echo "" >> migration-report.txt
echo "XAML TableView instances:" >> migration-report.txt
grep -rn "<TableView" --include="*.xaml" . >> migration-report.txt
echo "" >> migration-report.txt
echo "ItemSelected handlers:" >> migration-report.txt
grep -rn "ItemSelected" --include="*.xaml" --include="*.cs" . >> migration-report.txt
echo "" >> migration-report.txt
cat migration-report.txt

PowerShell Script

powershell

# Replace animation methods in all .cs files
Get-ChildItem -Path . -Recurse -Filter *.cs | ForEach-Object {
    $content = Get-Content $_.FullName -Raw
    
    # Animation methods
    $content = $content -replace '\.FadeTo\(', '.FadeToAsync('
    $content = $content -replace '\.ScaleTo\(', '.ScaleToAsync('
    $content = $content -replace '\.TranslateTo\(', '.TranslateToAsync('
    $content = $content -replace '\.RotateTo\(', '.RotateToAsync('
    $content = $content -replace '\.RotateXTo\(', '.RotateXToAsync('
    $content = $content -replace '\.RotateYTo\(', '.RotateYToAsync('
    $content = $content -replace '\.ScaleXTo\(', '.ScaleXToAsync('
    $content = $content -replace '\.ScaleYTo\(', '.ScaleYToAsync('
    $content = $content -replace '\.RelRotateTo\(', '.RelRotateToAsync('
    $content = $content -replace '\.RelScaleTo\(', '.RelScaleToAsync('
    
    # Display methods
    $content = $content -replace 'DisplayAlert\(', 'DisplayAlertAsync('
    $content = $content -replace 'DisplayActionSheet\(', 'DisplayActionSheetAsync('
    
    Set-Content $_.FullName $content
}

Write-Host "✅ Migration complete!"

Testing Your Upgrade

Build Validation

bash

# Clean solution
dotnet clean

# Restore packages
dotnet restore

# Build for each platform
dotnet build -f net10.0-android -c Release
dotnet build -f net10.0-ios -c Release
dotnet build -f net10.0-maccatalyst -c Release
dotnet build -f net10.0-windows -c Release

# Check for warnings
dotnet build --no-incremental 2>&1 | grep -i "warning CS0618"

Enable Warnings as Errors (Temporary)

xml

<!-- Add to your .csproj to catch all obsolete API usage -->
<PropertyGroup>
  <WarningsAsErrors>CS0618</WarningsAsErrors>
</PropertyGroup>

Test Checklist

App launches successfully on all platforms
All animations work correctly
Dialogs (alerts/action sheets) display properly
Loading indicators work (if you used IsBusy)
Inter-component communication works (MessagingCenter replacement)
No CS0618 warnings in build output
No runtime exceptions related to obsolete APIs

Troubleshooting

Error: 'MessagingCenter' is inaccessible due to its protection level

Cause: MessagingCenter is now internal in .NET 10.

Solution:

Install CommunityToolkit.Mvvm package
Replace with WeakReferenceMessenger (see MessagingCenter section)
Create message classes for each message type
Don't forget to unregister!

Warning: Animation method is obsolete

Cause: Using sync animation methods (FadeTo, ScaleTo, etc.)

Quick Fix:

bash

# Use PowerShell script from Bulk Migration Tools section
# Or use Find/Replace patterns

Manual Fix: Add Async to the end of each animation method call:

FadeTo → FadeToAsync
ScaleTo → ScaleToAsync
etc.

Page.IsBusy doesn't work anymore

Cause: IsBusy still works but is deprecated.

Solution: Replace with explicit ActivityIndicator (see IsBusy section)

Build fails with "Target framework 'net10.0' not found"

Cause: .NET 10 SDK not installed or not latest version.

Solution:

bash

# Check SDK version
dotnet --version  # Should be 10.0.100 or later

# Install .NET 10 SDK from:
# https://dotnet.microsoft.com/download/dotnet/10.0

# Update workloads
dotnet workload update

MessagingCenter migration breaks existing code

Common Issues:

Forgot to unregister:

csharp

// ⚠️ Memory leak if you don't unregister
protected override void OnDisappearing()
{
    base.OnDisappearing();
    WeakReferenceMessenger.Default.UnregisterAll(this);
}

Wrong message type:

csharp

// ❌ Wrong
WeakReferenceMessenger.Default.Register<UserLoggedIn>(this, handler);
WeakReferenceMessenger.Default.Send(new UserData());  // Wrong type!

// ✅ Correct
WeakReferenceMessenger.Default.Register<UserLoggedInMessage>(this, handler);
WeakReferenceMessenger.Default.Send(new UserLoggedInMessage(userData));

Recipient parameter confusion:

csharp

// The recipient parameter is the object that registered (this)
WeakReferenceMessenger.Default.Register<MyMessage>(this, (recipient, message) =>
{
    // recipient == this
    // message == the message that was sent
});

Warning: MediaPicker methods are obsolete

Cause: Using deprecated PickPhotoAsync or PickVideoAsync methods.

Solution: Migrate to PickPhotosAsync or PickVideosAsync:

csharp

// ❌ OLD
var photo = await MediaPicker.PickPhotoAsync(options);

// ✅ NEW (maintain single-selection)
var photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions 
{ 
    Title = options?.Title,
    SelectionLimit = 1 
});
var photo = photos.FirstOrDefault();

Key Changes:

Return type changes from FileResult? to List<FileResult>
Use .FirstOrDefault() to get single result
Set SelectionLimit = 1 to maintain old behavior
Check photos.Count == 0 instead of photo == null

MediaPicker returns more items than SelectionLimit

Cause: Windows and some Android custom pickers don't enforce SelectionLimit.

Solution: Add manual validation:

csharp

var photos = await MediaPicker.PickPhotosAsync(new MediaPickerOptions
{
    SelectionLimit = 5
});

if (photos.Count > 5)
{
    await DisplayAlertAsync("Error", "Too many photos selected", "OK");
    return;
}

Animation doesn't complete after migration

Cause: Forgetting await keyword.

csharp

// ❌ Wrong - animation runs but code continues immediately
view.FadeToAsync(0, 500);
DoSomethingElse();

// ✅ Correct - wait for animation to complete
await view.FadeToAsync(0, 500);
DoSomethingElse();

Warning: ListView/TableView/TextCell is obsolete

Cause: Using deprecated ListView, TableView, or Cell types.

Solution: Migrate to CollectionView (see ListView and TableView section)

Quick Decision Guide:

Simple list → CollectionView with custom DataTemplate
Settings page with <20 items → VerticalStackLayout with BindableLayout
Settings page with 20+ items → Grouped CollectionView
Grouped data list → CollectionView with IsGrouped="True"

CollectionView doesn't have SelectedItem event

Cause: CollectionView uses SelectionChanged instead of ItemSelected.

Solution:

csharp

// ❌ OLD (ListView)
void OnItemSelected(object sender, SelectedItemChangedEventArgs e)
{
    var item = e.SelectedItem as MyItem;
}

// ✅ NEW (CollectionView)
void OnSelectionChanged(object sender, SelectionChangedEventArgs e)
{
    var item = e.CurrentSelection.FirstOrDefault() as MyItem;
}

Platform-specific ListView configuration is obsolete

Cause: Using Microsoft.Maui.Controls.PlatformConfiguration.*Specific.ListView extensions.

Error:

text

warning CS0618: 'ListView' is obsolete: 'With the deprecation of ListView, this class is obsolete. Please use CollectionView instead.'

Solution:

Remove platform-specific ListView using statements:

csharp

// ❌ Remove these
using Microsoft.Maui.Controls.PlatformConfiguration;
using Microsoft.Maui.Controls.PlatformConfiguration.iOSSpecific;
using Microsoft.Maui.Controls.PlatformConfiguration.AndroidSpecific;

Remove platform-specific ListView calls:

csharp

// ❌ Remove these
myListView.On<iOS>().SetSeparatorStyle(SeparatorStyle.FullWidth);
myListView.On<Android>().IsFastScrollEnabled();
viewCell.On<iOS>().SetDefaultBackgroundColor(Colors.White);

CollectionView has different platform customization options - consult CollectionView docs for alternatives.

CollectionView performance issues after ListView migration

Common Causes:

Not using DataTemplate caching:

xaml

<!-- ❌ Bad performance -->
<CollectionView.ItemTemplate>
    <DataTemplate>
        <ComplexView />
    </DataTemplate>
</CollectionView.ItemTemplate>

<!-- ✅ Better - use simpler templates -->
<CollectionView.ItemTemplate>
    <DataTemplate>
        <VerticalStackLayout Padding="10">
            <Label Text="{Binding Title}" />
        </VerticalStackLayout>
    </DataTemplate>
</CollectionView.ItemTemplate>

Complex nested layouts:
- Avoid deeply nested layouts in ItemTemplate
- Use Grid instead of StackLayout when possible
- Consider FlexLayout for complex layouts

Images not being cached:

xaml

<Image Source="{Binding ImageUrl}"
       Aspect="AspectFill"
       HeightRequest="80"
       WidthRequest="80">
    <Image.Behaviors>
        <!-- Add caching behavior if needed -->
    </Image.Behaviors>
</Image>

Quick Reference Card

Priority Checklist

Must Fix (P0 - Breaking/Critical):

Replace MessagingCenter with WeakReferenceMessenger
Migrate ListView to CollectionView
Migrate TableView to CollectionView or BindableLayout
Replace TextCell, ImageCell, etc. with custom DataTemplates
Convert ContextActions to SwipeView
Remove platform-specific ListView configurations

Should Fix (P1 - Deprecated):

Update animation methods: add Async suffix
Update DisplayAlert → DisplayAlertAsync
Update DisplayActionSheet → DisplayActionSheetAsync
Replace Page.IsBusy with ActivityIndicator
Replace PickPhotoAsync → PickPhotosAsync (with SelectionLimit = 1)
Replace PickVideoAsync → PickVideosAsync (with SelectionLimit = 1)

Nice to Have (P2):

Migrate Application.MainPage to CreateWindow

Common Patterns

csharp

// Animation
await view.FadeToAsync(0, 500);

// Alert
await DisplayAlertAsync("Title", "Message", "OK");

// Messaging
WeakReferenceMessenger.Default.Send(new MyMessage());
WeakReferenceMessenger.Default.Register<MyMessage>(this, (r, m) => { });
WeakReferenceMessenger.Default.UnregisterAll(this);

// Loading
IsLoading = true;
try { await LoadAsync(); }
finally { IsLoading = false; }

Additional Resources

Official Docs: https://learn.microsoft.com/dotnet/maui/
Migration Guide: https://learn.microsoft.com/dotnet/maui/migration/
GitHub Issues: View dotnet/maui on GitHub
CommunityToolkit.Mvvm: https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/

Document Version: 2.0
Last Updated: November 2025
Applies To: .NET MAUI 10.0.100 and later