The Uno Platform Solution Template

Solution Structure

Both the Visual Studio Template Wizard, which comes with the Uno Platform Visual Studio extension, and the dotnet new unoapp template create a Uno Platform application with the same solution structure. In this guide, we'll explain the different options that can be used to configure the solution that gets generated. The options will be discussed in the groups they appear in the wizard.

Preset selection

Preset

The unoapp template comes with two preset options: Blank and Recommended (Default in Visual Studio Wizard). These represent two different sets of pre-configured values for the options that follow. The Blank option is the most minimal template, while the Recommended option comes with a few more features pre-configured.

Both presets include the following platforms: Windows, Android, iOS, Mac Catalyst, Desktop, and Wasm.

  • Blank

    The Blank preset option represents the simplest Uno Platform application. Think of this as the "Hello World" of Uno Platform applications. The application has a single page, with a single TextBlock. The only additional package reference it includes is to Uno.Resizetizer, which is used to make it easy define the application icon and splash screen for all target platforms.

    Create an application with the Blank preset:

    dotnet new unoapp -preset blank

    The Blank preset can be augmented by clicking Customize in the Visual Studio Wizard, or by specifying additional command line parameters to the dotnet new command. For example, this command will create a Blank application with the Uno.Toolkit.

    dotnet new unoapp -preset blank -toolkit

  • The Recommended preset option represents a more complete Uno Platform application. It uses Uno.Extensions to initialize the application by creating an IHost, using the IHostBuilder pattern established by the Microsoft.Extensions libraries. The IHost provides a number of services that are useful in Uno Platform applications, including Dependency Injection, Logging, and Configuration.

    The Recommended option also includes a number of additional packages that are useful in Uno Platform applications, including Uno.UITest, Uno.Extensions.Http, Uno.Extensions.Navigation, Uno.Extensions.Serialization, and Uno.Extensions.Logging.

    Create an application with the Recommended preset:

    dotnet new unoapp -preset recommended

    The Recommended preset can be augmented by clicking Customize in the Visual Studio Wizard, or by specifying additional command line parameters to the dotnet new command. For example, this command will create a Blank application with out the Uno.Toolkit.

    dotnet new unoapp -preset blank -toolkit false

For each of the options that follow, we'll define the values that are set for each preset option.

1. Framework

This setting lets you choose the .NET version to target. The default is .NET 8.0, but you can change it to .NET 7.0!

  • .NET 8.0

    .NET 8.0 is provided as a LTS (Long Term Support) version. This version adds significant performance improvements, as well as other general enhancements. This is the default (for both blank and recommended presets) and the recommended option for new projects

    dotnet new unoapp -tfm 8.0

  • .NET 9.0 Preview

    .NET 9.0 is provided as an STS (Standard Term Support) version. This is a preview version to be released at the end of 2024.

    dotnet new unoapp -tfm 9.0

2. Platforms

This setting lets you choose which platforms the generated app will target.

Uno Platform currently supports targeting the following operating systems:

  • Mobile
    • Android
    • iOS
  • Web
    • WebAssembly (wasm)
  • Desktop
    • Mac (Mac Catalyst)
    • Windows App SDK
    • Skia Desktop (Linux X11, Linux Framebuffer, Windows, macOS)
Note

For most platforms the name of the command line argument is just the platform name (eg windows or ios). However, for WebAssembly and Mac, use the abbreviation in braces in the above list (i.e. wasm, maccatalyst).

By default, when you create a new Uno Platform app, it will target the following platforms: Windows App SDK, iOS, Android, Mac Catalyst, and Skia Desktop.

The following command only selects the Windows platform:

dotnet new unoapp -platforms windows

To select multiple platforms, the platforms argument should be supplied multiple times. In the following example, the generated app will target Windows, Android and iOS:

dotnet new unoapp -platforms windows -platforms android -platforms ios

3. Presentation

This setting allows you to choose a presentation architecture.

  • None

    Generates a project without any presentation architecture installed. This is the default for the blank preset.

  • MVVM

    Generates a project optimized for use with the traditional MVVM architecture, using Microsoft's MVVM Community Toolkit.

    dotnet new unoapp -presentation mvvm

  • MVUX

    The Model View Update eXtended (MVUX) pattern is a new programming architecture by Uno Platform. This is the default for the recommended preset.

    Its main feature is enabling the use of immutable POCO entities and Models (using records) as the presentation layer, making the whole need for implementing property change notification redundant.

    To learn more about the MVUX pattern, read this.

    dotnet new unoapp -presentation mvux

4. Markup

This setting allows you to choose the markup to use for declaring the UI of the application.

  • XAML

    Use XAML for the declaration of UI. This is the default for both the blank and recommended preset

    dotnet new unoapp -markup xaml

  • C# Markup

    Use C# Markup for the declaration of UI.

    dotnet new unoapp -markup csharp

5. Theme

Uno platform lets you decide easily which theme or skin to display throughout your app.

