| uid |
|---|
Uno.Contributing.Overview |
This article explores how Uno works in detail, with a focus on information that's useful for contributors to Uno.
Uno Platform is a cross-platform projection of Microsoft's WinUI framework (and its preview iteration, UWP). Uno mirrors WinUI/UWP types and supports the WinUI/UWP XAML dialect, as well as handling several additional aspects of the app contract like assets and string resources. Thus, it allows app code written for UWP to be built and run on Android, iOS, mac Catalyst, in the browser via WebAssembly, Linux, and on macOS.
Note
While UWP supports authoring app code in C++ as well as C#, Uno Platform only supports C#.
Broadly then, Uno Platform has two jobs to do:
- Duplicate the types provided by WinUI, including views in the
Microsoft.UI.Xamlnamespace, and non-UI APIs such asWindows.Foundation,Windows.Storage, etc... - Perform compile-time tasks related to non-C# aspects of the WinUI app contract (parse XAML files, process assets to platform-specific formats, etc)
Like WinUI, Uno Platform provides access to the existing .NET libraries, via .NET.
Uno Platform aims to be a 1:1 match for WinUI (and UWP), in API surface (types, properties, methods, events, etc...), in appearance, and in behavior. At the same time, Uno Platform places an emphasis on native interoperability and making it easy to intermix purely native views with Uno/UWP controls in the visual tree.
Certain aspects of the framework are not tied in any way to the platform that Uno happens to be running on. These include support for the DependencyProperty system and data-binding, and style and resource resolution. The code that implements these features is fully shared across all platforms.
Other parts of the framework are implemented using a mix of shared and platform-specific code, such as view types (ie types inheriting from UIElement). There is a tendency for high-level controls, which are typically built by composition of simpler visual primitives, to be implemented mainly by shared code - NavigationView is a good example. The primitives themselves, such as TextBlock, Image, or Shape, contain a much higher proportion of platform-specific code as they need to call into per-platform rendering APIs.
The layouting system is implemented in shared code as much as possible, for cross-platform consistency; however it's nonetheless tied into the underlying native layout cycle on each platform.
APIs for non-UI features, for example Windows.System.Power or Windows.Devices.Sensors, incorporate a large fraction of platform-specific code to interact with the associated native APIs.
WinUI has a very large API surface area, and not all features in it have been implemented by Uno Platform. We want pre-existing WinUI (and UWP) apps and libraries that reference these features to still be able to at least compile on Uno Platform. To support this, an internal automated tool inspects the UWP framework, compares it to authored code in Uno Platform, and generates stubs for all types and type members that exist in UWP but are not implemented on Uno. For example:
#if __ANDROID__ || __IOS__ || IS_UNIT_TESTS || __WASM__ || __MACOS__
[global::Uno.NotImplemented]
public bool ExitDisplayModeOnAccessKeyInvoked
{
get
{
return (bool)this.GetValue(ExitDisplayModeOnAccessKeyInvokedProperty);
}
set
{
this.SetValue(ExitDisplayModeOnAccessKeyInvokedProperty, value);
}
}
#endifNotice the platform conditionals, since a member may be implemented for some platforms but not others. The [NotImplemented] attribute flags this property as not implemented and a code analyzer surfaces a warning if it is referenced in app code.
For more details on how Uno Platform runs on each platform, see platform-specific information for:
This is the most substantial compile-time task that Uno Platform carries out. Whenever an app or class library is built, all contained XAML files are parsed and converted to C# files, which are then compiled in the usual way. (Note that this differs from WinUI, which parses XAML to XAML Binary Format (.xbf) files which are processed by the WinUI runtime.)
Uno Platform uses existing libraries to parse a given XAML file into a XAML object tree, then Uno-specific code is responsible for interpreting the XAML object tree as a tree of visual elements and their properties. Most of this takes place within the XamlFileGenerator class.
On Android, iOS, and macOS, UIElement (the base view type in UWP/WinUI) inherits from the native view class on the respective platform. This poses a challenge because UIElement inherits from the DependencyObject class in UWP/WinUI, which is a key part of the dependency property system. Uno makes this work by breaking from UWP/WinUI and having DependencyObject be an interface rather than a type.
Class library authors and app authors sometimes inherit directly from DependencyObject rather than a more derived type. To support this scenario seamlessly, the DependencyObjectGenerator task looks for such classes and generates a partial implementation for the DependencyObject interface, ie the methods that on UWP would be inherited from the base class.
Different platforms have different requirements for where bundled image files are located and how multiple versions of the same asset are handled (eg, to target different resolutions). The asset retargeting task copies the image assets located in the shared project to the appropriate location and format for the target platform.
As with images, different platforms have different requirements for location and formatting of localized string resources. The ResourcesGenerationTask reads the strings defined in UWP's *.resw files in the shared project, and generates the appropriate platform-specific file.