Migrating to Uno Platform 7.0

Uno Platform 7.0 removes the native UI rendering backends (native Android Views, native iOS/tvOS UIKit, and the native WebAssembly DOM renderer) and makes Skia the single, implicit rendering engine on every target. It also removes the Mac Catalyst target framework entirely.

Skia already runs on every platform — desktop (Win32, X11, macOS and the Linux framebuffer), Skia-on-Android, Skia-on-iOS, and Skia-on-WebAssembly. In 7.0 it becomes the only UI rendering path: a UIElement is a plain managed object backed by a Composition.Visual on all platforms, drawn into a single Skia surface.

This does not drop platform support: Android, iOS, macOS, Windows, Linux, and WebAssembly all remain supported — they now all render with Skia. The one exception is Mac Catalyst, which is removed as a target framework; macOS is served by the net10.0-desktop head.

Important

This is a hard removal in a single major version — there is no [Obsolete] interim. Plan to recompile every Uno Platform library against 7.0 and update your application heads.

TL;DR

If your app is already a single Sdk="Uno.Sdk" project on .NET 10 or later, this is likely all you need. The steps below cover each item in more detail.

Every app:

  1. Bump Uno.Sdk in global.json.

  2. Update and rebuild every library the app depends on.

  3. If you target Android, update the two head classes. Every Android app needs this, usually in Platforms/Android/MainActivity.Android.cs and Platforms/Android/Main.Android.cs:

    - public class MainActivity : Microsoft.UI.Xaml.ApplicationActivity
+ public class MainActivity : Uno.UI.Runtime.Android.ApplicationActivity

    + using Uno.UI.Hosting;
+
- public class Application : Microsoft.UI.Xaml.NativeApplication
+ public class Application : Uno.UI.Runtime.Android.NativeApplication
  {
      public Application(IntPtr javaReference, JniHandleOwnership transfer)
-         : base(() => new App(), javaReference, transfer)
+         : base(javaReference, transfer)
      {
      }
+
+     protected override UnoPlatformHost CreateHost() =>
+         UnoPlatformHostBuilder.Create()
+             .App(() => new App())
+             .UseAndroid()
+             .Build();
  }

  4. Check that the new minimum versions suit your users: iOS and tvOS 15.0, Android API 24 and WinAppSDK 10.0.19041.0. These apply by default, with no build error. On Windows, packaged apps also need the Windows App Runtime 2.4.0 or later on your users' machines.

  5. Build, fix what the compiler reports, and re-test on your devices.

Only if it applies to your app:

Everything else lives on linked pages you only need to open when something applies to you.

Before you start

Your project What to do
A single Sdk="Uno.Sdk" app project Continue with the steps below.
A project created before Uno Platform 6.0 that still selects a renderer Follow the Uno Platform 6.0 migration guide first.
Separate head projects (*.Mobile, *.Wasm, *.Skia.*, …) or an app on Microsoft.NET.Sdk Convert to the Uno.Sdk first, since these no longer build.
A class library or NuGet package Read Libraries and conditional code as well.
An app or library that uses Prism Remove the Prism Uno Feature as part of the upgrade. The current Prism packages (9.0.537 and earlier) don't build with 7.0, so add Prism back as packages once a release built for Uno Platform 7.0 is out.

Upgrade step by step

1. Update your tools

Update your Visual Studio, Visual Studio Code or Rider extension, then run uno-check to get the matching .NET SDK and workloads.

2. Bump the Uno.Sdk

In the global.json at the root of your solution, set Uno.Sdk to the latest 7.x version from NuGet:

{
  "msbuild-sdks": {
    "Uno.Sdk": "7.x.y"
  }
}

This drives the versions of all Uno Platform packages. In Visual Studio, restart the IDE when the banner asks you to. See How to upgrade Uno Platform NuGet Packages.

3. Update your target frameworks and check minimum versions

In <TargetFrameworks>, in every project:

7.0 also raises the default minimum OS versions, with no build error, so check that they suit your users:

  • iOS and tvOS 15.0, and Android API 24. A head that pins a lower SupportedOSPlatformVersion keeps it, but that combination is no longer tested, so raise it.
  • WinAppSDK 10.0.19041.0. The same goes for a head that pins a lower TargetPlatformMinVersion.

Windows heads now build against Windows App SDK 2.x, so packaged apps need the Windows App Runtime 2.4.0 or later on your users' machines. If you pin WinAppSdkVersion to 1.x, restore fails until you raise it to 2.4.0 or later. If you set WindowsSdkPackageVersion, remove it or use a .87 revision, or the Windows build can fail with CS1705.

