Dotnet-Maui-9-To-Dotnet-Maui-10-Upgrade

# 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.

---

Table of Contents

1. [Quick Start](#quick-start)

2. [Update Target Framework](#update-target-framework)

3. [Breaking Changes (P0 - Must Fix)](#breaking-changes-p0---must-fix)

- [MessagingCenter Made Internal](#messagingcenter-made-internal)

- [ListView and TableView Deprecated](#listview-and-tableview-deprecated)

4. [Deprecated APIs (P1 - Fix Soon)](#deprecated-apis-p1---fix-soon)

- [Animation Methods](#1-animation-methods)

- [DisplayAlert and DisplayActionSheet](#2-displayalert-and-displayactionsheet)

- [Page.IsBusy](#3-pageisbusy)

- [MediaPicker APIs](#4-mediapicker-apis)

5. [Recommended Changes (P2)](#recommended-changes-p2)

6. [Bulk Migration Tools](#bulk-migration-tools)

7. [Testing Your Upgrade](#testing-your-upgrade)

8. [Troubleshooting](#troubleshooting)

---

Quick Start

**Five-Step Upgrade Process:**

1. **Update TargetFramework** to `net10.0`

2. **Update CommunityToolkit.Maui** to 12.3.0+ (if you use it) - REQUIRED

3. **Fix breaking changes** - MessagingCenter (P0)

4. **Migrate ListView/TableView to CollectionView** (P0 - CRITICAL)

5. **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

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

Multi-Platform

<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:

<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](https://github.com/dotnet/maui/pull/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.

# 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:**

# 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 Interna