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.

Note

The Uno.Sdk only supports the WinUI API set.

Tip

Beginning with 5.2, Uno.Sdk enabled projects are best experienced using the MSBuild Editor Visual Studio 2022 Extension to provide intellisense.

Managing the Uno.Sdk version

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

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;
    Serilog;
    MVUX;
    Configuration;
    Http;
    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
Foldable Adds a reference to Uno.WinUI.Foldable.
MediaElement Adds native references where needed to use MediaElement.
CSharpMarkup Adds support for C# Markup.
Extensions Adds the most commonly used Extensions Packages for Hosting, Configuration, and Logging.
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.
Hosting Adds support for Dependency Injection using Uno.Extensions.Hosting packages.
Http Adds support for custom Http Clients including the use of Refit with Uno.Extensions.
Localization Adds support for Localization using Uno.Extensions.
Logging Adds support for Logging using Uno.Extensions.
MauiEmbedding Adds support for embedding Maui controls in Uno Platform applications.
MVUX Adds support for MVUX.
ThemeService Adds the Uno.Extensions.Core.WinUI package.
Navigation Adds support for Navigation using Uno.Extensions.
LoggingSerilog Adds support for Serilog using Uno.Extensions.
Storage Adds support for Storage using Uno.Extensions.
Serialization Adds support for Serialization using Uno.Extensions.
Toolkit Adds support for the Uno.Toolkit.
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.
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.
Mvvm Adds support for the CommunityToolkit.Mvvm package.
Dsp Adds support for the Uno.Dsp.Tasks packages.
Prism Adds Prism support for Uno Platform applications WinUI.
Skia Adds support for SkiaSharp.
Svg SVG support for iOS, Android, and Mac Catalyst. This option is not needed when only targeting WebAssembly and WinAppSDK.
Lottie Adds support for Lottie animations.

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:

Property NuGet Package(s) Description
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.
UnoLoggingVersion Uno.Extensions.Logging.OSLog and similar packages Implements logging mechanisms to help with monitoring and debugging Uno Platform applications.
UnoResizetizerVersion Uno.Resizetizer Provides tools for automatically resizing and managing image assets in Uno Platform projects.
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.
UnoUniversalImageLoaderVersion Uno.UniversalImageLoader Facilitates the loading and displaying of images across different platforms supported by Uno.
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.

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

If you wish to disable Implicit package usage, add <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.

Supported OS Platform versions

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

Target SupportedOSPlatformVersion
Android 21
iOS 14.2
macOS 10.14
MacCatalyst 14.0
WinUI 10.0.18362.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>21.0</SupportedOSPlatformVersion>
      </PropertyGroup>
    </When>
    <When Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">
      <PropertyGroup>
        <SupportedOSPlatformVersion>14.2</SupportedOSPlatformVersion>
      </PropertyGroup>
    </When>
    <When Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'macos'">
      <PropertyGroup>
        <SupportedOSPlatformVersion>10.14</SupportedOSPlatformVersion>
      </PropertyGroup>
    </When>
    <When Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'maccatalyst'">
      <PropertyGroup>
        <SupportedOSPlatformVersion>14.0</SupportedOSPlatformVersion>
      </PropertyGroup>
    </When>
    <When Condition="$(TargetFramework.Contains('windows10'))">
      <PropertyGroup>
        <SupportedOSPlatformVersion>10.0.18362.0</SupportedOSPlatformVersion>
        <TargetPlatformMinVersion>10.0.18362.0</TargetPlatformMinVersion>
      </PropertyGroup>
    </When>
  </Choose>

Visual Studio 2022 First-TargetFramework workarounds

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

For some of the platforms (Desktop, WinAppSDK, and WebAssembly), the corresponding target frameworks must be placed first in order for debugging and publishing to function properly. To address that problem, the Uno Platform tooling modifies the csproj file to reorder the TargetFrameworks property so that the list is accepted by Visual Studio.

As a result, the csproj file is on disk and will show the file as modified in your source control, yet the automatic change can be reverted safely. If the behavior is impacting your IDE negatively, you can disable it by adding the following in your .csproj file:

<PropertyGroup>
  <UnoDisableVSTargetFrameworksRewrite>true</UnoDisableVSTargetFrameworksRewrite>
</PropertyGroup>

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

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. The supported file extensions are as shown below:

  • *.crossruntime.cs (WASM, Skia, or Reference)
  • *.wasm.cs
  • *.skia.cs
  • *.reference.cs
  • *.iOS.cs(iOS & MacCatalyst)
  • *.macOS.cs (MacOS not MacCatalyst)
  • *.iOSmacOS.cs (iOS, MacCatalyst, & MacOS)
  • *.Android.cs

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

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>