How to Upgrade Your .NET MAUI Apps to CoreCLR in .NET 11

Introduction

Starting with .NET 11 Preview 4, .NET MAUI applications on Android, iOS, and Mac Catalyst run on the CoreCLR runtime by default. This is a major shift from the Mono runtime that powered mobile .NET apps for over a decade. CoreCLR is the same high-performance runtime used by ASP.NET Core, Azure services, and desktop applications—bringing runtime unification, better diagnostics, and improved performance to your mobile apps. This guide walks you through the steps to upgrade your existing .NET MAUI projects to leverage CoreCLR, understand what changed, and handle any transition issues.

What You Need

• .NET 11 SDK Preview 4 or later – Download from dotnet.microsoft.com
• Visual Studio 2022 (17.12+) or JetBrains Rider with .NET 11 support
• An existing .NET MAUI project targeting .NET 10 or earlier (optional, for migration)
• Familiarity with .NET MAUI development
• Target devices or emulators for Android, iOS, and Mac Catalyst

Step-by-Step Guide

Step 1: Understand the Runtime Change

First, know what’s happening. In .NET 11, default builds for Android, iOS, Mac Catalyst, and tvOS use CoreCLR instead of Mono. This does not affect Blazor WebAssembly (still Mono). You can opt back to Mono if needed (Step 6). Review the official documentation on runtimes and compilation for more details.

Step 2: Install .NET 11 Preview 4

Download and install the .NET 11 SDK from the official site. Ensure you include the MAUI workload:

dotnet workload install maui

Verify installation:

dotnet --list-sdks

You should see version 11.0.x-preview.x.

Step 3: Open Your .NET MAUI Project and Retarget to .NET 11

If upgrading from .NET 9 or 10, edit the .csproj file. Change the TargetFrameworks to use net11.0-android, net11.0-ios, etc. Example:

<TargetFrameworks>net11.0-android;net11.0-ios;net11.0-maccatalyst</TargetFrameworks>

You may need to update any NuGet packages to versions compatible with .NET 11.

Step 4: Build and Run with CoreCLR Default

Build your project normally. For Release and Debug configurations, CoreCLR is now the default. No special flags are required. Run on a device or emulator. Your app will use the same runtime as your backend services, providing consistent JIT behavior, garbage collection, and diagnostics.

Step 5: Verify the Runtime

To confirm your app is using CoreCLR, check the logs or use diagnostics. On Android, you can look at the adb logcat output for runtime initialization messages. Alternatively, in code you can check System.Runtime.InteropServices.RuntimeInformation.FrameworkDescription—it will show ".NET 11.0.x" (CoreCLR) instead of ".NET (Mono)".

Step 6: Handle Issues – Opt Back to Mono (Temporary)

If you encounter compatibility issues during the transition, you can revert to Mono by setting a build property in your .csproj:

<PropertyGroup>
  <UseMonoRuntime>true</UseMonoRuntime>
</PropertyGroup>

This allows you to continue development while you fix any runtime-dependent code. However, plan to remove this flag as soon as possible to benefit from CoreCLR.

Step 7: Leverage Unified Tooling and Diagnostics

With CoreCLR across all platforms, you can use the same profiling, debugging, and monitoring tools for mobile as for server apps. For example:

• dotnet-counters and dotnet-trace now work on mobile.
• Performance counters and GC logs are identical.
• Memory dump analysis using same toolset.

Integrate these into your CI/CD pipeline for mobile performance testing.

Tips for a Smooth Transition

• Test early, test often: Start with a simple app to validate CoreCLR behavior before upgrading complex projects.
• Understand Mono’s legacy: Mono made .NET mobile possible for 15+ years—from MonoTouch to Xamarin to MAUI. CoreCLR is the next chapter, not an end. Many libraries (e.g., Unity, Avalonia, Uno, MonoGame) still rely on Mono in other contexts.
• Check NuGet compatibility: Some native bindings or P/Invoke code may assume Mono’s marshalling. Test third-party packages.
• Use conditional compilation if you need platform-specific runtime code. For example, check RuntimeInformation.FrameworkDescription to differentiate Mono vs CoreCLR.
• Monitor performance: CoreCLR often brings faster JIT and better GC, but verify with real device benchmarks.
• Stay updated: .NET 11 is in preview; follow the MAUI GitHub repo for changes.
• Expect improved diagnostics: Unified runtime means fewer surprises in production.

By following these steps, your .NET MAUI apps will join the millions of production workloads already running on CoreCLR—the same runtime that powers Azure, ASP.NET Core, and desktop apps. Embrace the unification and enjoy simpler, more powerful mobile development.