This option sets the generated theme or skin to be used in the generated app. The options available are:

  • Material
    Material is Google's design system.
    Learn more about Material. This option will result in an application that will have the material theme applied. This is the default for the recommended preset.

    dotnet new unoapp -theme material

  • Fluent
    Fluent is an open-source design system that drives Windows and WinUI's default style.
    Learn more about Fluent Design System. This is the default for the blank preset.

    dotnet new unoapp -theme fluent

The theme in the application can be further customized with the following options:

Theme Service

Includes references to the Uno.Extensions.Core.WinUI package which includes the theme service that can be used to control the theme (Dark, Light or System) of the application. This is included by default in the recommended preset, but not in the blank preset.

dotnet new unoapp -theme-Service

Import Theme File (Uno.Dsp)

Allows colors in the application to be overridden using a theme file (Material theme only). This is included by default in the recommended preset, but not in the blank preset.

dotnet new unoapp -dsp

6. Extensions

The settings on the Extensions page let you configure which Uno Extensions should be added to the solution and projects generated by the wizard.

Uno Extensions is a set of Extensions that cover common essentials application core building blocks and are supported on all operating systems Uno Platform targets.
Uno.Extensions follow the Microsoft.Extensions model that creates a host environment where you can register additional dependencies. The registered dependencies are then available throughout the application via the Services (IServiceProvider) property on the IHost instance.

The available extensions are:

Dependency Injection

Dependency Injection (DI) is an Inversion of Control (IoC) technique that enables consuming classes not to worry about the management or creation of their dependencies and instead rely on a central service to provide it when needed, based on how the provider was configured.

Uno Platform brings the power of Microsoft Extensions Dependency Injection to all OSs Uno Platform targets and adds its additional functionality via its Uno.Extensions.DependencyInjection library, which you can learn more about here.

This is included by default in the recommended preset, but not in the blank preset.

Note

Some other features (e.g. Configuration, Http, Authentication as well as others) depend on DI and will be disabled if DI is not enabled.

dotnet new unoapp -di

Configuration

This extension provides a way to load application configuration data from and to various sources using the Options Pattern. This is included by default in the recommended preset, but not in the blank preset.

Refer to the Uno Configuration documentation for more information.

dotnet new unoapp -config

HTTP

Uno.Extensions.Http allows for the registration of API endpoints as multiple typed HttpClient instances. In this centralized location for accessing web resources, the lifecycle of the corresponding HttpMessageHandler objects is managed. Added clients can optionally be configured to use the platform-native handler. Additional functionality is provided to clear cookies or log diagnostic messages in responses. This library uses Microsoft.Extensions.Http for any HTTP-related work. This is included by default in the recommended preset, but not in the blank preset.

For more documentation on HTTP requests, read the documentation.

Refer to the documentation to learn how to use it in an Uno Platform app.

dotnet new unoapp -http

Localization

The Localization extension is responsible for managing globalization in your app.
This enables keeping all translations of your app in a single place and enables the user to easily switch the UI language.

The generated app contains resw files which can be used to define the application strings. The defined languages are configured in appsettings.json. Follow this link to learn how to switch the UI culture.

Visual Studio Solution Explorer showing localization files

The default settings come with the following pre-set languages: English (en), Spanish (es), French (fr), and Portuguese - Brazil (pt-BR).

Uno.Extensions.Localization expands Microsoft.Extensions.Localization to all OSs supported by Uno Platform.

This is included by default in the recommended preset, but not in the blank preset.

Read the full Localization documentation here or learn more about Globalization.

dotnet new unoapp -loc
  • Regions

    Navigation is an integral part of any app and for that, Uno Platform has developed a navigation system that is registered and served using DI and is fully integrated with the navigation-specific UI controls out there, such as Frame, NavigationView, and TabBar.

    It is a region-based navigation. A Region is the abstraction of the view responsible for handling navigation. Regions are structured into a logical hierarchical representation that shadows the navigation-aware controls in the visual hierarchy. The hierarchy allows navigation requests to be propagated up to the parent and down to child regions as required.
    This library is also responsible for showing pop-ups, flyouts, dialogs, and other interactions with the user.

    This is the default navigation in the recommended preset.

    Learn more about Uno's Navigation library here.

    dotnet new unoapp -nav regions
  • Blank

    Provides the default WinUI frame navigation. This is the default navigation in the blank preset.

    dotnet new unoapp -nav blank

Logging

Logging is a crucial component in an app that enables the developer to emit log messages whenever an important action or execution is taken by the app. This then lets you trace back any errors or issues that may arise in the future. There are several Logging tools out there, with one of the most common of them being Microsoft.Extensions.Logging.

Uno Platform provides its Uno.Extensions.Logging to bring Logging to all platforms it supports.

Uno.Extensions.Logging is covered in more detail here.

  • Console

    Generates an app configured to write debug-level logging information to the Console. This is the default logging in the blank preset.

    dotnet new unoapp -log none
  • Default

    Generates an app that uses Dependency Injection to configure logging that writes output to Console. This is the default logging for the recommended preset.

    dotnet new unoapp -log default
  • Serilog

    Generates an app that uses Dependency Injection to configure logging with Serilog.

    dotnet new unoapp -log serilog

Refer to the Logging documentation for more information.

7. Features

Toolkit

Installs the Uno.Toolkit package in the project, this package adds a set of custom controls, behaviors, extensions and other utilities to Uno Platform projects that are not offered out-of-the-box by WinUI.

This includes Card, TabBar, NavigationBar and others.

This is included by default in the recommended preset, but not in the blank preset.

dotnet new unoapp -toolkit
Tip

The Uno Toolkit is demonstrated as a live web app here. It is also available as an iOS or Android app.
The Gallery app is open-source and is available on GitHub.

.NET MAUI Embedding

Adds support for embedding .NET MAUI controls and third party libraries into an application. This is not included in either the blank or recommended presets.

dotnet new unoapp -maui

Server

Adds an ASP.NET Core Server project to the solution, which hosts the WASM project, and can also be used to create an API and endpoints. It can also be used as the data server and you can also choose to implement the authentication server code in it.

This is included by default in the recommended preset, but not in the blank preset.

dotnet new unoapp -server

PWA Manifest

Includes a PWA (Progressive Web Apps) manifest that enables easy installation of the WASM web-target as an app in the running device.

This is included by default in both the blank and recommended presets.

Note

As this is a WASM feature it will be disabled (Wizard), or ignored (dotnet new), if WASM is not selected as one of the output target platforms.

dotnet new unoapp -pwa

Visual Studio Code debugging

Enables Uno Platform debugging in Visual Studio Code. This is included by default in both the blank and recommended presets.

dotnet new unoapp -vscode

WASM Multi-Threading

Enables multi-threading in the WASM project.
This option is only available if WASM is selected as one of the output target platforms. This is not enabled in either blank or recommended presets.

dotnet new unoapp -wasm-multi-threading

8. Authentication

Adds Uno Platform's Custom Authentication support to the generated project.

Using Uno's authentication tools you can easily integrate in your app a login screen and authenticate users. It also helps you manage and track the state of the app's authentication, by allowing you to log out or switch users as well as other authentication-related actions.

Uno.Extensions.Authentication currently supports these types of authentication:

  • None

    No authentication is added to the application. This is the default for both blank and recommended presets.

    dotnet new unoapp -auth none

  • Custom

    Provides a customized login experience for performing login, refresh, or logout. This is also the authentication type that is generated with the project template when Custom Authentication is selected. The other types are not supported yet at the moment but they're on the roadmap and will come to the wizard soon.

    dotnet new unoapp -auth custom

  • MSAL

    MSAL (formerly AzureAD) stands for Microsoft Authentication Library, is part of the Microsoft Identity Platform and enables acquiring authentication tokens and access of protected APIs using OAuth2 and OpenID.

    dotnet new unoapp -auth msal

  • OIDC

    Also referred to as OpenID Connect, is a simple identity layer using the OAuth 2.0 protocol.

    dotnet new unoapp -auth oidc

  • Web

    Web authentication is achieved via a web page that the app sends over to be opened in the browser and gets a token result once the login process is completed successfully.

    dotnet new unoapp -auth web

Read the Authentication documentation to get more knowledge about Uno Platform's authentication support and the tools it provides.

Note

The Authentication option is selected by default in the Default template, and not in the Blank one. This option is dependent on the DependencyInjection option and is only shown if the latter is enabled.

9. Application

Application ID

This option sets the iOS/macOS application Bundle ID to be used in the App Store.

The Application ID is also used as the Win App SDK Application ID setting for the app.

dotnet new unoapp -id com.mycompany.myapp

Publisher

This option sets the Publisher name in the Win App SDK settings.

dotnet new unoapp -pub 'O=My Company, C=US'

10. Testing

  • Unit tests

    Adds an NUnit test project that targets the main (shared) head project.

    The project also comes with FluentAssertions pre-installed.

    This is included in the recommended preset, but not in the blank preset.

    dotnet new unoapp -tests unit

  • UI tests

    Adds an NUnit-powered test app that provides UI testing capabilities using Uno Platform's UI testing tools (Uno.UITest).

    To learn more about UI Testing in Uno Platform apps, read this.

    This is included in the recommended preset, but not in the blank preset.

    dotnet new unoapp -tests ui

You can include both types of tests by including the parameter multiple times:

dotnet new unoapp -tests ui -tests unit

Alternatively, to include no tests, use the none parameter:

dotnet new unoapp -tests none

Testing tab in the wizard

11. CI Pipeline

  • None

    No CI pipeline will be created. This is the default option for both the blank and recommended presets.

    dotnet new unoapp -ci none

  • Azure Pipelines

    Adds a YAML file that can be used to create a CI pipeline in Azure Pipelines.

    dotnet new unoapp -ci azure

  • GitHub Action

    Adds a YAML file that can be used to create a CI pipeline in GitHub Actions.

    dotnet new unoapp -ci github