Blogs
.NET MAUI 11 key changes and upgrade guide

Summarize this blog post with:

TL;DR: .NET MAUI 11 is primarily a runtime, platform, quality, and migration-focused release. CoreCLR is the supported runtime for .NET 11 Android, iOS, tvOS, and Mac Catalyst projects, while NativeAOT is an optional publishing alternative. Android now requires API 24 or later, Android x86 is unsupported while ARM32 remains supported, and default handlers and navigation lifecycle behavior have changed. Before upgrading, validate Release and publish builds, custom handlers, CollectionView2 behavior, navigation, HybridWebView, maps, trimming, NativeAOT, and the exact third-party package versions used by the application.

.NET MAUI 11 brings important changes to the runtime, platform requirements, handlers, and development tools. While these updates improve the development experience, they can also affect how existing applications behave after an upgrade.

The move to CoreCLR, the increased Android minimum API level, and changes to navigation and control handlers are particularly important for teams maintaining production MAUI applications.

In this guide, we’ll explore the key .NET MAUI 11 features, breaking changes, and compatibility considerations. You’ll also learn how to validate your application, identify potential issues, and follow a practical upgrade workflow before moving to production.

Who should read this

This article is for:

  • developers upgrading an existing .NET MAUI app

  • engineering leads planning a framework migration

  • architects reviewing runtime and platform impact

  • teams using custom handlers, trimming, NativeAOT, HybridWebView, maps, or third-party UI libraries

  • teams validating Syncfusion .NET MAUI controls on .NET 11

By the end, you should know:

  • which .NET 11 changes matter most

  • what to test first

  • which app areas are higher risk

  • how to structure a safer upgrade plan

Why .NET 11 matters for MAUI teams

This release updates the runtime model, raises Android requirements, changes default handler behavior, and improves platform APIs and development tools. For existing applications, the primary concern is whether production flows continue to behave correctly in Release and published builds on supported devices.

Treat .NET 11 as a controlled platform migration. The detailed validation sequence appears in the Practical upgrade workflow section to avoid repeating the same package, build, and testing guidance here.

Core runtime changes: CoreCLR is now the default

One of the biggest changes in .NET MAUI 11 is the adoption of CoreCLR as the default runtime.

More specifically, supported .NET 11 Android, iOS, tvOS, and Mac Catalyst projects use CoreCLR. This change should not be interpreted as identical runtime behavior across every MAUI target because platform packaging, deployment, diagnostics, and operating-system constraints still differ. Windows already uses the .NET desktop runtime model, so mobile-runtime migration checks mainly apply to the supported mobile workloads.

For projects moving from .NET 10, remove UseMonoRuntime=true. In a .NET 11 mobile project, that setting causes build error NETSDK1242. Also review tools or scripts that depend on Mono runtime names, libmonosgen package files, stack frames, symbols, or diagnostic events, because these now identify CoreCLR.

Trimming removes unused code during publishing to reduce package size. It can affect reflection, dynamic loading, serialization across unknown types, and third-party libraries that are not trimming-safe. Compare Debug, Release, and production-like publish outputs because these compatibility problems may not appear during a Debug build.

NativeAOT is still opt-in

NativeAOT compiles an application directly into native machine code. Depending on the target platform, application architecture, dependency graph, and publishing configuration, it may improve startup time or memory usage. These outcomes are workload-specific and are not guaranteed.

Evaluate NativeAOT only after establishing a stable CoreCLR baseline, and test it early if the app uses:

  • reflection

  • dynamic loading

  • JSON serialization across unknown types

  • JavaScript to .NET interop

  • third-party libraries not designed for aggressive trimming

Quick decision guide

Runtime optionBest fitMain caution
CoreCLRBest default for most upgradesStill requires Release-build validation
NativeAOTTeams optimizing specific publish scenariosTrimming and dependency compatibility must be tested early

If your team is upgrading first and optimizing later, CoreCLR is the safer starting point.

New platform test projects

These templates simplify testing in an application-aware environment during migration.

The available template short names are androidtest, iostest, tvostest, macostest, and maccatalysttest.

dotnet new androidtest -n MauiUpgradeTests
cd MauiUpgradeTests
dotnet test

Platform test projects complement, rather than replace, unit tests, UI automation, integration tests, and real-device validation.

For current details, see What’s new in .NET MAUI for .NET 11

Control, handler, and navigation changes to test first

A handler connects a cross-platform control, such as Button or Entry, to its native implementation. A MAUI app may compile successfully but still experience UI regressions at runtime because handlers, theming, layout behavior, or navigation timing changed.

1. Material 3 behavior on Android

Android handlers for ImageButton, DatePicker, Entry, and Slider now reflect Material 3 styling and behavior. Validate control sizing, spacing, padding, text scaling, accessibility, and consistency with existing themes.

2. CollectionView2 on Windows

Windows uses CollectionView2 by default. On collection-heavy screens, test item measurement and layout, grouped data, empty views, headers and footers, selection state, scrolling position, incremental loading, complex templates, and virtualization-sensitive behavior. Also verify keyboard and pointer interaction when the screen depends on desktop input.

3. Shell, NavigationPage, and TabbedPage handlers

Android Shell apps now use the handler-based architecture by default. Test apps that use custom Shell renderers, route handling, flyout customization, tab behavior, or native navigation modifications.

On iOS and Mac Catalyst, NavigationPage and TabbedPage use new handlers by default. Their layout, navigation bar, tabs, lifecycle ordering, and custom renderer or handler integrations should be included in regression testing.

4. Navigation lifecycle assumptions

On iOS and Mac Catalyst, NavigationPage’s Appearing event now occurs before the page is pushed. Code that assumes the page is already visible should use NavigatedTo instead. Retest delayed initialization, analytics, focus changes, animation starts, and asynchronous work currently triggered from Appearing.

5. HybridWebView and JavaScript interop

For JavaScript-to-.NET invocation, .NET 11 provides a SetInvokeJavaScriptTarget overload that accepts a source-generated JsonSerializerContext. Using the source-generated JSON metadata path avoids reflection-based serialization and supports NativeAOT and full trimming when configured correctly. Validate the generated context, analyzer configuration, serialized types, and Release/publish behavior.

6. SwipeItem visuals

If your app depends on icons inside swipe actions, verify image tint behavior and set IconColor explicitly when needed.

XAML and tooling improvements

.NET 11 includes several improvements that make MAUI development smoother.

Notable updates include:

  • Incremental Hot Reload can update existing live page and control instances

  • lazy ResourceDictionary creation when XAML source generation is enabled

  • more trim-safe compiled RelativeSource ancestor bindings

  • implicit XAML namespaces enabled by default

  • compiled binding improvements inside DataTemplate

  • support for x:Code with preview features enabled

  • improved dotnet run and dotnet watch workflows

These updates are useful, but they should be treated as development-time improvements. They do not replace Release-mode testing or production publish validation.

Other notable .NET MAUI 11 additions

To support the “What’s New” scope, this section summarizes several prominent additions beyond migration behavior.

  • LongPressGestureRecognizer provides built-in long-press handling with duration, movement threshold, state, command, and event support.

  • BoxView adds a Fill property that accepts brushes, including linear and radial gradients.

  • TabbedPage supports badges through BadgeText, BadgeColor, and BadgeTextColor attached properties.

  • SwipeItem adds theme-aware IconColor and TextColor properties.

  • Map adds capabilities such as pin clustering, custom pin icons, map-element events, visibility and Z-order controls, and additional location and region APIs. On Windows, the Map implementation is backed by Azure Maps and requires an Azure Maps subscription key. Map capabilities remain platform-specific, so verify each required feature on every intended target.

New platform API improvements

.NET 11 also adds or improves passkeys, MediaPicker, Window.StatusBarTheme, Geolocation, Windows AppInstance activation, and accessibility-related APIs.

Validate each API against its supported platforms and required permissions.

Android and Apple platform requirements

Android

The minimum supported Android API level is API 24. This value controls the oldest Android version on which the app can run. It is different from the target SDK version, which declares the Android API level against which the app is designed and can affect platform compatibility behavior and store requirements. Do not use the terms interchangeably.

Android x86 is no longer supported. Android ARM32 remains supported. Review device coverage, emulator images, CI agents, and customer support expectations before migration.

Example project configuration:

<PropertyGroup>
  <SupportedOSPlatformVersion Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">24</SupportedOSPlatformVersion>
</PropertyGroup>

If android:minSdkVersion is explicitly configured in AndroidManifest.xml, it must match the project setting. Configure the target SDK separately according to the installed .NET for Android workload, Android tooling, and current store requirements.

Apple platforms

For Apple targets, verify the supported OS and Xcode requirements for the exact .NET MAUI workload and servicing release used for publication. Also include the new NavigationPage and TabbedPage handlers and the NavigationPage lifecycle timing change in iOS and Mac Catalyst validation.

Breaking changes to review before upgrading

Review the following documented changes before upgrading. This table consolidates the previous breaking-change list and risk table.

ChangeImpactRecommended action
CoreCLR replaces Mono for supported .NET 11 mobile workloadsRuntime names, package files, symbols, diagnostics, tooling, and behavior can change. UseMonoRuntime=true causes NETSDK1242.Remove UseMonoRuntime=true and update Mono-dependent tools or scripts.
Android API 24 minimumDevices below API 24 are no longer supported.Review analytics and support commitments; align SupportedOSPlatformVersion and any explicit minSdkVersion.
Android x86 removedx86 emulator or device targets no longer build or run; ARM32 remains supported.Replace x86 emulator and CI coverage with supported architectures.
Android Shell handler enabled by defaultCustom Shell renderers and navigation customizations can regress.Test routes, flyout, tabs, navigation customization, and custom integrations.
NavigationPage and TabbedPage handlers on iOS and Mac CatalystVisual behavior and lifecycle ordering can change.Test navigation bars, tabs, custom handlers/renderers, and page lifecycle code.
NavigationPage Appearing timingAppearing occurs before the page is pushed on iOS and Mac Catalyst.Use NavigatedTo for work that assumes the page is visible.
Microsoft.Maui.Controls.Compatibility removedProjects explicitly referencing the package can fail to restore, build, or run as expected.Remove the package reference and migrate remaining compatibility renderers or APIs to handlers and supported APIs.
CollectionView2 default on WindowsLayout, selection, grouping, scrolling, and virtualization behavior can differ.Regression-test complex collection screens and input behavior.
Trimming and NativeAOT-sensitive codeReflection, dynamic loading, serialization, interop, and incompatible dependencies can fail at publish time or runtime.Validate production-like publish output and dependencies early.
Obsolete APIs and SwipeItem tint behaviorSource cleanup or explicit styling may be required.Replace obsolete animation APIs and verify SwipeItem IconColor.

What .NET 11 means for Syncfusion .NET MAUI users

Syncfusion® Essential Studio for .NET MAUI v35.1.46 release notes explicitly confirm .NET 11 support across the controls in that release. Use v35.1.46 or another package version whose release documentation explicitly confirms compatibility with the selected .NET 11 workload. Do not assume that every older Syncfusion package version supports .NET 11.

Review the Syncfusion v35.1.46 release notes and the Syncfusion .NET MAUI controls documentation for the exact packages and controls used by the application.

Prioritize these business-critical scenarios:

  • DataGrid scrolling, sorting, grouping, selection, editing, and virtualization

  • ListView item templates, selection, scrolling, and load-on-demand behavior

  • Scheduler appointments, recurrence, navigation, and time-zone behavior

  • Charts rendering, labels, legends, selection, zooming, and interaction

  • PDF Viewer loading, navigation, annotations, forms, and large documents

  • CollectionView and custom template behavior

  • Touch, swipe, drag, keyboard, and accessibility interactions

  • Android Material 3 styling and handler-dependent appearance

  • iOS and Mac Catalyst page-lifecycle and navigation behavior

  • Release builds, trimming, publishing, and NativeAOT where applicable

Test the exact Syncfusion package version, .NET MAUI workload, runtime, target platform, device, and production publishing configuration used by the application.

Practical upgrade workflow

Use this sequence for a safer upgrade.

1. Pin the SDK

Create a migration branch and update the project target frameworks to .NET 11. Include only the platforms supported by the application. For example:

<PropertyGroup>
  <TargetFrameworks>net11.0-android;net11.0-ios;net11.0-maccatalyst</TargetFrameworks>
  <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net11.0-windows10.0.19041.0</TargetFrameworks>
  <UseMaui>true</UseMaui>
</PropertyGroup>

Add global.json so the team uses the same installed SDK. The 11.0.100 value below is an example only; replace it with the final .NET 11 SDK version installed and approved for the migration.

{
  "sdk": {
    "version": "11.0.100"
  }
}
dotnet --info

2. Restore workloads and packages

dotnet workload list
dotnet workload restore
dotnet restore

Record all third-party package versions, including Syncfusion packages, and remove any explicit Microsoft.Maui.Controls.Compatibility reference.

3. Build every target in Release mode

Use explicit target frameworks so each intended platform is built rather than relying on one host-default target.

dotnet build MyApp.csproj -f net11.0-android -c Release
dotnet build MyApp.csproj -f net11.0-ios -c Release
dotnet build MyApp.csproj -f net11.0-maccatalyst -c Release
dotnet build MyApp.csproj -f net11.0-windows10.0.19041.0 -c Release

Run Apple-target builds on a supported macOS/Xcode environment and Windows-target builds on Windows. Review compile errors, obsolete warnings, trimming warnings, runtime configuration, and platform-specific output.

4. Publish with production-like settings

Run the publish command with the target framework and runtime identifier used by the production pipeline. For example, an Android ARM64 validation publish can start with:

dotnet publish MyApp.csproj -f net11.0-android -c Release -r android-arm64

Apply the application’s actual signing, store packaging, trimming, NativeAOT, and deployment properties. Use the platform-specific Microsoft publishing guide for the final production command because required properties vary by Android, iOS, Mac Catalyst, and Windows. See the .NET MAUI deployment documentation

5. Run smoke tests on real scenarios

  • app startup and authentication

  • Shell, NavigationPage, and TabbedPage flows

  • CollectionView2 screens on Windows

  • Syncfusion DataGrid, ListView, Scheduler, Charts, and PDF Viewer screens used by the app

  • Material 3-affected Android controls

  • maps, including Azure Maps configuration on Windows

  • HybridWebView JavaScript-to-.NET flows

  • file, media, location, and permission flows

  • accessibility and keyboard interaction

  • production-like trimming, publishing, and NativeAOT scenarios where applicable

6. Record results by target

  • platform and OS version

  • device, emulator, or simulator

  • runtime and architecture

  • build configuration and trimming mode

  • package versions

  • pass or fail result and evidence

Common upgrade mistakes to avoid

  • leaving UseMonoRuntime=true in a .NET 11 mobile project

  • testing only Debug builds or only one target framework

  • using only emulators instead of representative real devices

  • treating minimum Android API level and target SDK version as the same setting

  • assuming older third-party packages are compatible without release-note confirmation

  • enabling NativeAOT before establishing a stable CoreCLR baseline

  • checking build success but not publish and packaged-app behavior

Note: Start by validating high-risk screens, then gradually expand test coverage.

Should your team adopt .NET 11 now?

Adopt .NET 11 for evaluation and migration testing when you need early compatibility results. Move broadly to production only after validating supported devices, exact package versions, production publishing, store submission, monitoring, and rollback.

The right mindset is not “Can we upgrade?” but “Have we validated the flows that matter?”

Frequently asked questions

Does every MAUI app need NativeAOT?

No. CoreCLR is the supported runtime for .NET 11 mobile workloads, while NativeAOT is an optional publishing alternative. Enable it only after validating platform support, trimming, interop, architecture, and dependency compatibility.

What is the main Android migration change?

The minimum supported Android API level is 24, and Android x86 is no longer supported while ARM32 remains supported. Review device coverage, emulator images, CI targets, and the separate target SDK configuration before migration.

Should Syncfusion users do anything different?

Use Syncfusion v35.1.46 or another version whose release notes explicitly confirm .NET 11 support. Test the exact package versions and business-critical controls under the production runtime, target platform, build, trimming, and publish settings.

Conclusion

.NET MAUI 11 changes the runtime, Android baseline, default handlers, navigation timing, and several publishing-sensitive behaviors. Start by updating the target frameworks and SDK, remove Mono and compatibility-package assumptions, then validate each supported platform in Release and production-like publish configurations.

If the application uses Syncfusion .NET MAUI controls, select a version whose release notes confirm .NET 11 support and include its business-critical controls in the first compatibility pass. Build success is only the start; complete the migration by validating the packaged application on representative devices and recording the results before rollout.

Meet the Author

Prithis Iyyappan

Prithis Iyyappan has been a software engineer/.NET developer since 2022, working on developing customized and feature-rich front-end UI components for .NET MAUI and Xamarin.Forms at Syncfusion.