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

1. Backup project

2. Install SDK & workloads

3. Update TFMs

4. Update packages

5. Replace deprecated APIs

6. Update manifests

7. Clean and rebuild

8. Test all platforms

9. Update CI/CD

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