Using the Uno.Sdk

Uno Platform projects use the Uno.Sdk package that is designed to keep projects simple, yet configurable. It imports the Microsoft.Net.Sdk (and the Microsoft.Net.Sdk.Web for WebAssembly).

This document explains the many features of this SDK and how to configure its behavior.

Tip

Uno.Sdk enabled projects are best experienced using the MSBuild Editor Visual Studio Extension to provide intellisense.

Managing the Uno.Sdk version

Updating the Uno.Sdk is done through the global.json file.

Solution-less projects and `.slnx` solutions

Uno.Sdk projects are standard .NET SDK-style projects: a single .csproj is all you need to build, run, and publish an application. A solution file is a convenience for IDEs and multi-project repositories — it is not a requirement of the Uno.Sdk or the .NET CLI.

From the directory containing your project file:

dotnet build -f net10.0-desktop
dotnet run -f net10.0-desktop
dotnet publish -f net10.0-desktop -c Release

Important

The global.json file that selects your Uno.Sdk version applies to projects, not solutions. When working without a solution file, keep global.json in the project directory or in any parent directory.

IDE dev-loop tooling (Hot Reload, the Dev Server, and Uno Platform Studio add-ins) supports solution-less workspaces starting with Uno.Sdk 6.6. In VS Code, this additionally requires the Uno Platform extension 0.25.3 or later together with the C# Dev Kit extension. On earlier Uno.Sdk versions the Dev Server still starts, but the Studio add-ins are not loaded.

Using the `.slnx` solution format

The XML-based .slnx solution format is fully supported — by the .NET CLI, by the Uno Platform IDE extensions, and by the Dev Server (workspace discovery enumerates both .sln and .slnx files):

<Solution>
  <Project Path="MyApp/MyApp.csproj" />
</Solution>

To convert an existing solution, run:

dotnet sln MyApp.sln migrate

Uno Platform Features

As Uno Platform can be used in many different ways, in order to reduce the build time and avoid downloading many packages, the Uno.Sdk offers a way to simplify which Uno Platform features should be enabled.

You can use the UnoFeatures property in the csproj or Directory.Build.props as shown here:

<UnoFeatures>
    Material;
    Hosting;
    Toolkit;
    Logging;
    LoggingSerilog;
    MVUX;
    Configuration;
    Http;
    HttpRefit;
    HttpKiota;
    Serialization;
    Localization;
    Navigation;
</UnoFeatures>

Important

Once you have changed the features list, Visual Studio requires restoring packages explicitly, or building the app once for the change to take effect.

This allows for the SDK to selectively include references to relevant sets of Nuget packages to enable features for your app.

Here are the supported features:

