Transitioning .NET MAUI to CoreCLR: A Guide for .NET 11

Overview

Starting with .NET 11 Preview 4, CoreCLR becomes the default runtime for .NET MAUI applications on Android, iOS, Mac Catalyst, and tvOS. This change unifies the runtime across all .NET workloads—your MAUI app will now run on the same CoreCLR that powers ASP.NET Core, Azure services, and desktop applications. This guide walks you through everything you need to know: what changed, how to update your projects, and how to handle potential pitfalls.

This transition is the culmination of over 15 years of .NET evolution. The Mono runtime first brought .NET to mobile via MonoTouch (2009) and MonoDroid (later Xamarin), and later became the foundation for .NET MAUI. Now, CoreCLR takes over as the default, bringing consistent JIT behavior, garbage collection, and diagnostics across all platforms.

Prerequisites

Before you begin, ensure you have the following:

• .NET 11 SDK (Preview 4 or later) installed. You can download it from the official .NET download page.
• A target platform environment set up for Android, iOS, or Mac Catalyst development (e.g., Xcode for iOS, Android SDK for Android).
• An existing .NET MAUI project targeting .NET 8 or .NET 9 (optional, but used for migration example).
• Familiarity with the .NET CLI and basic MAUI project structure.

Step-by-Step Instructions

Step 1: Check Your Current Runtime

First, confirm which runtime your current MAUI app uses. In your project file (.csproj), look at the TargetFrameworks property. For .NET 8 or 9, you might see something like:

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

At this version, Mono is the default for mobile platforms. If you want to explicitly verify, you can check build output or use diagnostic logging.

Step 2: Update to .NET 11

To take advantage of CoreCLR, change your target frameworks to net11.0:

1. Open your .csproj file.
2. Modify the TargetFrameworks line to use net11.0-android, net11.0-ios, net11.0-maccatalyst, and optionally net11.0-tvos.
3. Ensure all NuGet packages are compatible with .NET 11. Update them using the NuGet Package Manager or CLI.

Example updated TargetFrameworks:

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

Step 3: Build and Run Your App

After updating, build your project:

dotnet build -f net11.0-android

For iOS (requires macOS with Xcode):

dotnet build -f net11.0-ios

Then deploy to a device or emulator. CoreCLR will be used automatically for both Debug and Release configurations. You should see faster startup, more consistent garbage collection, and better integration with tooling like dotnet-counters and dotnet-dump.

Step 4: Handle Potential Issues

If you encounter runtime errors or unexpected behavior, consider the following:

• NuGet compatibility: Some third-party libraries may still rely on Mono-specific features. Check for updated versions targeting .NET 11.
• P/Invoke and native interop: CoreCLR’s loader behaves slightly differently. Review any platform-specific calls.
• GC behavior: CoreCLR uses a different garbage collector by default. Monitor memory usage if you had custom GC settings for Mono.

Step 5: Opt Back to Mono (Temporary Workaround)

If your app cannot run on CoreCLR yet, you can revert to Mono per project by adding a RuntimeIdentifier property in your .csproj:

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

This is a temporary measure; the long-term goal is full CoreCLR support. Be aware that using Mono may prevent you from benefiting from future optimizations and tooling improvements.

Common Mistakes

Forgetting to Update Target Framework for All Platforms

If you leave a platform on net8.0 or net9.0, it will continue using Mono, leading to inconsistent behavior across devices. Always update all target framework monikers to net11.0-*.

Assuming Blazor WebAssembly Also Changes

Blazor WebAssembly (WASM) remains on Mono in .NET 11. Do not attempt to change its runtime. This transition applies only to Android, iOS, Mac Catalyst, and tvOS.

Ignoring NuGet Package Updates

Many libraries that target .NET MAUI may not have updated their package references. Failing to update them can result in build failures or runtime errors. Always run dotnet restore and check for warnings.

Overlooking Diagnostics Tooling Differences

CoreCLR introduces new diagnostics APIs. If you were relying on Mono-specific profiling tools, update your monitoring setup to use cross-platform tools like dotnet-trace and dotnet-counters.

Summary

.NET 11 marks a historic unification: CoreCLR is now the default runtime for .NET MAUI on Android, iOS, Mac Catalyst, and tvOS. By updating your projects to target net11.0-*, you unlock consistent performance, diagnostics, and tooling across all .NET workloads. While the transition is smooth for most apps, be aware of potential NuGet compatibility issues and the option to temporarily revert to Mono. This change completes the journey that began with Mono over 15 years ago, bringing the same high-performance runtime to every platform .NET touches.