4. Clean up UnoFeatures

  • skiarenderer is now implied in an app, so you can usually remove it. Replace it with Skia instead if the app also lists WebGpu and still draws with SkiaSharp, since WebGpu turns off the implied Skia.
  • Remove Prism. The build reports UNOB0035 while UnoFeatures still lists it. The current Prism packages (9.0.537 and earlier) don't build with 7.0, so add Prism back as packages once a release built for Uno Platform 7.0 is available.
  • Remove Lottie and any reference to Uno.WinUI.Lottie. Lottie needs no package on Uno Platform targets now. A project that also targets Windows still references CommunityToolkit.WinUI.Lottie for that target.
  • If code built for Windows uses SKCanvasElement, SKXamlCanvas, Toolkit Skia controls such as ShadowContainer or SkiaSharp itself, list Skia and set <UnoEnableSkiaOnWinAppSdk>true</UnoEnableSkiaOnWinAppSdk>. Skia is off on Windows without that property, even when listed, and the build fails until you set it.
  • If your library uses SKCanvasElement, the SkiaExtensions conversions or Toolkit Skia controls, list Skia.

Your code may use a package that used to arrive implicitly, such as AndroidX or LibVLCSharp. Add those explicitly.

5. Update the Android head

Skip this if you don't target Android. Otherwise, make the edit shown in the TL;DR. Keep anything else your classes contain, such as their attributes or a static constructor.

If your Application class calls ConfigureUniversalImageLoader(), which apps created with the native renderer do, also delete that call, the method and its using Com.Nostra13.Universalimageloader.Core;. Skia handles image loading internally.

See Android head uses the host builder for details.

6. Keep existing settings on iOS and tvOS

Skip this if you don't target iOS or tvOS, or don't use LocalSettings or RoamingSettings. Otherwise, updating users lose access to their saved settings unless you do this, and the build won't warn you. Call this once during startup, before the settings are first read:

#if __IOS__ || __TVOS__
var migrated = Uno.Storage.ApplicationDataMigrator.MigrateSettings();
#endif

The move is one-way. See Application settings on iOS and tvOS before you ship it.

7. Update your libraries and rebuild

Libraries built against 6.x are binary-incompatible with 7.0, and many of the failures only appear at run time. So before you build:

  • Update every third-party Uno Platform library to a version built for 7.0.
  • Recompile every library of your own against 7.0.
  • If you use Uno Themes, Uno Toolkit or Uno Extensions, the Uno.Sdk moves them to a new major. Read their upgrade notes: Uno Themes 9, Uno Toolkit 11 and Uno Extensions 8.

Then delete the bin and obj folders and build each target framework. Use Errors, symptoms and code search to go from each error to its fix.

8. Re-test

Rendering now goes through Skia on every target, and Vulkan is the default on Android, Linux and Windows. Re-baseline visual or snapshot tests, and re-test text, lists and scrolling, IME, pickers, and safe-area or notch handling on devices. Then check for the changes the compiler won't catch, starting with these:

The rest of the guide

Open these only when you need them. Each page starts by saying who should read it.

Page Open it when
Errors, symptoms and code search You have an error or a symptom, or want to scope the upgrade by searching your code.
Project format, target frameworks and OS versions You have separate heads, Mac Catalyst, .NET 9 or pinned OS versions.
Packages and Uno Features You reference packages explicitly, use lock files, or lost a transitive dependency.
Namespace, assembly and host renames Your code names Uno.UI.Toolkit, a *.Skia.* host, or an assembly by name.
App startup, activation and platform state You customize Android startup, activation, lifecycle events or iOS settings.
Libraries and conditional code You author a library, or use #if, XAML prefixes or file suffixes.
Removed public APIs A type or member no longer exists.
WinUI API alignment A member moved, or a base class, signature or constructor changed.
Removed feature flags Your code sets FeatureConfiguration or PrimaryLanguageOverride.
XAML and default styles XAML fails to build or a style or URI no longer resolves.
Behavior changes to re-test The app builds but looks or acts differently.
Full checklist You want every migration task in one list.
Tip

Using an AI agent for the upgrade? Point it at this page and have it work through the steps in order, then run the searches in Search your code and read only the sections that match. Ask it to fix each error using the linked section, rather than suppressing the diagnostic or adding back a removed package.