Technical Migration Guide: Upgrading .NET MAUI Projects from .NET 9 to .NET 10

Introduction

Migrating a production-grade .NET MAUI application from .NET 9 to .NET 10 is a significant undertaking that requires careful planning, a thorough understanding of breaking changes, and diligent validation across all supported platforms. .NET 10 introduces major improvements in performance, diagnostics, and developer productivity, but also includes critical breaking changes, deprecated APIs, and updated platform requirements that must be addressed to ensure a smooth transition and continued production stability.

This guide provides a comprehensive, step-by-step approach to upgrading your .NET MAUI project, including prerequisites, environment setup, SDK and workload updates, project file changes, platform-specific migration steps, testing strategies, CI/CD considerations, and best practices for a robust migration.

This article covers:

Environment and SDK prerequisites
Changes in workloads and tooling
Updates to .csproj and platform targets
Breaking changes and deprecated APIs
Migration steps for Android, iOS, Windows, and macOS
Post-migration testing and validation
Best practices for production readiness

1. Prerequisites and Environment Setup

1.1 Supported Operating Systems and Hardware

Ensure your environment meets minimum requirements:

Windows: Windows 11 (21H2+) or Windows 10 (1909+)
macOS: macOS 12 or higher
Hardware: x86/x64 CPU, 4 GB RAM minimum (16 GB recommended), up to 210 GB disk space

These apply to both developer machines and CI/CD agents.

1.2 Development Tools

Visual Studio 2026 or later
Visual Studio Code with .NET MAUI extension (optional)
Xcode 26+ (iOS/Mac Catalyst)
Latest Android SDK (API 24+ recommended)

Install Workloads

dotnet workload install maui
dotnet workload install android
dotnet workload install ios
dotnet workload install maccatalyst
dotnet workload install windows

Verify:

dotnet --version
dotnet workload list

1.3 Backup and Source Control

Commit all code
Tag current version (e.g., v9.0-production)
Back up project directory

2. SDK, Workloads, and Tooling Changes

2.1 .NET 10 Workload Model

Workload sets for stable installations
Android API 36, JDK 21 support
iOS 18.2, macOS 15.2 minimums
Full MAUI support in VS 2026+

2.2 NuGet Package Compatibility

Update all packages:

dotnet list package --outdated

Key updates:

Microsoft.Maui.* → 10.0.0+
CommunityToolkit.Maui → 12.3.0+

3. Updating .csproj and Target Frameworks

3.1 Target Frameworks

<PropertyGroup>
  <TargetFrameworks>net10.0-android;net10.0-ios;net10.0-maccatalyst;net10.0-windows10.0.19041.0</TargetFrameworks>
</PropertyGroup>

Conditional TFMs for OS-specific builds supported.

3.2 Platform Version Properties

<SupportedOSPlatformVersion Condition="'$(TargetFrameworkIdentifier)'=='android'">24.0</SupportedOSPlatformVersion>

(Repeat for iOS, macOS, Windows.)

3.3 Additional Project Updates

Remove obsolete properties
Enable XAML source generation

<MauiXamlInflator>SourceGen</MauiXamlInflator>

Windows fix if needed:

<WindowsPackageType>None</WindowsPackageType>

4. Breaking Changes and Deprecated APIs

Major removals and replacements:

Area	Change	Replacement
MessagingCenter	Removed	WeakReferenceMessenger
ListView/TableView	Deprecated	CollectionView
Animation methods	Sync deprecated	Async versions
DisplayAlert	Sync deprecated	DisplayAlertAsync
Page.IsBusy	Deprecated	ActivityIndicator
MediaPicker	Old methods deprecated	PickPhotosAsync
Application.MainPage	Deprecated	CreateWindow override

5. Platform-Specific Migration

5.1 Android

Target net10.0-android
Align minSdkVersion
Install JDK 21
Rebuild and test on devices

5.2 iOS and Mac Catalyst

Target net10.0-ios / maccatalyst
Install Xcode 26
Update provisioning
Address trimmer warnings

5.3 Windows

Target net10.0-windows10.0.19041.0
Add WindowsPackageType if needed
Test MSIX packaging

5.4 macOS

Target net10.0-macos
Validate entitlements and dependencies

6. Code Migration Examples

MessagingCenter → WeakReferenceMessenger

WeakReferenceMessenger.Default.Send(new UserLoggedInMessage(user));

ListView → CollectionView

Use DataTemplates with CollectionView.

Animation APIs

await button.FadeToAsync(0, 500);

MediaPicker

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

7. Testing and Validation

Unit tests (xUnit)
Device testing across platforms
Automated UI testing (XHarness)
Performance profiling (dotnet-trace, PerfView)
Treat obsolete warnings as errors

8. CI/CD Updates

Install .NET 10 SDK on agents
Install MAUI workloads
Update signing for Android, iOS, Windows
Publish packages with updated versioning

9. Performance and Diagnostics

New metrics:

maui.layout.measure_duration
maui.layout.arrange_duration

OpenTelemetry supported for tracing and monitoring.

10. Migration Checklist

Backup project
Install SDK & workloads
Update TFMs
Update packages
Replace deprecated APIs
Update manifests
Clean and rebuild
Test all platforms
Update CI/CD
Monitor production

11. Troubleshooting

Common issues include MessagingCenter removal, ListView deprecation, SDK mismatch errors, Android minSdk conflicts, Windows startup errors, and trimmer warnings.

12. Best Practices

Resolve all warnings
Test on real devices
Automate builds
Monitor performance
Keep MAUI updated regularly

13. Automation Scripts

PowerShell TFM Update

Get-ChildItem -Recurse -Filter *.csproj | ForEach-Object {
 (Get-Content $_.FullName) -replace 'net9.0', 'net10.0' | Set-Content $_.FullName
}

14. Conclusion

Migrating from .NET 9 to .NET 10 in a .NET MAUI application unlocks performance, diagnostics, and tooling improvements, but requires disciplined upgrades across code, dependencies, platforms, and pipelines. With structured planning, testing, and observability, you can ensure a stable, production-ready transition.