Skip to content

Upgrading .NET MAUI from .NET 7 to .NET 8

David Ortinau edited this page Nov 16, 2023 · 5 revisions

To upgrade from .NET 7 to 8:

  • First, read the release notes and What's New in .NET 8
  • Install .NET 8 and the .NET MAUI workload with Visual Studio 17.8+, or with the standalone installer and dotnet workload install maui command.
  • Change your target framework (TFM) references from net7.0-* to net8.0-*. If you are using a TFM like net7.0-ios13.6, be sure to match the shipping version of that platform or just remove the platform version (i.e. 13.6).
  • delete your bin and obj folders

We recommend also adding explicit package references to .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 have installed. You may override this by adding <MauiVersion></MauiVersion> to the csproj like this:

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

This is useful when using ad-hoc builds from the Nightly Feed or builds downloaded from pull requests.

Misc Changes

The following behavior has changed from the previous release:

  • Use of the xref:Microsoft.Maui.Controls.Maps.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.
  • 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.
Clone this wiki locally