Feature	Description
`AndroidAuto`	Configures the Android target for Android Auto and Android Automotive OS by adding the Xamarin.AndroidX.Car.App.App package.
`AndroidTV`	Configures the Android target for Android TV by adding the Xamarin.AndroidX.Leanback package.
`AndroidWear`	Adds Wear OS support to the Android target with the Xamarin.AndroidX.Wear and Xamarin.AndroidX.Wear.Tiles packages, and raises the default Android `SupportedOSPlatformVersion` to 26.
`Authentication`	Adds the Uno.Extensions packages for Custom Authentication.
`AuthenticationMsal`	Adds the Uno.Extensions packages for Authentication using Microsoft.Identity.Client.
`AuthenticationOidc`	Adds the Uno.Extensions packages for Authentication using a custom Oidc client.
`Configuration`	Adds the Uno.Extensions packages for Configuration.
`CSharpMarkup`	Adds support for C# Markup.
`Cupertino`	Adds support for the Cupertino Design Theme library. If the `Toolkit` feature is also used, it will add support for the Cupertino Design Toolkit library.
`Dsp`	Adds support for the Uno.Dsp.Tasks packages.
`Extensions`	Adds the most commonly used Extensions Packages for Hosting, Configuration, and Logging.
`ExtensionsCore`	Adds the Uno.Extensions.Core.WinUI package, without the other Extensions packages. Same as `ThemeService`.
`Foldable`	Adds a reference to Uno.WinUI.Foldable.
`GLCanvas`	Adds support for the OpenGL Canvas.
`GooglePlay`	Adds support for In App Reviews. For more information, see the Store Context documentation.
`Hosting`	Adds support for Dependency Injection using Uno.Extensions.Hosting packages.
`Http`	Adds support for custom Http Clients with Uno.Extensions.
`HttpRefit`	Adds support for strongly-typed REST API clients via Refit
`HttpKiota`	Adds support for OpenAPI-generated clients via Kiota
`Localization`	Adds support for Localization using Uno.Extensions.
`Logging`	Adds support for Logging using Uno.Extensions.
`LoggingSerilog`	Adds support for Serilog using Uno.Extensions.
`Material`	Adds support for the Material Design Theme library. If the `Toolkit` feature is also used, it will add support for the Material Design Toolkit library.
`MauiNativeEmbedding`	Adds support for embedding Maui controls in Uno Platform applications with the native embedding of Uno.Extensions (formerly `MauiEmbedding`, which now selects `Uno.Maui.Embedding`).
`MauiEmbedding`	Adds Uno.Maui.Embedding and Uno.Maui.Handlers so third-party .NET MAUI control libraries (including Windows-only builds) can run in Uno Platform applications. Implies `Retarget`.
`MediaElement`	Deprecated alias of `MediaPlayerElement`, kept for compatibility. Use `MediaPlayerElement` instead.
`MediaPlayerElement`	Adds native references where needed to use MediaPlayerElement.
`Mvvm`	Adds support for the CommunityToolkit.Mvvm package.
`MVUX`	Adds support for MVUX. Non-optimized builds also reference `Uno.HotTesting.Reactive`; see MVUX feed mocks.
`Navigation`	Adds support for Navigation using Uno.Extensions.
`Reactor`	Adds Microsoft.UI.Reactor, the declarative, component-based C# UI framework, through the Uno.Microsoft.UI.Reactor package. It runs on the Uno Platform targets only: a project listing it can't target WinAppSDK (see UNOB0031). See Using Reactor.
`Retarget`	Adds Uno.WinUI.Retarget, which runs Windows App SDK / WinUI 3 NuGet packages on Uno Platform by rewriting their Windows builds when the app is built. It also appends the Windows target frameworks to `AssetTargetFallback`, and keeps the Windows App SDK packages out of the restore of the non-Windows target frameworks (`PrunePackageReference`). `MauiEmbedding` implies it.
`Serialization`	Adds support for Serialization using Uno.Extensions.
`SimpleTheme`	Adds support for the Simple Design Theme library. If the `Toolkit` feature is also used, it will add support for the Simple Design Toolkit library.
`Skia`	Adds support for SkiaSharp — the default rendering backend on Uno Platform targets. It is implied on an app's Uno Platform targets when no renderer feature is listed, and the legacy `SkiaRenderer` feature is mapped to it there for backwards compatibility. A library gets neither, because the renderer is the app's choice: a library that draws with SkiaSharp, for example with `SKCanvasElement` or the Uno Toolkit's Skia controls, lists `Skia`. `WebGpu` counts as a renderer feature: listing it without `Skia` leaves SkiaSharp and its native libraries out, so an app that also uses SkiaSharp itself, for example to draw with `SKCanvasElement`, lists both: `Skia;WebGpu`. The WinAppSDK target is not provided by Uno Platform and always renders natively with WinUI, so `Skia` is off there, even when listed, and brings no SkiaSharp packages or native libraries. To use `SKXamlCanvas`, the Uno Toolkit's Skia controls or SkiaSharp itself on Windows, list `Skia` and set `<UnoEnableSkiaOnWinAppSdk>true</UnoEnableSkiaOnWinAppSdk>`. The native libraries' PDBs are left out either way. For more details, see Skia Rendering documentation.
`SpellChecking`	Adds support for spell-checking in TextBox controls on all Skia-based targets via Uno.WinUI.SpellChecking.
`Storage`	Adds support for Storage using Uno.Extensions.
`Svg`	Renders SVG with Svg.Skia, through Uno.WinUI.Svg, instead of the managed SVG engine built into Uno Platform. Applies to apps using the Skia renderer, and has no effect on Windows (WinAppSDK), where the OS renders SVG.
`ThemeService`	Adds the Uno.Extensions.Core.WinUI package.
`Toolkit`	Adds support for the Uno.Toolkit.
`WebGpu`	Adds the WebGPU rendering backend (`Uno.WinUI.Composition.WebGpu`) and the WebGPU Canvas on Uno Platform targets. When both `Skia` and `WebGpu` are listed, both backends are referenced, Skia still renders by default, and the app opts into WebGPU on its host builder. Listing `WebGpu` without `Skia` makes the app SkiaSharp-free (see `Skia` above).
`WebView`	Adds support for the WebView2 control.

Implicit Packages

Uno Platform is composed of many required and optional NuGet packages. By default, the SDK automatically references the Uno.UI required packages based on the current target framework, using versions appropriate for the version of Uno Platform being used.

