How to Prepare Your .NET MAUI Apps for the CoreCLR Transition in .NET 11

Introduction

Starting in .NET 11 Preview 4, CoreCLR becomes the default runtime for .NET MAUI applications on Android, iOS, Mac Catalyst, and tvOS. This means your mobile apps will now run on the same high-performance runtime that powers ASP.NET Core, Azure services, desktop applications, and countless production workloads worldwide. For developers, this change brings runtime unification, better diagnostics, and consistent behavior across platforms. But it also requires understanding how to adapt your projects and workflows. This guide walks you through everything you need to know and the steps to ensure a smooth transition.

How to Prepare Your .NET MAUI Apps for the CoreCLR Transition in .NET 11 — Source: devblogs.microsoft.com

What You Need

.NET 11 SDK – Download the latest preview from dotnet.microsoft.com.
.NET MAUI workload – Install via CLI: dotnet workload install maui.
Target platforms – Android, iOS, Mac Catalyst, or tvOS (not Blazor WebAssembly).
Existing .NET MAUI project (or create a new one).
Familiarity with the .NET MAUI build process – Basic knowledge of csproj files and runtime options.
Testing devices or simulators – For validating your app on target platforms.

Step-by-Step Guide

Step 1: Understand the Change and Its Impact

Before diving into code, grasp what this transition means. For over 15 years, Mono was the runtime enabling .NET on mobile, from MonoTouch (2009) and MonoDroid to Xamarin and .NET MAUI. Now, CoreCLR – the same runtime used by ASP.NET Core and desktop apps – is the default for mobile platforms. This eliminates the split where mobile ran on Mono while server/desktop ran on CoreCLR. Benefits include unified JIT behavior, garbage collection, diagnostics, and a single set of tools. However, be aware that Blazor WebAssembly remains on Mono and is unaffected. Additionally, if you encounter issues, you can temporarily opt back to Mono via a project setting.

Step 2: Set Up Your .NET 11 Preview Environment

Install the .NET 11 SDK (Preview 4 or later). After installation, verify with dotnet --version (should show 11.x). Then install or update the MAUI workload:

Open a terminal or command prompt.
Run dotnet workload install maui (or dotnet workload update if already installed).
Confirm availability: dotnet new maui --list should show MAUI templates.
For iOS and Mac Catalyst development, ensure you have Xcode (on macOS) or appropriate SDKs.

Step 3: Create or Update a .NET MAUI Project

If you have an existing project targeting .NET 8 or 9, update its TargetFramework to net11.0-android, net11.0-ios, net11.0-maccatalyst, or net11.0-tvos. For a new project, use:

dotnet new maui -n MyCoreCLRApp

By default, the project will target CoreCLR for Release and Debug builds. To verify, open the .csproj file and ensure no explicit UseMonoRuntime property is set. Alternatively, you can force CoreCLR by adding false (though this is the default).

Step 4: Build and Run Your App on a Target Platform

Build your app with CoreCLR enabled. Use the standard MAUI commands:

Android: dotnet build -t:Run -f net11.0-android
iOS: dotnet build -t:Run -f net11.0-ios (requires macOS with Xcode)
Mac Catalyst: dotnet build -t:Run -f net11.0-maccatalyst
tvOS: dotnet build -t:Run -f net11.0-tvos

Observe the output – you may notice faster startup or different memory usage. Test core features like UI rendering, data binding, and platform-specific APIs. If you encounter crashes or unexpected behavior, proceed to Step 5.

Step 5: Troubleshoot Issues and Optimize

Because CoreCLR has different garbage collection and JIT characteristics than Mono, you may need to adjust your code or configuration. Common areas to check:

Memory management: CoreCLR’s GC is more performant but may require tuning for resource-constrained mobile devices. Use the dotnet-counters tool to monitor GC statistics.
Reflection and code generation: Some libraries may rely on Mono-specific behaviors. Test with your dependencies.
Debugging: Use dotnet trace or Visual Studio diagnostics – now unified across platforms.
Performance: Compare startup time and frame rate before/after. You can use dotnet-trace to profile.
Third-party libraries: Ensure they are compatible with CoreCLR. Check their documentation for .NET 11 support.

For specific errors, consult the Troubleshooting section below.

Step 6: Opt Back to Mono (Temporary Fallback)

If your app has blocking issues that cannot be resolved quickly, you can temporarily revert to Mono. In your .csproj file, add:

true

Then rebuild. Note that Mono support may be deprecated in future .NET versions, so use this only as a short-term measure. Report any issues to the .NET team via GitHub.

Tips for a Smooth Transition

Start testing early – Begin with .NET 11 Preview 4 to identify issues before the final release.
Focus on runtime-specific code – If you used Mono-specific APIs (e.g., Mono.Runtime), replace them with portable alternatives.
Leverage unified diagnostics – Use the same profiling tools (e.g., dotnet-counters, dotnet-trace) for mobile and backend.
Monitor performance – CoreCLR may improve startup time and memory usage, but test on real devices.
Check third-party dependencies – Verify that NuGet packages and libraries are updated for .NET 11.
Explore the new capabilities – CoreCLR opens doors to advanced features like tiered compilation and better AOT support.
Stay informed – Follow the official .NET MAUI blog and release notes for updates.

Troubleshooting Common Issues

App crashes on launch: Check for missing native dependencies or incorrect target framework.
Slow startup: Try enabling tiered compilation (true in csproj).
GC-related pauses: Adjust GC settings via environment variables (e.g., DOTNET_gcServer).
Incompatible library: Look for a CoreCLR-compatible version or use a workaround.
Build errors: Ensure your MAUI workload is up to date (dotnet workload update).

The shift to CoreCLR marks the next chapter in .NET’s cross-platform journey – one that Mono began more than 15 years ago. By following these steps, you can prepare your apps for a unified, performant future.

Tags: