What's new in .NET MAUI for .NET 8

Article
11/21/2023

The focus of .NET MAUI in .NET 8 is quality. In .NET 8, 1618 pull requests were merged that closed 689 issues. These includes changes from the .NET MAUI team as well as the .NET MAUI community. These changes should result in a significant increase in quality in .NET 8.

Important

Due to working with underlying external dependencies, such as Xcode or Android SDK Tools, the .NET Multi-platform App UI (.NET MAUI) support policy differs from the .NET and .NET Core support policy. For more information, see .NET MAUI support policy.

In .NET 8, .NET MAUI ships as a .NET workload and multiple NuGet packages. The advantage of this approach is that it enables you to easily pin your projects to specific versions, while also enabling you to easily preview unreleased or experimental builds. When you create a new .NET MAUI project the required NuGet packages are automatically added to the project.

This article lists the new features of .NET MAUI for .NET 8 and provides links to more detailed information on each.

For information about what's new in .NET 8, see What's new in .NET 8.

New functionality

While the focus of this release of .NET MAUI is quality, there's also some new functionality that enables new scenarios in your apps.

Controls

Controls that support text input gain extension methods that support hiding and showing the soft input keyboard. For more information, see Hide and show the soft input keyboard.
The ContentPage class gains a HideSoftInputOnTapped property, which indicates whether tapping anywhere on the page will cause the soft input keyboard to hide if it's visible. For more information, see ContentPage.
BlazorWebView gains a StartPath property, a TryDispatchAsync method, and enhanced logging capabilities. For more information, see Host a Blazor web app in a .NET MAUI app using BlazorWebView.
WebView gains a UserAgent property. For more information, see WebView.
Inline media playback of HTML5 video, including autoplay and picture in picture, has been enabled by default for the WebView on iOS. For more information, see Set media playback preferences on iOS and Mac Catalyst.
The Grid.Add overload that accepts 5 arguments has been added back to .NET MAUI. However, this method is deprecated and is only present to aid migrations from Xamarin.Forms.
Grid gains an AddWithSpan extension method that adds a view to the Grid at the specified row and column with the specified row and column spans.

Desktop

Menu bar items and context menu items can be invoked through keyboard shortcuts known as keyboard accelerators. For more information, see Keyboard accelerators.
Windows apps can be published as unpackaged apps. For more information, see Publish an unpackaged .NET MAUI app for Windows with the CLI.

Gesture recognizers

PointerGestureRecognizer gains PointerPressedCommand, PointerPressedCommandParameter, PointerReleasedCommand, PointerReleasedCommandParameter properties, and PointerPressed and PointerReleased events. For more information, see Recognize a pointer gesture.
The PointerEventArgs object that accompanies the pointer events raised by the PointerGestureRecognizer class gains a PlatformArgs property of type PlatformPointerEventArgs. This property provides access to the platform-specific arguments for a pointer gesture event. For more information, see Recognize a pointer gesture.
The DragStartingEventArgs, DragEventArgs, DropEventArgs, and DropCompletedEventArgs objects that accompany drag and drop gesture events each gain a PlatformArgs property. This property provides access to the platform-specific arguments for a drag or drop event. For more information, see Recognize a drag and drop gesture.
The position at which a drag or drop gesture occurred can be obtained by calling the GetPosition method on a DragEventArgs, DragStartingEventArgs, or DropEventArgs object. For more information, see Recognize a drag and drop gesture.
The TapGestureRecognizer class gains the ability to handle secondary taps on Android. For more information, see Recognize a tap gesture.

Shell navigation gains a GoToAsync overload that enables you to pass single use navigation data, that's cleared after navigation has occurred, as a ShellNavigationQueryParameters object. For more information, see Pass single use object-based navigation data.

Platform integration

The Geolocation class can listen for location changes when app's are in the foreground. For more information, see Listen for location changes.
Flashlight gains a IsSupportedAsync method that determines whether a flashlight is available on the device. For more information, see Flashlight.
SensorSpeed intervals have been unified across all platforms. For more information, see Accessing device sensors.
The Permissions class gains the Permissions.Bluetooth permission, which is an Android 12 permission for looking for Bluetooth devices, making the current device discoverable to other Bluetooth devices, and communicating with already-paired Bluetooth devices. For more information, see Permissions.
The Permissions class gains the Permissions.NearbyWifiDevices permission, which is an Android 13 permission for accessing nearby WiFi devices. For more information, see Permissions.

XAML

The x:ClassModifier attribute can be specified on XAML classes, to control the access level for a generated class in an assembly. For more information, see Class modifiers.
Resources defined in a ResourceDictionary can also be consumed in an AppThemeBinding with the DynamicResource markup extension. For more information, see Define and consume theme resources.
Color is the ContentProperty of the SolidColorBrush class, and therefore does not need to be explicitly set from XAML.

Troubleshooting

For troubleshooting purposes, resource generation can be disabled. For more information, see Disable image packaging, Disable splash screen packaging, Disable font packaging, and Disable asset file packaging.
For troubleshooting purposes, a blank splash screen can be generated. For more information, see Generate a blank splash screen.
Resizeter checks for duplicate image filenames. For more information, see Duplicate image filename errors.

Miscellaneous

Window management can be decoupled from the App class. For more information, see Decouple window management from the App class.
Several system fonts can be easily consumed in Android apps. For more information, see Consume fonts.
On iOS, MauiUIApplicationDelegate gains a PerformFetch method that can be overridden or consumed via the iOSLifecycle.PerformFetch delegate. For more information, see iOS platform lifecycle events.

Type deprecation and removal

The following types or members have been deprecated:

ClickGestureRecognizer has been deprecated.
The AutomationProperties.Name, AutomationProperties.HelpText, and AutomationProperties.LabeledBy attached properties have been deprecated.
The FocusChangeRequested has been deprecated. Instead, use the Focus() method to attempt to set focus on the view.

The following types or members have been removed:

The Application.Properties property and Application.SavePropertiesAsync method have been removed. To migrate your app properties data to .NET MAUI, see Migrate data from the Xamarin.Forms app properties dictionary to .NET MAUI preferences.
The PhoneDialer.Current property has been removed. Use PhoneDialer.Default instead.
OpenGLView has been removed.

Behavior changes

The following behavior has changed from the previous release:

Use of the Map control from XAML now requires the following xmlns namespace declaration: xmlns:maps="http://schemas.microsoft.com/dotnet/2021/maui/maps".
Image caching is disabled on Android when loading an image from a stream with the ImageSource.FromStream method. This is due to the lack of data from which to create a reasonable cache key.
On iOS, pages automatically scroll when the soft input keyboard would cover a text entry field, so that the field is above the soft input keyboard. The KeyboardAutoManagerScroll.Disconnect method, in the Microsoft.Maui.Platform namespace, can be called to disable this default behavior. The KeyboardAutoManagerScroll.Connect method can be called to re-enable the behavior after it's been disabled.
How the color of a tab is set in a Shell app has changed on some platforms. For more information, see Tab appearance.
It's not required to specify a value for the $(ApplicationIdGuid) build property in your app's project file. This is because .NET MAUI Windows apps no longer require a GUID as an app ID, and instead use the value of the $(ApplicationId) build property as the app ID. Therefore, the same reverse domain format app ID is now used across all platforms, such as com.mycompany.myapp.
.NET MAUI Mac Catalyst apps are no longer limited to 50 menu items on the menu bar.
The PlatformImage.FromStream method, in the Microsoft.Maui.Graphics namespace, can now be used to load images on Windows instead of having to use the W2DImageLoadingService class.
On Android, animations respect the system animation settings. For more information, see Basic animation.

Performance

There are plenty of performance changes in .NET MAUI 8. These changes can be classified into five areas:

For more information, see .NET 8 Performance Improvements in .NET MAUI.

Upgrade from .NET 7 to .NET 8

To upgrade your projects from .NET 7 to .NET 8, install .NET 8 and the .NET MAUI workload with Visual Studio 17.8+, or with the standalone installer and the dotnet workload install maui command.

Then, open your .csproj file and change the Target Framework Monikers (TFMs) from 7 to 8. If you're using a TFM such as net7.0-ios13.6 be sure to match the platform version or remove it entirely. The following example shows the TFMs for a .NET 7 project:

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

The following example shows the TFMs for a .NET 8 project:

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

Explicit package references should also be added to your .csproj file for the following .NET MAUI NuGet packages:

<ItemGroup>
    <PackageReference Include="Microsoft.Maui.Controls" Version="$(MauiVersion)" />
    <PackageReference Include="Microsoft.Maui.Controls.Compatibility" Version="$(MauiVersion)" />
</ItemGroup>

The $(MauiVersion) variable is referenced from the version of .NET MAUI you've installed. You can override this by adding the $(MauiVersion) build property to your .csproj file:

<Project Sdk="Microsoft.NET.Sdk">
    <PropertyGroup>
        <TargetFrameworks>net8.0-android;net8.0-ios;net8.0-maccatalyst</TargetFrameworks>
        <UseMaui>True</UseMaui>
        <MauiVersion>8.0.3</MauiVersion>
    </PropertyGroup>
</Project>

This can be useful when using ad-hoc builds from the nightly feed or builds downloaded from pull requests.

In addition, the $(ApplicationIdGuid) build property can be removed from your .csproj file in .NET 8. For more information, see Behavior changes.

Prior to building your upgraded app for the first time, delete the bin and obj folders.

Note

The project template for a .NET MAUI app in .NET 8 enables the nullable context for the project with the $(Nullable) build property. For more information, see Nullable.