It is possible to configure the version of those packages in two ways. The first is by using an explicit PackageReference to any of the Uno Platform packages, or by using the *Version properties supported by the SDK. These versions are used by the UnoFeatures defined for your app.

Here are the supported properties:

Uno Platform Packages
Third Party Packages

Property	NuGet Package(s)	Description
`UnoAppMcpVersion`	Uno.UI.App.Mcp	Overrides the version of the Uno App MCP server add-in used by the DevServer.
`UnoCoreLoggingSingletonVersion`	Uno.Core.Extensions.Logging.Singleton	Provides a logging singleton pattern with helpers and extension methods for simplified logging.
`UnoCSharpMarkupVersion`	Uno.WinUI.Markup and similar packages	Enables C# Markup, the use of C# for building UI markup, similar to XAML but with C# syntax.
`UnoDspTasksVersion`	Uno.Dsp.Tasks and similar packages	Includes tasks for Uno DSP (Theme colors import) within Uno Platform projects.
`UnoExtensionsVersion`	Uno.Extensions.Storage.WinUI and similar packages	Extends the Uno Platform with additional methods and classes for more versatile application development.
`UnoFontsVersion`	Uno.Fonts.OpenSans and similar packages	Overrides the version of the bundled Uno.Fonts packages (OpenSans, Fluent, Roboto).
`UnoHotDesignVersion`	Uno.UI.HotDesign	Overrides the version of the Hot Design add-in used by the DevServer.
`UnoLoggingVersion`	Uno.Extensions.Logging.OSLog and similar packages	Implements logging mechanisms to help with monitoring and debugging Uno Platform applications.
`UnoReactorVersion`	Uno.Microsoft.UI.Reactor	Overrides the version of Reactor used by the `Reactor` UnoFeature.
`UnoResizetizerVersion`	Uno.Resizetizer	Provides tools for automatically resizing and managing image assets in Uno Platform projects.
`UnoSdkExtrasVersion`	Uno.Sdk.Extras	Overrides the version of additional Uno.Sdk build-time helper targets.
`UnoSettingsVersion`	Uno.Settings.DevServer	Overrides the version of the Settings add-in used by the DevServer.
`UnoThemesVersion`	Uno.Material.WinUI and similar packages	Supplies a variety of themes that can be applied to Uno Platform applications to enhance the UI.
`UnoToolkitVersion`	Uno.Toolkit.WinUI and similar packages	Offers a collection of controls, helpers, and tools to complement the standard WinUI components.
`UnoWasmBootstrapVersion`	Uno.Wasm.Bootstrap and similar packages	Enables the bootstrapping of Uno Platform applications running on WebAssembly.

Note

In the 5.2 version of the Uno.Sdk you must provide a value for UnoExtensionsVersion, UnoThemesVersion, UnoToolkitVersion, and UnoCSharpMarkupVersion in order to use the packages associated with the UnoFeatures from these libraries as they are downstream dependencies of the Uno repository.

Property	NuGet Package(s)	Description
`AndroidMaterialVersion`	Xamarin.Google.Android.Material	Implements Material Design components for Android using Xamarin bindings.
`AndroidXActivityVersion`	Xamarin.AndroidX.Activity	Provides classes to build Android activities with AndroidX libraries.
`AndroidXAppCompatVersion`	Xamarin.AndroidX.AppCompat	Offers backward-compatible versions of Android components with AndroidX.
`AndroidXBrowserVersion`	Xamarin.AndroidX.Browser	Contains components to implement browser features with AndroidX.
`AndroidXCollectionVersion`	Xamarin.AndroidX.Collection and similar packages	Provides AndroidX extensions for collections like sparse arrays and bundles.
`AndroidXFragmentVersion`	Xamarin.AndroidX.Fragment and similar packages	Provides AndroidX fragments; referenced with MAUI embedding to keep it aligned with Uno's AndroidX packages.
`AndroidXLifecycleVersion`	Xamarin.AndroidX.Lifecycle.LiveData	Provides AndroidX lifecycle-aware data holders; referenced with MAUI embedding to keep it aligned with Uno's AndroidX packages.
`AndroidXSplashScreenVersion`	Xamarin.AndroidX.Core.SplashScreen	Support for Android splash screen customization.
`AndroidXNavigationVersion`	Xamarin.AndroidX.Navigation.UI and similar packages	Facilitates navigation within an Android app using AndroidX.
`AndroidXRecyclerViewVersion`	Xamarin.AndroidX.RecyclerView	Implements a flexible view for providing a limited window into large datasets with AndroidX.
`AndroidXSwipeRefreshLayoutVersion`	Xamarin.AndroidX.SwipeRefreshLayout	Provides a swipe-to-refresh UI pattern with AndroidX.
`AndroidXLeanbackVersion`	Xamarin.AndroidX.Leanback and similar packages	Provides UI components for Android TV applications.
`AndroidXCarAppVersion`	Xamarin.AndroidX.Car.App.App and similar packages	Provides the Android for Cars App Library for building automotive apps.
`AndroidXWearVersion`	Xamarin.AndroidX.Wear and similar packages	Provides support for Wear OS watch applications.
`AndroidXWearTilesVersion`	Xamarin.AndroidX.Wear.Tiles and similar packages	Provides Tiles API for Wear OS watch faces and complications.
`CommunityToolkitMvvmVersion`	CommunityToolkit.Mvvm	Delivers a set of MVVM (Model-View-ViewModel) components for .NET applications.
`MauiVersion`	Microsoft.Maui.Controls and similar packages	Overrides the version of .NET MAUI used by the `mauinativeembedding` UnoFeature, and the default of the `mauiembedding` UnoFeature (`10.0.101`).
`UnoMauiVersion`	Uno.Maui.Handlers and Uno.Maui.Embedding	Overrides the version of the Uno.Maui packages used by the `mauiembedding` UnoFeature.
`MicrosoftIdentityClientVersion`	Microsoft.Identity.Client	Provides an authentication library for Microsoft Identity Platform.
`MicrosoftLoggingVersion`	Microsoft.Extensions.Logging.Console	Enables logging to the console with Microsoft's extensions.
`MicrosoftWebView2Version`	Microsoft.Web.WebView2	Overrides the version of the native WebView2Loader used by the `webview` UnoFeature on desktop.
`UnoRetargetVersion`	Uno.WinUI.Retarget	Overrides the version of Uno.WinUI.Retarget used by the `retarget` UnoFeature.
`SkiaSharpVersion`	SkiaSharp.Skottie and similar packages	Provides a cross-platform 2D graphics API for .NET platforms based on Google's Skia Graphics Library.
`HarfBuzzSharpVersion`	HarfBuzzSharp.NativeAssets.*	The HarfBuzz text-shaping native libraries, referenced for each target.
`SvgSkiaVersion`	Svg.Skia	Renders SVG files using the SkiaSharp graphics engine.
`VlcNativeWindowsAssetsVersion`	VideoLAN.LibVLC.Windows	Overrides the version of the native VLC assets used by `MediaPlayerElement` on Windows desktop.
`WinAppSdkBuildToolsVersion`	Microsoft.Windows.SDK.BuildTools	Contains the tools required to build applications for the Microsoft Windows App SDK.
`WinAppSdkBuildToolsWinAppVersion`	Microsoft.Windows.SDK.BuildTools.WinApp	Enables `dotnet run` to launch the packaged WinAppSDK app with package identity. See Running packaged WinUI apps with `dotnet run`.
`WinAppSdkVersion`	Microsoft.WindowsAppSDK	Provides project templates and tools for building Windows applications.

Those properties can be set from Directory.Build.props or may be set in the csproj file for your project.

<!-- .csproj file -->
<Project Sdk="Uno.Sdk">
  <PropertyGroup>

      ...

      <UnoFeatures>
        Material;
        Dsp;
        Hosting;
        Toolkit;
        Logging;
        MVUX;
        Configuration;
        Http;
        Serialization;
        Localization;
        Navigation;
        ThemeService;
        Mvvm;
      </UnoFeatures>
      
      <UnoToolkitVersion>6.3.6</UnoToolkitVersion>
      <MicrosoftLoggingVersion>9.0.1</MicrosoftLoggingVersion>
      <CommunityToolkitMvvmVersion>8.4.0</CommunityToolkitMvvmVersion>
  </PropertyGroup>    
</Project>

In the sample above, we are overriding the default versions of the UnoToolkit, MicrosoftLogging, and CommunityToolkitMvvm packages.

Using Central Package Management with implicit packages

Uno Platform templates use NuGet Central Package Management (CPM) by default: package versions live in a Directory.Packages.props file at the root of the repository, and <PackageReference> items in project files carry no Version attribute.

CPM and the Uno.Sdk implicit packages coexist automatically:

The SDK keeps managing the versions of its implicit packages (based on the Uno Platform version from global.json and the *Version properties above).
If your Directory.Packages.props contains a <PackageVersion> entry for a package the SDK already references implicitly, the SDK removes that central entry during restore, so it cannot conflict with the SDK-managed version. To change the version of an implicit package, use the matching *Version property or take over the package with an explicit reference (see below) — a lone <PackageVersion> entry has no effect.
If your project declares its own <PackageReference> for a package the SDK would otherwise add implicitly — versioned centrally, via Version, or via VersionOverride — the SDK backs off and your reference wins.

A typical Directory.Packages.props only needs entries for the packages you add — implicit packages need none:

<Project ToolsVersion="15.0">
  <PropertyGroup>
    <ManagePackageVersionsCentrally>true</ManagePackageVersionsCentrally>
  </PropertyGroup>
  <ItemGroup>
    <!-- Your own dependencies -->
    <PackageVersion Include="AutoMapper" Version="13.0.1" />
    <PackageVersion Include="FluentValidation" Version="11.9.0" />
    <!-- Takes over an otherwise-implicit package (requires a matching
         PackageReference in the project file) -->
    <PackageVersion Include="CommunityToolkit.Mvvm" Version="8.4.0" />
  </ItemGroup>
</Project>

Overriding the version of a single package

Under CPM, the standard NuGet VersionOverride metadata overrides the centrally-defined version for one project, and is honored by the Uno.Sdk when deciding whether to back off from an implicit package:

<ItemGroup>
  <PackageReference Include="CommunityToolkit.Mvvm" VersionOverride="8.3.2" />
</ItemGroup>

For Uno-managed packages, prefer the *Version MSBuild properties documented above (UnoToolkitVersion, CommunityToolkitMvvmVersion, …) — they adjust the implicit reference itself, without needing a PackageReference/PackageVersion pair.

Per-TargetFramework package versions

A single <PackageVersion> entry cannot express different versions per target framework, but Directory.Packages.props is evaluated once per target framework, so conditional item groups work:

<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
  <PackageVersion Include="CommunityToolkit.WinUI.UI.Controls" Version="7.1.2" />
</ItemGroup>
<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'windows'">
  <PackageVersion Include="Uno.CommunityToolkit.WinUI.UI.Controls" Version="7.1.200" />
</ItemGroup>

The same pattern works with a Choose/When block, as shown in Supported OS Platform versions.

NuGet audit

Implicit packages are turned into ordinary <PackageReference> items before restore runs, so NuGet audit evaluates them exactly like packages you reference yourself: known vulnerabilities in implicit packages are reported as direct-dependency warnings, and NuGetAudit* properties apply to them as usual.

Disabling Implicit Uno Packages

If you wish to disable Implicit package usage, add the following:

<DisableImplicitUnoPackages>true</DisableImplicitUnoPackages>

to your Directory.Build.props file or csproj file. You will be then able to manually add the NuGet packages for your project.

Note

When disabling Implicit Uno Packages it is recommended that you use the $(UnoVersion) to set the version of the core Uno packages that are versioned with the SDK as the SDK requires Uno.WinUI to be the same version as the SDK to ensure proper compatibility.

For the narrower scenario of a library that is essentially a WinUI library that also happens to support Uno cross-targets — and that should not leak Uno.WinUI to WinAppSDK-only consumers, or needs a strong-named output on Windows — see the WinAppSDK-only libraries section below.

WinAppSDK-only libraries

When you author a library that is only a WinUI library on the Windows App SDK target (and uses the rest of the Uno.Sdk solely for cross-platform target frameworks), you may want the Windows build to contain no implicit Uno dependencies. Two common motivations:

Avoid leaking Uno.WinUI as a transitive NuGet dependency to consumers that only target the Windows App SDK.
Compile to a strong-named assembly on Windows for scenarios that require a fully strong-named dependency chain (organizational policy, certain hosts, or downstream consumers that only accept strong-named references). Uno.WinUI is not strong-named, so leaving it as an implicit reference would block those scenarios.

Enable this with:

<DisableImplicitUnoWinAppSdkPackages>true</DisableImplicitUnoWinAppSdkPackages>

When set, Uno.Sdk stops adding the following implicit package references on the net*-windows10* target framework:

Uno.WinUI (also removes the Uno Platform extension APIs it bundles under lib/net*-windows10.0.19041.0/)
Uno.Resizetizer
Uno.Sdk.Extras
Uno.Settings.DevServer

The property is intentionally scoped:

It only takes effect on the Windows App SDK target framework. Other targets (Android, iOS, Skia Desktop, WebAssembly, …) are unaffected, so the cross-platform side of your library still uses Uno.WinUI and the rest of the Uno stack.
Packages added through UnoFeatures (Toolkit, Material, Cupertino, Simple, csharpmarkup, maps, foldable, skia/Graphics2DSK, glcanvas, mvvm, dsp, Uno.Extensions.*, …) are not stripped. Opting into a UnoFeatures value is treated as an explicit request for that package, even when this property is set.
Non-Uno implicit packages (Microsoft.WindowsAppSDK, Microsoft.Windows.SDK.BuildTools, CommunityToolkit.Mvvm, SkiaSharp.Views.WinUI, …) keep flowing as usual.

If you still need one of the stripped packages on Windows for a specific reason, add it back explicitly:

<ItemGroup Condition="$(TargetFramework.Contains('windows10'))">
    <PackageReference Include="Uno.Resizetizer" Version="$(UnoResizetizerVersion)" PrivateAssets="all" />
</ItemGroup>

Note

This property is aimed at libraries (IsPackable=true). Application heads typically need the implicit Uno packages on Windows to run, so setting this on a head project is not recommended.

MVUX feed mocks in non-optimized builds

When UnoFeatures includes MVUX, the Uno.Sdk also references Uno.HotTesting.Reactive in builds where Optimize is not true (Debug, by default). The package provides MVUX feed mocks for previews and UI tests, and is meant to stay out of published apps:

It is absent from optimized (Release) builds. Code that uses its types must only compile in non-optimized builds, for example under #if DEBUG, or the Release build fails.
It is referenced with PrivateAssets="all", so it does not flow to projects that reference yours, nor into the package of a library packed in Debug. A test project that doesn't use the MVUX feature references it directly, at the same version as the app's Uno.Extensions packages.
It follows UnoExtensionsVersion, and is skipped (UNOB0028) when that version is older than the 7.4 builds that first ship it, or is a floating version or a range.
Debug and Release restore different packages. Restore the configuration you build before any --no-restore build, and if you use RestoreLockedMode, give each configuration its own lock file, e.g. <NuGetLockFilePath>packages.$(Configuration).lock.json</NuGetLockFilePath>.

To turn the implicit reference off:

<PropertyGroup>
  <UnoDisableHotTesting>true</UnoDisableHotTesting>
</PropertyGroup>

Running packaged WinUI apps with `dotnet run`

On the Windows App SDK target, the Uno.Sdk implicitly references the Microsoft.Windows.SDK.BuildTools.WinApp package for executable (application head) projects. This package overrides the dotnet run behavior so that, instead of launching the raw executable, it registers a loose-layout package and launches the app with package identity — matching the experience of the dotnet new templates for WinUI. This means features that require package identity (such as notifications, app data, or ApplicationData) work the same way they do when the app is deployed from its MSIX package.

The package is referenced with PrivateAssets="all", so it does not flow to consumers of your project. It is only added to executable heads — libraries never pull it in.

You can control this behavior with the following properties:

Property	Default	Effect
`EnableWinAppRunSupport`	`true`	Set to `false` to keep the package reference but disable the `dotnet run` interception (the app then launches as a plain executable, without package identity).
`UnoDisableWinAppRunSupport`	`false`	Set to `true` to suppress the implicit `Microsoft.Windows.SDK.BuildTools.WinApp` reference entirely, so the package is never restored.
`WinAppSdkBuildToolsWinAppVersion`	(SDK-managed)	Overrides the version of the `Microsoft.Windows.SDK.BuildTools.WinApp` package.

For example, to turn the feature off while still restoring the package (useful if you set it conditionally), add to your csproj or Directory.Build.props:

<PropertyGroup>
  <EnableWinAppRunSupport>false</EnableWinAppRunSupport>
</PropertyGroup>

Or, to avoid restoring the package altogether:

<PropertyGroup>
  <UnoDisableWinAppRunSupport>true</UnoDisableWinAppRunSupport>
</PropertyGroup>

Note

EnableWinAppRunSupport is provided by the Microsoft.Windows.SDK.BuildTools.WinApp package itself, so it also works when you add the package explicitly. UnoDisableWinAppRunSupport is specific to the Uno.Sdk and only affects the implicit reference.

Supported OS Platform versions

By default, the Uno.Sdk specifies a set of OS Platform versions, as follows:

Target	`SupportedOSPlatformVersion`
Android	24 (26 when the `AndroidWear` feature is used)
iOS	15.0
tvOS	15.0
WinUI	10.0.19041.0

You can set this property in a Choose MSBuild block in order to alter its value based on the active TargetFramework.

 <Choose>
    <When Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">
      <PropertyGroup>
        <SupportedOSPlatformVersion>24.0</SupportedOSPlatformVersion>
      </PropertyGroup>
    </When>
    <When Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">
      <PropertyGroup>
        <SupportedOSPlatformVersion>15.0</SupportedOSPlatformVersion>
      </PropertyGroup>
    </When>
    <When Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'tvOS'">
      <PropertyGroup>
        <SupportedOSPlatformVersion>15.0</SupportedOSPlatformVersion>
      </PropertyGroup>
    </When>
    <When Condition="$(TargetFramework.Contains('windows10'))">
      <PropertyGroup>
        <SupportedOSPlatformVersion>10.0.19041.0</SupportedOSPlatformVersion>
        <TargetPlatformMinVersion>10.0.19041.0</TargetPlatformMinVersion>
      </PropertyGroup>
    </When>
  </Choose>

Visual Studio First-TargetFramework Workarounds

Using a Single Project in Visual Studio requires the Uno Platform tooling to apply a workaround in order to have an acceptable debugging experience.

When building inside Visual Studio, an issue prevents debugging and Hot Reload from working properly for all targets when browserwasm is the active launch target but is not first in the TargetFrameworks property. To work around this, the Uno Platform tooling swaps the active target framework into the first position of TargetFrameworks whenever it is browserwasm.

This reorder is applied in-memory during MSBuild evaluation only — the .csproj file on disk is never modified. If the behavior is impacting your IDE negatively, you can disable it by adding the following in your .csproj file:

<PropertyGroup>
  <UnoDisableFirstTargetFrameworkRewrite>true</UnoDisableFirstTargetFrameworkRewrite>
</PropertyGroup>

Note that we are currently tracking these Visual Studio issues, make sure to upvote them:

net10.0-browserwasm must be first for WebAssembly debugging to work (Link)
WinAppSDK Unpackaged profile cannot be selected properly when a net10.0 mobile target is active

Disabling Default Items

The Uno.Sdk will automatically includes files that you previously needed to manage within your projects. These default items include definitions for including files within the Content, Page, and PRIResource item groups. Additionally, if you have referenced the Uno.Resizetizer it will add default items for the UnoImage allowing you to more easily manage your image assets.

You may disable this behavior in one of two ways:

<PropertyGroup>
  <!-- Globally disable all default includes from the `Uno.Sdk`, `Microsoft.NET.Sdk`, and if building on WASM `Microsoft.NET.Sdk.Web` -->
  <EnableDefaultItems>false</EnableDefaultItems>

  <!-- Disable only default items provided by the `Uno.Sdk` -->
  <EnableDefaultUnoItems>false</EnableDefaultUnoItems>
</PropertyGroup>

WinAppSdk PRIResource Workaround

Many Uno projects and libraries make use of a winappsdk-workaround.targets file that corrects a bug found in WinUI. When using the Uno.Sdk these targets now are provided for you out of the box. This extra set of workaround targets can be disabled by setting the following property:

<PropertyGroup>
  <DisableWinUI8857_Workaround>true</DisableWinUI8857_Workaround>
</PropertyGroup>

Cross Targeting Support

By Default when using the Uno.Sdk you get the added benefit of default includes for an easier time building Cross Targeted Applications. A file carrying one of the suffixes below is compiled only for the target frameworks it names, in class libraries and application heads alike:

Suffix	Compiled for
`*.Android.cs`	`netX.0-android`
`*.iOS.cs`	`netX.0-ios`
`*.tvOS.cs`	`netX.0-tvos`
`*.UIKit.cs`	`netX.0-ios` and `netX.0-tvos`
`*.desktop.cs`	`netX.0-desktop`
`.wasm.cs`, `.browserwasm.cs`	`netX.0-browserwasm`
`*.WinAppSDK.cs`	`netX.0-windows10.x`
`.crossruntime.cs`, `.skia.cs`	every target framework except `netX.0-windows10.x`

*.crossruntime.cs and *.skia.cs are equivalent, and hold code for the targets Uno Platform renders itself as opposed to the WinAppSDK one. Neither names a drawing backend: Uno.UI is compiled once and resolves its backend at run time.

Note

Before Uno Platform 7.0, *.skia.cs and *.crossruntime.cs were compiled only for netX.0-desktop, which made *.skia.cs an alias of *.desktop.cs. A file that is genuinely desktop-only should be renamed to *.desktop.cs.

Note

*.reference.cs, *.iOSmacOS.cs and *.Apple.cs are no longer recognized. *.reference.cs and *.iOSmacOS.cs named build flavors that no longer exist and can be removed; rename *.Apple.cs to *.UIKit.cs, which always had the identical rule.

As discussed above setting EnableDefaultUnoItems to false will disable these includes.

Tip

When you need to exclude specific files from a particular target framework (such as WebAssembly), you can use a custom MSBuild target:

<Target Name="AdjustAppItemGroups" BeforeTargets="ResolveAssemblyReferences">
    <ItemGroup Condition="'$(TargetFramework)' == 'net10.0-browserwasm'">
        <None Remove="Page.xaml"/>
        <Page Remove="Page.xaml"/>
    </ItemGroup>
</Target>

This approach allows you to selectively remove pages from specific target frameworks while maintaining them in others.

Platform-Specific Folders

In addition to the per-file suffixes described above, the Uno.Sdk recognizes a set of well-known sub-folders under Platforms/ that scope their contents to a single target. Files in these folders are automatically included only when the matching TFM is being built and excluded from every other TFM (the SDK removes them from Compile, Page, Content, EmbeddedResource, and Manifest for inactive platforms).

Folder	TFM it applies to	Typical contents
`Platforms/Android/`	`*-android`	`Main.Android.cs`, `AndroidManifest.xml`, Android resources
`Platforms/iOS/`	`*-ios`	`Main.iOS.cs`, `Info.plist`, `Entitlements.plist`, `PrivacyInfo.xcprivacy`
`Platforms/tvOS/`	`*-tvos`	tvOS-specific entry point and resources
`Platforms/Desktop/`	`*-desktop`	`Program.cs` with the `UnoPlatformHostBuilder` configuration
`Platforms/Wasm/` (or `Platforms/WebAssembly/`)	`*-browserwasm`	`Program.cs`, `wwwroot/`, `manifest.webmanifest`
`Platforms/Windows/`	`-windows10.`	`Package.appxmanifest`, `app.manifest`, splash screens, tile/app-icon PNGs referenced by the manifest

The location of each folder can be overridden via the matching MSBuild property if your project uses a different layout: PlatformsProjectFolder, AndroidProjectFolder, iOSProjectFolder, tvOSProjectFolder, DesktopProjectFolder, WasmProjectFolder, WindowsProjectFolder.

High Refresh Rate on iPhone

iPhones with ProMotion displays only render above 60 Hz when the app's Info.plist sets CADisableMinimumFrameDurationOnPhone to true. For projects using the Uno.Sdk, this key is added automatically, so animations and scrolling can run at up to 120 Hz on those devices. iPads are not affected: they use their display's full refresh rate without this key.

A value set explicitly in your own Platforms/iOS/Info.plist takes precedence. To keep iPhones at 60 Hz, for example to reduce power use, disable it in your project file:

<PropertyGroup>
  <UnoDisableHighRefreshRate>true</UnoDisableHighRefreshRate>
</PropertyGroup>

Apple Privacy Manifest Support

Starting May 1st, 2024, Apple requires the inclusion of a new file, the Privacy Manifest file (named PrivacyInfo.xcprivacy), in app bundles. This file is crucial for complying with updated privacy regulations.

For projects using the Uno.Sdk (version 5.2 or later), the Platforms/iOS/PrivacyInfo.xcprivacy file is automatically integrated within the app bundle. An example of this manifest file can be found in the Uno.Templates repository.

For more information on how to include privacy entries in this file, see the Microsoft .NET documentation on the subject, as well as Apple's documentation.

Note

If your application is using the Uno Platform 5.1 or earlier, or is not using the Uno.Sdk, you can include the file using the following:

 <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">
   <BundleResource Include="iOS\PrivacyInfo.xcprivacy" LogicalName="PrivacyInfo.xcprivacy" />
 </ItemGroup>

Using the Uno.Sdk

Tip

Managing the Uno.Sdk version

Solution-less projects and .slnx solutions

Important

Using the .slnx solution format

Uno Platform Features

Important

Implicit Packages

Note

Using Central Package Management with implicit packages

Overriding the version of a single package

Per-TargetFramework package versions

NuGet audit

Disabling Implicit Uno Packages

Note

WinAppSDK-only libraries

Note

MVUX feed mocks in non-optimized builds

Running packaged WinUI apps with dotnet run

Note

Supported OS Platform versions

Visual Studio First-TargetFramework Workarounds

Disabling Default Items

WinAppSdk PRIResource Workaround

Cross Targeting Support

Note

Note

Tip

Platform-Specific Folders

High Refresh Rate on iPhone

Apple Privacy Manifest Support

Note

Solution-less projects and `.slnx` solutions

Using the `.slnx` solution format

Running packaged WinUI apps with `dotnet run`