# Uno Platform

> uid: Uno.Features.AdaptiveTrigger

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/AdaptiveTrigger.md

---
uid: Uno.Features.AdaptiveTrigger
---

# Using Adaptive Triggers With Uno Platform Applications

## AdaptiveTrigger Class

Use the `AdaptiveTrigger` class to trigger a `<VisualState.Setters>` target. The target invokes changes in window properties, such as font size or panel orientation.

For more information, please refer to Microsoft's documentation on the [AdaptiveTrigger class](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.adaptivetrigger) and the [VisualState class](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.visualstate).

## Differences between Uno and WinUI

In a standard WinUI application, the sequential order of the adaptive trigger does not matter. The compiler will execute any `<VisualState.Setters>` target regardless of their order. For more information, see [AdaptiveTriggers' order declared in XAML shouldn't matter GitHub issue](https://github.com/unoplatform/uno/issues/2662).

In an Uno Platform application, the sequential order of the adaptive trigger does matter. In this instance, the `VisualState` will execute the `Setters` when it finds the first matching occurrence. Subsequent triggers may be ignored if the first matching property remains true for the life of the program.

## Sample XAML

Following is an example of three `<VisualState>` blocks. The blocks are non-sequential, ordered from `SmallScreen` to `LargeScreen` to `MediumScreen`. The expected output is to have the font size change as the window size changes.

Each `<VisualState>` block has an adaptive trigger with a `MinWindowWidth` property. The property tells the `VisualState` to execute the `VisualState.Setters` whenever the window width is greater or equal to its integer value.

Example:

```xml
<Page
    x:Class="UnoTutorial1.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:UnoTutorial1"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"    
    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

    <Grid>
        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup>
                <VisualState x:Name="SmallScreen">
                    <VisualState.StateTriggers>
                        <!--Increase FontSize to 20 when window width >=200 effective pixels.-->
                        <AdaptiveTrigger MinWindowWidth="200"/>
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Target="Block1.FontSize" Value="20"/>
                    </VisualState.Setters>
                </VisualState>

                <VisualState x:Name="LargeScreen">
                    <VisualState.StateTriggers>
                        <!--Increase FontSize to 40 when window width is >=1000 effective pixels.-->
                        <AdaptiveTrigger MinWindowWidth="1000"/>
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Target="Block1.FontSize" Value="40"/>
                    </VisualState.Setters>
                </VisualState>

                <VisualState x:Name="MediumScreen">
                    <VisualState.StateTriggers>
                        <!--Increase FontSize to 30 when window width >=720 effective pixels.-->
                        <AdaptiveTrigger MinWindowWidth="720"/>
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Target="Block1.FontSize" Value="30"/>
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>

        <StackPanel x:Name="stackPanel" Orientation="Vertical">
            <TextBlock x:Name="Block1" Text="Sample text line 1."/>
            <TextBlock Text="Sample text line 2." FontSize="{Binding FontSize, ElementName=Block1, Mode=TwoWay}"/>
            <TextBlock Text="Sample text line 3." FontSize="{Binding FontSize, ElementName=Block1, Mode=TwoWay}"/>
        </StackPanel>
    </Grid>
</Page>
```

## Expected Output

The above code might generate an unexpected output in an Uno application.

`SmallScreen` is listed first in order. Because the property `MinWindowWidth="200"` remains true for the life of the program, the compiler will never execute the `LargeScreen` or `MediumScreen` adaptive triggers. In this instance, the font size never changes.

This example demonstrates why developers must consider the order of their adaptive triggers, as the ordering may generate unexpected outcomes.

The following demonstrates the same code, but re-written in a sequential order to generate the expected output:

```xml
<Page
    x:Class="UnoTutorial1.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:UnoTutorial1"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"    
    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

    <Grid>
        <VisualStateManager.VisualStateGroups>
            <VisualStateGroup>
                <VisualState x:Name="LargeScreen">
                    <VisualState.StateTriggers>
                        <!--Increase FontSize to 40 when window width is >=1000 effective pixels.-->
                        <AdaptiveTrigger MinWindowWidth="1000"/>
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Target="Block1.FontSize" Value="40"/>
                    </VisualState.Setters>
                </VisualState>

                <VisualState x:Name="MediumScreen">
                    <VisualState.StateTriggers>
                        <!--Increase FontSize to 30 when window width >=720 effective pixels.-->
                        <AdaptiveTrigger MinWindowWidth="720"/>
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Target="Block1.FontSize" Value="30"/>
                    </VisualState.Setters>
                </VisualState>
                <VisualState x:Name="SmallScreen">
                    <VisualState.StateTriggers>
                        <!--Increase FontSize to 20 when window width >=200 effective pixels.-->
                        <AdaptiveTrigger MinWindowWidth="200"/>
                    </VisualState.StateTriggers>
                    <VisualState.Setters>
                        <Setter Target="Block1.FontSize" Value="20"/>
                    </VisualState.Setters>
                </VisualState>
            </VisualStateGroup>
        </VisualStateManager.VisualStateGroups>

        <StackPanel x:Name="stackPanel" Orientation="Vertical">
            <TextBlock x:Name="Block1" Text="Sample text line 1."/>
            <TextBlock Text="Sample text line 2." FontSize="{Binding FontSize, ElementName=Block1, Mode=TwoWay}"/>
            <TextBlock Text="Sample text line 3." FontSize="{Binding FontSize, ElementName=Block1, Mode=TwoWay}"/>
        </StackPanel>
    </Grid>
</Page>
```

## Correct Output

In the above example, the `VisualState` blocks are sequential, ordered from `LargeScreen` to `MediumScreen` to `SmallScreen`. Because of this, the compiler will execute the first true occurrence in the order written.

The `LargeScreen` setter target is triggered when the window width is `>=` 1000 pixels. When this statement becomes false, the `VisualState` executes the next setter target that matches, i.e. the `MediumScreen` block. When the `MediumScreen` adaptive trigger is false, the `VisualState` finally executes the setter target for the `SmallScreen` block.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Authentication/AuthenticationOverview.md

---
uid: Uno.Extensions.Authentication.Overview
---
# Authentication

Uno.Extensions.Authentication is designed to make it simple to add authentication to an application. Authenticating a user may be used to restrict access to specific parts of the application, or in order to supply an access token when calling a back-end service.

There are two aspects to the Authentication extensions:

- Authentication: the process of authenticating the user and acquiring tokens
- Authorization: tokens (acquired via authentication) can be queried to control access to parts of the application or supplied to service call so the user can be authorized to access the back-end service

## Installation

`Authentication` is provided as an Uno Feature. To enable `Authentication` support in your application, add `Authentication` to the `<UnoFeatures>` property in the Class Library (.csproj) file. In case you are using Msal Authentication add `AuthenticationMsal`, or `AuthenticationOidc` for Oidc Authentication.

[!include[existing-app](../includes/existing-app.md)]

[!include[single-project](../includes/single-project.md)]

For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

## IAuthenticationService

The `IAuthenticationService` interface defines the methods that an application can call to authenticate the user.

```csharp
public interface IAuthenticationService
{
    string[] Providers { get; }
    ValueTask<bool> LoginAsync(IDispatcher? dispatcher, IDictionary<string, string>? credentials = default, string? provider = null, CancellationToken? cancellationToken = default);
    ValueTask<bool> RefreshAsync(CancellationToken? cancellationToken = default);
    ValueTask<bool> LogoutAsync(IDispatcher? dispatcher, CancellationToken? cancellationToken = default);
    ValueTask<bool> IsAuthenticated(CancellationToken? cancellationToken = default);
    event EventHandler LoggedOut;
}
```

There are any number of different application workflows that require authentication but they typically boil down to using one or more of the `IAuthenticationService` methods. For example:

### Login on launch

In this scenario the user is required to be authenticated in order to access the application. This is a workflow that redirects the user to a login prompt if they aren't authenticated when the application is launched.

- Launch app
- App invokes `IAuthenticationService.RefreshAsync` to refresh any existing tokens (eg retrieve a new Access Token by supplying a Refresh Token to an authentication endpoint).
- If `RefreshAsync` returns true, the user is logged in, so navigate to the home page of the application
- If `RefreshAsync` returns false, navigate to the login page of the application
- On the login page, user enter credentials and clicks Login, the app invokes `IAuthenticationService.LoginAsync` and supplies credentials
- If `LoginAsync` returns true, app navigates to home page
- The user might decide to logout of the application, which invokes the `IAuthenticationService.LogoutAsync` method, the application then navigates back to the login page.

### User login requested

In this scenario the application doesn't require the user to be authenticated unless they want to access certain parts of the application (or there is additional/different information that's available to the user if they've logged in)

- Launch app
- App invokes `IAuthenticationService.RefreshAsync` to refresh any existing tokens and to determine if the user is authenticated. The user is directed to the home page of the application, either as an unauthenticated or authenticated user (depending on the app, this may show different data).
- User attempts to navigate to a part of the application that needs them to be authenticated, or just clicks a sign-in button so they can access the current page as an authenticated user.
- App navigates to the login page where the user can enter their credentials. The app then invokes `IAuthenticationService.LoginAsync` to authenticate the user.
- If `LoginAsync` returns true, the user is then either navigated to the part of the application they were attempting to access, or back to the view they were on.
- The user can logout of the application, which again invokes the `IAuthenticationService.LogoutAsync` method

## Authentication Providers (IAuthenticationProvider)

The process of authentication with a given authority is implemented by an authentication provider (i.e. implements IAuthenticationProvider). Multiple providers, and in fact, multiple instances of any provider, can be registered during application startup. For example, an application may want to provide support for authenticating using Facebook, Twitter and Apple - each of these has a different backend service that needs to be connected with. In the application the user selects which registered provider to use by supplying the `provider` argument when invoking the `IAuthenticationService.LoginAsync` method. This argument is optional and is not required if only a single provider has been registered.

> [!NOTE]
> The `IAuthenticationProvider` implementations are all marked as internal as they should be configured via the extensions methods on the `IHostBuilder` and the builder interface for the corresponding implementation.

### Custom

The `CustomAuthenticationProvider` provides a basic implementation of the `IAuthenticationProvider` that requires callback methods to be defined for performing login, refresh and logout actions. Learn [Custom authentication](xref:Uno.Extensions.Authentication.HowToAuthentication)

### MSAL

The `MsalAuthenticationProvider` wraps the [MSAL library](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) from Microsoft into an implementation of `IAuthenticationProvider`. This implementation ignores any credentials passed into the `LoginAsync` method, instead invoking the web based authentication process required to authentication with Microsoft. Learn [Msal authentication](xref:Uno.Extensions.Authentication.HowToMsalAuthentication)

### Oidc

The `OidcAuthenticationProvider` wraps support for any [OpenID Connect](https://openid.net/connect/) backend, including [IdentityServer](https://duendesoftware.com/products/identityserver). Learn [Oidc authentication](xref:Uno.Extensions.Authentication.HowToOidcAuthentication)

#### Platform-specific behavior

When the `OidcAuthenticationProvider` is automatically built, there are platform specific checks invoked internally which occasionally alter behavior during the authentication process:

**WebAssembly**: The `OidcAuthenticationProvider` will automatically use the `WebAuthenticationBroker` to obtain redirect URIs during the authentication process. This is done to avoid the need for a redirect to a custom URI scheme, which is not supported in the browser.

### Web

The `WebAuthenticationProvider` provides an implementation that displays a web view in order for the user to login. After login, the web view redirects back to the application, along with any tokens. Learn [Web Authentication](xref:Uno.Extensions.Authentication.HowToWebAuthentication)

#### Platform-specific behavior

Before the `WebAuthenticationProvider` is automatically built, there are platform specific checks invoked internally which occasionally alter behavior during the authentication process:

**Windows**: The `AddWeb()` extension method will initialize a `WebAuthenticator` to launch an out-of-process browser. This is done preemptively to support its usage within `WebAuthenticationProvider` during login and logout instead of the `WebAuthenticationBroker` used for other platforms.

**Other platforms**: For a description of various subtle differences when displaying a web login prompt on multiple platforms, see [Web Authentication Broker](https://platform.uno/docs/articles/features/web-authentication-broker.html). The broker will only respond to the `PrefersEphemeralWebBrowserSession` setting value in iOS (versions 13.0+), while the other platforms will ignore it.

## Http Handlers

Once a user has been authenticated, the tokens are cached and are available for use when invoking service calls. Rather than developers having to access the tokens and manually appending the tokens to the http request, the Authentication extensions includes http handlers which will be inserted into the request pipeline in order to apply the tokens as required.

### Authorization Header

The `HeaderHandler` is used to apply the access token to the http request using the `Authorization` header. The default scheme is `Bearer` but this can be override to use a different scheme, such as basic.

### Cookies

The `CookieHandler` is used to apply the access token, and/or refresh token, to the http request as cookies. This requires the cookie name for access token and request token to be specified as part of configuring the application. Learn how to use [Cookies](xref:Uno.Extensions.Authentication.HowToCookieAuthorization) to authorize

---

# Source: https://github.com/unoplatform/uno/blob/master/CODE_OF_CONDUCT.md

# Code of Conduct

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. This code of conduct has been adopted by many other open source communities and we feel it expresses our values well.

As contributors and maintainers of this project, and in the interest of fostering an open and welcoming community, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

We are committed to making participation in this project a harassment-free experience for everyone, regardless of the level of experience, gender, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, or nationality.

Examples of unacceptable behavior by participants include:

- The use of sexualized language or imagery
- Personal attacks
- Trolling or insulting/derogatory comments
- Public or private harassment
- Publishing other's private information, such as physical or electronic addresses, without explicit permission
- Other unethical or unprofessional conduct

Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.

By adopting this Code of Conduct, project maintainers commit themselves to fairly and consistently applying these principles to every aspect of managing this project. Project maintainers who do not follow or enforce the Code of Conduct may be permanently removed from the project team.

This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community.

Instances of abusive, harassing or otherwise, unacceptable behavior may be reported by contacting a project maintainer at [conduct@platform.uno](mailto:conduct@platform.uno). All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. Maintainers are obligated to maintain confidentiality concerning the reporter of an incident.

This Code of Conduct is adapted from the Contributor Covenant, version 1.3.0, available from [http://contributor-covenant.org/version/1/3/0/](http://contributor-covenant.org/version/1/3/0/)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/ComboBox.md

---
uid: Uno.Controls.ComboBox
---

# ComboBox

The `ComboBox` is designed to select a value in a set of items. For more information about its usage, see [Combo box and list box Microsoft documentation](https://learn.microsoft.com/windows/apps/design/controls/combo-box).

## Customize the placement of the Drop-Down (UNO-only feature)

By default, when opening a `ComboBox`, WinUI aligns its drop-down to keep the selected item at the same location. This means that, if the currently selected value is the last one in the list, the drop-down will appear above the `ComboBox`.
If there isn't any selected item, the drop-down will appear centered over the `ComboBox`.

On Uno, you can change this behavior using `DefaultDropDownPreferredPlacement` or `DropDownPreferredPlacement`.

### Change the default value for all the `ComboBox` in your application

The default placement for all `ComboBox` instances can be changed by setting the feature flag in the startup of your app (`App.cs` or `App.xaml.cs`):

```csharp
Uno.UI.FeatureConfiguration.ComboBox.DefaultDropDownPreferredPlacement = DropDownPlacement.Below;
```

### Change only for a specific `ComboBox`

```xml
<Page
    [...]
    xmlns:not_win="using:Uno.UI.Xaml.Controls"
    mc:Ignorable="d not_win">

    <ComboBox
        ItemsSource="12345"
        not_win:ComboBox.DropDownPreferredPlacement="Below" />

```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/CommandBar.md

---
uid: Uno.Controls.CommandBar
---

# CommandBar

The `CommandBar` in **Uno** is designed to be used the same way you would use the `CommandBar` on **WinUI**. In most cases, you should refer to the [official `CommandBar` documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.commandbar).

This document exists to highlight some of the differences you might encounter when working with the native mode of `CommandBar` on either **iOS** or **Android**.

## Modes

The `CommandBar` supports 2 different modes:

| Mode    | Style                    |
|---------|--------------------------|
| Windows | `XamlDefaultCommandBar`  |
| Native  | `NativeDefaultCommandBar`|

### Windows

This mode replicates **WinUI**'s `CommandBar`. It is templatable and supports a template that's almost identical to **WinUI**'s default `CommandBar`.

![CommandBar Example - Windows](assets/commandbar/windows/example.png)

#### Usage Example

```csharp
<Style TargetType="CommandBar" BasedOn="{StaticResource XamlDefaultCommandBar}" />
```

#### Remarks

- This mode hasn't been extensively tested.
- We usually avoid using this mode, and prefer to use the Native one instead.

### Native

This mode is the preferred one and is enabled by default. It uses platform-specific controls to ensure a more native user experience.

![CommandBar Example - Android](assets/commandbar/android/example.png)

![CommandBar Example - iOS](assets/commandbar/ios/example.png)

| Platform | Native control      | Benefits                                              |
|----------|---------------------|-------------------------------------------------------|
| Android  | `Toolbar`          | Native pressed states (ripple), native overflow menu. |
| iOS      | `UINavigationBar` | Transitions when navigating  between pages.   |

The rest of this document will exclusively cover this mode.

#### Usage Example

```csharp
<Style TargetType="CommandBar" BasedOn="{StaticResource NativeDefaultCommandBar}" />
```

#### Remarks

In this mode, the `CommandBar` can't be fully customized like other templatable controls would. Additionally, you can't customize the visual states of either the `CommandBar` or its `AppBarButton`s.

### Padding

You must use `VisibleBoundsPadding.PaddingMask="Top"` on `CommandBar` to properly support the notch or punch-holes on iOS/Native and Android/Native.

On Skia-based renderers, you'll need to set the `VisibleBoundsPadding` or `SafeArea` on the parent control of the `CommandBar`.

#### Back button

An important difference with this mode is the presence of a back button. Whenever the `CommandBar` is part of a `Page` whose `Frame` has a non-empty back stack, the back button will be displayed.

![CommandBar Example - Android - Back button](assets/commandbar/android/back.png)

![CommandBar Example - iOS - Back button](assets/commandbar/ios/back.png)

On **Android**, tapping the back button triggers `SystemNavigationManager.BackRequested`. It's the responsibility of the application's navigation controller to eventually call `Frame.GoBack()`.

On **iOS**, tapping the back button automatically triggers a back navigation on the native `UINavigationController` (which is part of the native `Frame` implementation). The `Frame` will raise the `Navigated` event, and its state will automatically be updated to reflect the navigation. The navigation can't be intercepted or canceled. To intercept back navigation, you must replace the native back button with your own custom button using `NavigationCommand` (see below).

## Properties

| Property                              | Windows | iOS | Android | Comments                                                                                                               |
|---------------------------------------|:-------:|:---:|:-------:|------------------------------------------------------                                                                  |
| Background                            | x       | x   | x       |                                                                                                                        |
| Content                               | x       | x   | x       |                                                                                                                        |
| Foreground                            | x       | x   | x       |                                                                                                                        |
| Height                                | x       | -   | -       | **iOS** and **Android**: Fixed and can't be changed.                                                                   |
| HorizontalAlignment                   | x       | -   | x       | **iOS**: Always use `HorizontalAlignment.Stretch`.                                                                     |
| Opacity                               | x       | x   | x       |                                                                                                                        |
| Padding                               | x       | x   | x       | **iOS**, **Android** and **Skia**: Please refer to the `Padding` section.                                                        |
| PrimaryCommands                       | x       | x   | x       |                                                                                                                        |
| SecondaryCommands                     | x       | -   | x       | **iOS**: Not supported.                                                                                                |
| VerticalAlignment                     | x       | -   | x       | **iOS**: Always use `VerticalAlignment.Top`.                                                                           |
| Visibility                            | x       | x   | x       |                                                                                                                        |
| Width                                 | x       | -   | x       | **iOS**: Always use `double.NaN`.                                                                                      |
| HorizontalContentAlignment            | x       | -   | x       | **Android**: Stretch and Left are supported. **Windows**: Set `IsDynamicOverflowEnabled="False"` for proper behavior.  |
| VerticalContentAlignment              | x       | -   | -       | Only supported on Windows. **Android**: Alignment needs to be done through the content itself.                         |

*If it's not listed, assume it's not supported.*

### Background

Gets or sets a brush that describes the background of a control.

![CommandBar Example - Android - Background](assets/commandbar/android/background.png)

![CommandBar Example - iOS - Background](assets/commandbar/ios/background.png)

#### Remarks

- Only supports `SolidColorBrush`.
- Changing the opacity through `SolidColorBrush.Opacity` is supported.

### Content

Gets or sets the content of a `ContentControl`.

#### Remarks

The `Content` is processed differently whether it's of type `string` or `FrameworkElement`.

When `Content` is a `string`, it's displayed using the platform's default font family, font size, font style and text alignment. Only the foreground color can be changed, using `Foreground`.

![CommandBar Example - Android - When Content is a `string`](assets/commandbar/android/content-string.png)

![CommandBar Example - iOS - When Content is a `string`](assets/commandbar/ios/content-string.png)

| Platform | FontFamily    | FontSize | HorizontalAlignment |
|----------|---------------|----------|---------------------|
| iOS      | `San Francisco` | 17       | Center              |
| Android  | `Roboto`        | 20       | Left                |

When `Content` is a `FrameworkElement`, it's displayed within the available area:

![CommandBar Example - Android - When Content is a `FrameworkElement`](assets/commandbar/android/content-frameworkelement.png)

![CommandBar Example - iOS - When Content is a `FrameworkElement`](assets/commandbar/ios/content-frameworkelement.png)

| Platform | Available height |
|----------|:----------------:|
| iOS      | 30px             |
| Android  | 48px             |

Please note that:

- `HorizontalContentAlignment` and `VerticalContentAlignment` are ignored.
- On **iOS**, the Content is automatically centered horizontally unless `HorizontalAlignment.Stretch` is used.

### Foreground

Gets or sets a brush that describes the foreground color.

![CommandBar Example - Android - Foreground](assets/commandbar/android/foreground.png)

![CommandBar Example - iOS - Foreground](assets/commandbar/ios/foreground.png)

#### Remarks

- This is typically used to change the Content`'s text color.
- Only supports `SolidColorBrush`.
- Setting this property will not affect any of the `CommandBar's` `AppBarButton` tint Color. If you need to change the `AppBarButton` tint, this is possible by setting the `ShowAsMonochrome` property to true as well as setting the Foreground`SolidColorBrush`on the`BitmapIcon`.
- On`Android`, you can also enable a feature that will allow that the`SolidColorBrush`set on your `CommandBar` `Foreground` to update your`AppBarButton`s Tint. To enable this, set on your `App.xml.cs` the `FeatureConfiguration.AppBarButton.EnableBitmapIconTint` to **true**.

### PrimaryCommands

Gets the collection of primary command elements for the `CommandBar`.

![CommandBar Example - Android - PrimaryCommands](assets/commandbar/android/primarycommands.png)

![CommandBar Example - iOS - PrimaryCommands](assets/commandbar/ios/primarycommands.png)

#### Remarks

- Only supports `AppBarButton`. `AppBarToggleButton` and `AppBarSeparator` are not supported.
- Refer to  the `AppBarButton` section for details.

### SecondaryCommands

Gets the collection of secondary command elements for the `CommandBar`.

![CommandBar Example - Android - SecondaryCommands](assets/commandbar/android/secondarycommands.png)

![CommandBar Example - iOS - SecondaryCommands](assets/commandbar/android/secondarycommands-popup.png)

#### Remarks

- Only supported on **Android**.

### Height

Gets or sets the suggested height of a `FrameworkElement`.

#### Remarks

The height is fixed and cannot be changed.

| Platform | Form factor | Portrait | Landscape |
|----------|-------------|:--------:|:---------:|
| iOS      | Phone       | 44pt     | 44pt      |
| iOS      | Tablet      | 44pt     | 44pt      |
| Android  | Phone       | 48dp     | 56dp      |
| Android  | Tablet      | 64dp     | 64dp      |

[Source (Android)](https://material.io/guidelines/layout/structure.html#structure-app-bar)

## Extensions

Extensions are attached properties that extend the **WinUI** APIs to provide platform-specific features.

They can be found in the `Uno.UI.Toolkit` namespace.

Extensions to extend the functionality of `CommandBar` can be found in the `CommandBarExtensions` class.

| Attached Property    | Windows | iOS | Android | Comments |
|----------------------|:-------:|:---:|:-------:|----------|
| BackButtonForeground | -       | x   | x       |          |
| BackButtonIcon       | -       | x   | x       |          |
| BackButtonTitle      | -       | x   | x       |          |
| NavigationCommand    | -       | x   | x       |          |
| Subtitle             | -       | -   | x       |          |

### BackButtonForeground

Gets or sets the back button foreground for the `CommandBar`.

![CommandBar Example - Android - BackButtonForeground](assets/commandbar/android/backbuttonforeground.png)

![CommandBar Example - iOS - BackButtonForeground](assets/commandbar/ios/backbuttonforeground.png)

#### Remarks

- Only supports `SolidColorBrush`.

### BackButtonIcon

Gets or sets the back button icon for the `CommandBar`.

![CommandBar Example - Android - BackButtonIcon](assets/commandbar/android/backbuttonicon.png)

![CommandBar Example - iOS - BackButtonIcon](assets/commandbar/ios/backbuttonicon.png)

#### Remarks

- Only supports `BitmapIcon`.

### BackButtonTitle

Gets or sets the back button title for the `CommandBar`.

![CommandBar Example - iOS - BackButtonTitle](assets/commandbar/ios/backbuttontitle.png)

#### Remarks

Only supported on **iOS**.

On **iOS**, the back button displays the title of the previous page (which we usually set as `string` on `Content`). When the title of the previous page is too long (over 140px wide on iPhone 5) or isn't set (for example, if we set `FrameworkElement` instead of `string` on `Content`), "Back" will be displayed instead.

To explicitly provide a value to be used by the back button of the next page, use `BackButtonTitle`.

To remove the back button title from all pages (and only leave the back arrow), set `BackButtonTitle` to `""` in the default `CommandBar` style.

**WARNING:** The name of this property can be misleading, and doesn't actually let you change the title of the back button displayed on the given `CommandBar`. Read above for recommended usage.

### Elevation

Gets or sets the elevation of the `UIElement`.

![CommandBar Example - Android - Elevation](assets/commandbar/android/elevation.png)

![CommandBar Example - iOS - Elevation](assets/commandbar/ios/elevation.png)

#### Remarks

- This is usually only used on **Android**.
- According to [Google's Material Design Guidelines](https://material.io/guidelines/material-design/elevation-shadows.html), the recommended elevation for `CommandBar` is **8**.

### NavigationCommand

Gets or sets the navigation command for the `CommandBar`.

![CommandBar Example - Android - NavigationCommand](assets/commandbar/android/navigationcommand.png)

![CommandBar Example - iOS - NavigationCommand](assets/commandbar/ios/navigationcommand.png)

#### Remarks

Unlike the `PrimaryCommands` or `SecondaryCommands`, which appear to the right of the `CommandBar`, the `NavigationCommand` appears to the left of the `CommandBar`.

This is typically used for burger menus.

On **iOS**, the back gesture can be enabled or disabled using this property.

- When a `CommandBar` (visible or collapsed) is in the visual tree, the back gesture is **enabled**.
- When a `CommandBar` has a `NavigationCommand`, the back gesture is **disabled**.

On **Android**, only icons are supported (`AppBarButton.Icon`). This is due to a platform limitation, which can be explained by the fact that `CommandBar.Content` is left-aligned.

### Subtitle (**Android**)

Gets or sets the subtitle for the `CommandBar`.

![CommandBar Example - Android - Subtitle](assets/commandbar/android/subtitle.png)

#### Remarks

- The subtitle is displayed below the native title (`Content` of type `string`).
- The color of the subtitle currently can't be changed.

## Placement

On **iOS**, the same `UINavigationBar` instance is shared throughout all pages. When navigating between two pages, you can see that the `UINavigationBar` doesn't move, and only its content and the pages have a transition. To get the same effect while still letting you use `CommandBar` as you would on **WinUI** (as part of the `Page`), we have to do some magic. Namely, the `CommandBar` you define inside your `Page` is never actually rendered there, and only serves as a placeholder from which to read the information we need to pass to the shared `UINavigationBar` instance.

To ensure everything works properly, you must follow a few rules:

- The `CommandBar` must stretch horizontally and be aligned with the top of your `Page`.
- The `CommandBar` can't move (i.e., don't put it inside a `ScrollViewer`)
- The `CommandBar` must be accessible as soon as the page is being navigated to (i.e., don't put it inside a `DataTemplate` or an `AsyncValuePresenter`).
- There can only be one `CommandBar` per page.

## Extensibility

The `CommandBar` it automatically managed by the `Frame` control, however you can still use the "native" mode of the `CommandBar` with your own navigation mechanism.

On **iOS** a `CommandBarHelper` is available for this purpose, you only have to invoke each of the provided method in your own `UIViewController` implementation.

<!-- markdownlint-disable MD025 -->
<!-- TODO: Consider moving AppBarButton to a separate page -->

# AppBarButton

The `AppBarButton` in **Uno** is designed to be used the same way you would use the `AppBarButton` on **WinUI**. In most cases, you should refer to the [official `CommandBar` documentation](https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.appbarbutton).

When `AppBarButton` is used within a native `CommandBar`, its control template is completely ignored and can't be customized.

## Events

| Event   | Windows | iOS | Android | Comments |
|---------|:-------:|:---:|:-------:|----------|
| Clicked | x       | x   | x       |          |

## Properties

| Property        | Windows | iOS | Android | Comments                                   |
|-----------------|:-------:|:---:|:-------:|--------------------------------------------|
| Command         | x       | x   | x       |                                            |
| Content         | x       | x*  | x*      | Supports `string` and `FrameworkElement`.  |
| Foreground      | x       | x   | x*      | **Android**: See details below.            |
| Icon            | x       | x*  | x*      | Only supports `BitmapIcon`.                |
| IsEnabled       | x       | x   | x*      | **Android**: Not supported with `Content`. |
| Label           | x       | x*  | x*      | See details below.                         |
| Opacity         | x       | x   | x       |                                            |
| Visibility      | x       | x   | x       |                                            |

*If it's not listed, assume it's not supported.*

### Foreground

Gets or sets a brush that describes the foreground color.

![CommandBar AppBarButton Example - Android - Foreground](assets/commandbar/android/appbarbutton-foreground.png)

![CommandBar AppBarButton Example - iOS - Foreground](assets/commandbar/ios/appbarbutton-foreground.png)

#### Remarks

- This changes the color of the `Content` (text) or `Icon`.
- Only supports `SolidColorBrush`.
- On **Android**, this only affects the color of `Icon`, not `Content` (text).
- On **iOS**, the default value is blue.

### Content

Gets or sets the content of a `ContentControl`.

![CommandBar AppBarButton Example - Android - Content](assets/commandbar/android/appbarbutton-content.png)

![CommandBar AppBarButton Example - iOS - Content](assets/commandbar/ios/appbarbutton-content.png)

#### Remarks

- When given a `string`, its text will be displayed instead of the icon.
- When given a `FrameworkElement`:
  - it will be displayed instead of the icon
  - the native pressed state and tooltip (Android only) won't work
- Make sure to set `Icon` to null, as it takes priority over `Content`.

### Icon

Gets or sets the graphic content of the app bar button.

![CommandBar AppBarButton Example - Android - Icon](assets/commandbar/android/appbarbutton-icon.png)

![CommandBar AppBarButton Example - iOS - Icon](assets/commandbar/ios/appbarbutton-icon.png)

#### Remarks

- Only supports `BitmapIcon` (with PNG).

#### Recommended icon sizes (by scale)

| Platform | 100%  | 150%  | 200%  | 300%  | 400%    |
|----------|:-----:|:-----:|:-----:|:-----:|:-------:|
| iOS      | 25x25 | -     | 50x50 | 75x75 | -       |
| Android  | 24x24 | 36x36 | 48x48 | 72x72 | 96x96   |
| Windows  | 32x32 | 48x48 | 64x64 | 96x96 | 128x128 |

### Label

Gets or sets the text description displayed on the app bar button.

![CommandBar AppBarButton Example - Android - Label](assets/commandbar/android/appbarbutton-tooltip.png)

![CommandBar AppBarButton Example - iOS - Label](assets/commandbar/android/secondarycommands-popup.png)

#### Remarks

Unlike on **WinUI**, the `Label` will not be displayed below the `Icon`.

It is only displayed on **Android** when the `AppBarButton` is displayed from the overflow (when part of `SecondaryCommands`)

It is highly recommended to set and localize `Label` on all `AppBarButton`s, if only for accessibility.

### IsEnabled

Gets or sets a value indicating whether the user can interact with the control.

![CommandBar AppBarButton Example - Android - Disabled](assets/commandbar/android/appbarbutton-disabled.png)

![CommandBar AppBarButton Example - iOS - Disabled](assets/commandbar/ios/appbarbutton-disabled.png)

#### Remarks

- When set to **false**, buttons are disabled and grayed out (semi-transparent).
- You can't customize the disabled visual state of buttons.
- On **Android**, the disabled visual state only works with `Icon` and not with `Content` (text).

# Known issues

## iOS

- Can't have multiple CommandBars in the same page (e.g., Master/Details, bottom CommandBar).
- Can't change the title of the back button if the previous page doesn't have a CommandBar.
- You must define the title of the back button of the current page's CommandBar in the CommandBar of the previous page.
- Can't have a smooth transition between pages with different CommandBar backgrounds.
- Can't have a smooth transition between pages with and without a CommandBar.
- Can't change the position and size of the CommandBar (always top-aligned, horizontally-stretched, height of 44).
- Can't remove the 1px underline/shadow without making the CommandBar's background transparent.
- Can't change the height of the CommandBar.
- Can't use the back gesture on pages without a CommandBar.
- Can't disable the back gesture without using workarounds (fake back buttons).
- Can't change the Visibility of a CommandBar.
- Can't change the Opacity of a CommandBar.
- Can't superpose views over a CommandBar.
- Can't animate/translate the CommandBar (i.e., when hiding/showing it based on scroll offset).
- Can't put your CommandBar inside a ScrollViewer and make it scroll.
- Can't put your CommandBar inside templates (i.e., AVP).
- Can't cancel a back navigation using BackRequestedEventArgs.Handled.

# FAQ: CommandBar

- > Why is my content underneath the `CommandBar` for iOS and the `CommandBar` underneath the StatusBar/Notch for Android ?

  You must use `VisibleBoundsPadding.PaddingMask="Top"` on `CommandBar` to properly support the notch or punch-holes on iOS and Android.

  ```xml
  xmlns:toolkit="using:Uno.UI.Toolkit"
  ...
  <Style Target="CommandBar">
      <Setter Property="toolkit:VisibleBoundsPadding.PaddingMask"
              Value="Top" />
  </Style>
  ```

- > How can I remove the back button title from all pages on iOS?

  ```xml
  xmlns:toolkit="using:Uno.UI.Toolkit"
  ...
  <Style Target="CommandBar">
      <Setter Property="toolkit:CommandBarExtensions.BackButtonTitle"
              Value="" />
  </Style>
  ```

- > How can I change the back button icon/arrow/chevron in my app?

  ```xml
  xmlns:toolkit="using:Uno.UI.Toolkit"
  ...
  <Style Target="CommandBar">
      <Setter Property="toolkit:CommandBarExtensions.BackButtonIcon">
          <Setter.Value>
              <BitmapIcon UriSource="ms-appx://Assets/back.png" />
          </Setter.Value>
      </Setter>
  </Style>
  ```

- > How can I change the color of the back button?

  ```xml
  xmlns:toolkit="using:Uno.UI.Toolkit"
  ...
  <CommandBar toolkit:CommandBarExtensions.BackButtonForeground="Red" />
  ```

- > Why does my back button display "Back" on iOS?

  The back button will display "Back" if:

  - The previous page doesn't have a `CommandBar`.
  - The previous page's `CommandBar` doesn't have a `Content` of type `string`.
  - The previous page's `CommandBar` doesn't have a `CommandBarExtensions.BackButtonTitle`.
  - The previous page's `CommandBar` has a title that's too long (more than 140pt).

- > Why can't I overlap content over the CommandBar on iOS?

  The `CommandBar` is not actually part of the `Page` on **iOS**, and you can't overlap content over it like you would on **WinUI** or **Android**. Please refer to the **Placement** section for details.

- > Why is my CommandBar going into the status bar on iOS/Android?

  You must use `VisibleBoundsPadding.PaddingMask="Top"` on the parent control of `CommandBar` to properly support the notch or punch-holes on iOS and Android.

  ```xml
  xmlns:toolkit="using:Uno.UI.Toolkit"
  ...
  <Grid toolkit:VisibleBoundsPadding.PaddingMask="Top">
      <CommandBar>
        ...
      </CommandBar>
  </Style>
  ```

- > Why doesn't my CommandBar show a back button?

  For a `CommandBar` to show a back button, it must first be resolved by `Frame` as soon as it navigates to a `Page`. To ensure that `CommandBar` is available as soon as the navigation starts, make sure it's directly part of a page, and not part of a `DataTemplate` or `ControlTemplate`.

- > Why don't my AppBarButton visual states work?

  You can't customize the `ControlTemplate` of `AppBarButton` when using `CommandBar` in native mode.

- > How can I change the foreground of the CommandBarExtensions.Subtitle on Android?

  You can't currently customize the foreground of the `CommandBarExtensions.Subtitle` on **Android**.

- > Why doesn't CommandBarExtensions.Subtitle work on iOS?

  `CommandBarExtensions.Subtitle` is not currently implemented on iOS.

  You can replicate the same effect by setting a custom `Content` on `CommandBar`:

  ```xml
  <CommandBar>
      <CommandBar.Content>
          <StackPanel HorizontalAlignment="Center">
              <TextBlock Text="Title"
                         HorizontalAlignment="Center"
                         FontSize="15" />
              <TextBlock Text="Subtitle"
                         HorizontalAlignment="Center"
                         FontSize="12"
                         Opacity="0.5" />
          </StackPanel>
      </CommandBar.Content>
  </CommandBar>
  ```

- > How can I add a badge to an AppBarButton?

  You can implement your own badge by setting a custom content on `AppBarButton`:

  ```xml
  <AppBarButton>
      <AppBarButton.Content>
          <Grid Height="48"
                Width="48">
              <Image Source="ms-appx:///Assets/Icons/cart.png"
                     VerticalAlignment="Center"
                     HorizontalAlignment="Center" />
              <Border x:Name="Badge"
                      VerticalAlignment="Top"
                      HorizontalAlignment="Right"
                      Background="Red"
                      Margin="8,4"
                      Padding="4,0"
                      MinWidth="16"
                      Height="16"
                      CornerRadius="8">
                  <TextBlock x:Name="Count"
                             HorizontalAlignment="Center"
                             VerticalAlignment="Center"
                             Foreground="White"
                             FontSize="8"
                             Text="0" />
              </Border>
          </Grid>
      </AppBarButton.Content>
  </AppBarButton>
  ```

- > How can I set custom content to an AppBarButton?

  You can set a custom content to an `AppBarButton` like this:

  ```xml
  <AppBarButton>
      <AppBarButton.Content>
          <TextBlock Text="Custom content goes here" />
      </AppBarButton.Content>
  </AppBarButton>
  ```

- > Why does my CommandBar always appear at the top of the page on iOS?

  You can't place your `CommandBar` anywhere other than at the top of the `Page` on **iOS**. See the **Placement** section for details.

- > How can I change the height of my CommandBar?

  You can't currently change the height of the `CommandBar`.

- > How can I remove the 1px line displayed below the CommandBar on iOS?

  To hide the native 1px *shadow* that's displayed below the `CommandBar` on **iOS**, make its background transparent:

  ```xml
  <CommandBar Background="Transparent" />
  ```

- > How can I add an elevation shadow to the CommandBar on Android?

  ```xml
  xmlns:toolkit="using:Uno.UI.Toolkit"
  ...
  <CommandBar toolkit:UIElementExtensions.Elevation="4" />
  ```

- > How can I use a Path for the AppBarButton Icon?

  `AppBarButton` doesn't currently support `PathIcon`. Only `BitmapIcon` with PNGs is supported. Please refer to the **Icon** section.

- > Why doesn't CommandBarExtensions.BackButtonTitle change the title of my back button?

  `CommandBarExtensions.BackButtonTitle` must be set on the page to which the back button navigates to. Please refer to the **BackButtonTitle** section.

- > Why doesn't my CommandBarExtensions.NavigationCommand display anything on Android?

  `CommandBarExtensions.NavigationCommand` only supports `AppBarButton` with `Icon` (not `Content`). Please refer to the **NavigationCommand** section.

- > How can I localize CommandBarExtensions.BackButtonTitle?

  *For attached properties, you need a special syntax in the Name column of a `.resw` file.* Ref: [Microsoft documentation](https://learn.microsoft.com/windows/uwp/app-resources/localize-strings-ui-manifest#refer-to-a-string-resource-identifier-from-xaml).

  More specifically :

  ```xml

  <CommandBar x:Uid="MyCommandBar"
              toolkit:CommandBarExtensions.BackButtonTitle="My Page Title">
          ...
  </CommandBar>
  ```

  And in the `.resw` file, the name would be: `MyCommandBar.[using:Uno.UI.Toolkit]CommandBarExtensions.BackButtonTitle`

- > How can I put a ComboBox in my CommandBar?

  ```xml
  <CommandBar>
      <CommandBar.Content>
          <ComboBox />
      </CommandBar.Content>
  </CommandBar>
  ```

- > How can I customize the pressed/disabled visual states of my AppBarButton?

  You can't currently customize the visual states of `AppBarButton` when using `CommandBar` in native mode.

- > Why doesn't the disabled state work on my AppBarButton on Android?

  `AppBarButton` doesn't currently support the disabled state when used with `Content` (of `string`) on **Android**. You can use an `Icon` instead.

- > How can I disable the back swipe/gesture on iOS?

  To disable the back swipe/gesture on **iOS**, you must remove the `CommandBar` or replace the back button with a custom one:

  ```xml
  <CommandBar>
      <toolkit:CommandBarExtensions.NavigationCommand>
          <AppBarButton Command="{Binding GoBack}">
              <AppBarButton.Icon>
                  <BitmapIcon UriSource="ms-appx:///Assets/Icons/back.png" />
              </AppBarButton.Icon>
          </AppBarButton>
      </toolkit:CommandBarExtensions.NavigationCommand>
  </CommandBar>
  ```

- > How can I display two CommandBars side by side on iOS (i.e., master-detail)

  `Page` only supports a single `CommandBar` at a time. To display two `CommandBar`s side by side (i.e., master-detail), you should place two `Frame`s side by side and put a `CommandBar` in the `Page` of each `Frame`.

- > How can I add a burger menu to the left of my CommandBar?

  ```xml
  <CommandBar>
      <toolkit:CommandBarExtensions.NavigationCommand>
          <AppBarButton Command="{Binding ToggleMenu}">
              <AppBarButton.Icon>
                  <BitmapIcon UriSource="ms-appx:///Assets/Icons/menu.png" />
              </AppBarButton.Icon>
          </AppBarButton>
      </toolkit:CommandBarExtensions.NavigationCommand>
  </CommandBar>
  ```

- > Why doesn't Flyout work on my AppBarButton?

  `AppBarButton` doesn't currently support `Flyout` when using `CommandBar` in native mode. You can use `MenuFlyout` instead.

- > Why can't I change the Foreground of my AppBarButton on Android?

  `AppBarButton` doesn't currently support `Foreground` when displaying text (using `Content` of `string`).

  However, you can change the color of all textual `AppBarButton`s globally using **Android** styles:

  **Colors.xml**

  ```xml
  <color name="red">#FFFF0000</color>
  ```

  **Styles.xml**

  ```xml
  <item name="android:actionMenuTextColor">@color/red</item>
  <item name="actionMenuTextColor">@color/red</item>
  ```

  If you need the button to display a different color to reflect being in a disabled state, you can add a selector in its own file, under res/color, like so:

  **PrimaryTextColorSelector.xml**

  ```xml
  <?xml version="1.0" encoding="utf-8"?>
  <selector xmlns:android="http://schemas.android.com/apk/res/android" >
      <item android:state_enabled="false" android:color="#88888888"/>
      <item android:color="#FF00FFFF"/>
  </selector>
  ```

  **Styles.xml**

  ```xml
  <item name="android:actionMenuTextColor">@color/PrimaryTextColorSelector</item>
  <item name="actionMenuTextColor">@color/PrimaryTextColorSelector</item>
  ```

- > How can I customize the font of the CommandBar title/content?

  You can't currently customize the font of the native `CommandBar` title (set with a `string` on `Content`). Only the color can be changed, using the `Foreground` property.

  To customize the font of the `CommandBar`'s title, you must set a custom `FrameworkElement` as the `Content` of your `CommandBar`:

  ```xml
  <CommandBar>
      <CommandBar.Content>
          <TextBlock Text="Title"
                     FontStyle="Italic"
                     FontWeight="Bold"
                     FontSize="30" />
      </CommandBar.Content>
  </CommandBar>
  ```

- > Why doesn't my CommandBar scroll when placed inside a ScrollViewer on iOS?

  `CommandBar` can't be placed inside a `ScrollViewer`. It must be anchored to the top of your `Page` at all time. Please refer to the **Placement** section for details.

- > How can I change the color of the ripple effect when pressing on AppBarButtons on Android?

  You can change the color of the ripple effect globally using Android styles:

  **Colors.xml**

  ```xml
  <!-- https://android.googlesource.com/platform/frameworks/support/+/415f740/v7/appcompat/res/values/colors_material.xml -->
  <color name="ripple_material_light">#20444444</color>
  <color name="ripple_material_dark">#20ffffff</color>
  ```

  **Styles.xml**
  
   ```xml
  <item name="colorControlHighlight">@color/ripple_material_dark</item>
   ```

- > Why doesn't my AppBarToggleButton work?

  `AppBarToggleButton` is not currently supported.

  To implement a similar effect, you can bind your `AppBarButton`'s icon to a state using a converter:

  ```xml
  <CommandBar>
      <AppBarButton Command="{Binding ToggleIsFavorite}">
          <AppBarButton.Icon>
              <BitmapIcon UriSource="{Binding IsFavorite, Converter={StaticResource IsFavoriteToStarIcon}}" />
          </AppBarButton.Icon>
      </AppBarButton>
  </CommandBar>
  ```

- > How can I show an image under my CommandBar?

  You can show an image under a `CommandBar` by making its background transparent and superposing it over an `Image`:

  ```xml
  <Grid>
      <Image Source="http://www.example.com/image.png">
      <CommandBar Background="Transparent"
                  VerticalAlignment="Top" />
  </Grid>
  ```

  ![CommandBar Example - iOS - Transparent Background](assets/commandbar/ios/transparent.png)

- > What size should my AppBarButton icons be?

  Please refer to the **Icon** section for details.

- > Why does my back button icon change when swiping back on iOS?

  This can happen when navigating between two pages with `CommandBar`s using different `CommandBarExtensions.BackButtonIcon`s.

  To avoid this issue, please make sure that all `CommandBar`s use the same `CommandBarExtensions.BackButtonIcon` by using a style:

  ```xml
  <Style Target="CommandBar">
      <Setter Property="toolkit:CommandBarExtensions.BackButtonIcon">
          <Setter.Value>
              <BitmapIcon UriSource="ms-appx:///Assets/Icons/back.png" />
          </Setter.Value>
      </Setter>
  </Style>
  ```

  If the issue still occurs, make sure that both pages have a `CommandBar`. If you don't want your page to display a `CommandBar`, you can simply collapse it:

  ```xml
  <CommandBar Visibility="Collapsed" />
  ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Configuration/ConfigurationOverview.md

---
uid: Uno.Extensions.Configuration.Overview
---
# Configuration

`Uno.Extensions.Configuration` provides a uniform way to read or write configuration data from a number of distinct sources. The implementation of `IOptions<T>` from [Microsoft.Extensions.Options](https://learn.microsoft.com/dotnet/api/microsoft.extensions.options) allows for [read-only](https://learn.microsoft.com/dotnet/core/extensions/configuration#concepts-and-abstractions) access to values organized into **configuration sections**. The [writable configuration](xref:Uno.Extensions.Configuration.HowToWritableConfiguration) pattern supports the ability to update configuration values at runtime.

This feature uses [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration) for any configuration related work. For more documentation on configuration, read the references listed at the bottom.

## Installation

> [!NOTE]
> If you already have `Extensions` in `<UnoFeatures>`, then `Configuration` is already installed, as its dependencies are included with the `Extensions` feature.

`Configuration` is provided as an Uno Feature. To enable `Configuration` support in your application, add `Configuration` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

[!include[existing-app](../includes/existing-app.md)]

[!include[single-project](../includes/single-project.md)]

For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

## Using Configuration

The `IConfiguration` interface is registered as a service when the `UseConfiguration()` extension method is used.

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(e)
    .Configure(
        host => host
            .UseConfiguration( /* ... */)
    );

    Host = appBuilder.Build();
    ...
}
```

`IConfiguration` is then available to be accessed by any class instantiated by the dependency injection (DI) container:

```csharp
public class MyService : IMyService
{
    private readonly IConfiguration configuration;

    public MyService(IConfiguration configuration)
    {
        this.configuration = configuration;
    }
    ...
}
```

## App settings file sources

To use `appsettings.json` file packaged as **EmbeddedResource** in the application:

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(e)
        .Configure(
            host => host
                .UseConfiguration(
                    builder => builder
                        .EmbeddedSource<App>()
                )
        );

    Host = appBuilder.Build();
    ...
}
```

The recommended approach to specifying a configuration file source, especially when targeting Web Assembly (WASM), is to register it as an **EmbeddedResource** as described above. Configuration data read from embedded resources has the benefit of being available to the application immediately upon startup. However, it is still possible to package the file source as **Content** instead:

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    // NOT RECOMMENDED FOR WEB ASSEMBLY
    var appBuilder = this.CreateBuilder(e)
        .Configure(
            host => host
                .UseConfiguration(
                    builder => builder
                        .ContentSource<App>()
                )
        );

    Host = appBuilder.Build();
    ...
}
```

Both `EmbeddedSource` and `ContentSource` methods will also create settings files that are specific to the current environment by default, `appsettings.<hostenvironment>.json` (eg `appsettings.development.json`). This can be disabled by setting the `includeEnvironmentSettings` argument to `false` (default value is `true`):

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(e)
        .Configure(
            host => host
                .UseConfiguration(
                    builder => builder
                        .EmbeddedSource<App>(includeEnvironmentSettings: false)
                )
        );

    Host = appBuilder.Build();
}
```

> [!TIP]
> It is recommended to ensure all configuration information is read before creation of the `IHost` instance by only using `EmbeddedSource`. This will allow configuration to determine which services are created.

## Sections

Map configuration section to class and register with dependency injection (DI):

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(e)
        .Configure(
            host => host
                .UseConfiguration(
                    builder => builder.EmbeddedSource<App>()
                        .Section<CustomIntroduction>()
                )
        );
    ...
}
```

This can be accessed from any class created by the DI container:

```csharp
public class MainViewModel : ObservableObject
{
    private readonly IOptions<CustomIntroduction> customConfig;

    public MainViewModel(IOptions<CustomIntroduction> customConfig)
    {
        this.customConfig = customConfig;
    }
}
```

## Updating configuration values at runtime

The **writable configuration** feature enables the ability to update configuration values at runtime. This pattern may also be referred to as the _settings pattern_ in certain documentation.  With the `UseConfiguration()` extension method, `IWritableOptions<T>` is registered as a service. The recommended approach when specifying a set of settings for this feature is to use **configuration sections**.

Registering a configuration section for writable configuration does not require it to exist in any source. The section will be created if it does not exist.

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(e)
        .Configure(
            host => host
                .UseConfiguration(builder =>
                    builder
                        .EmbeddedSource<App>()
                        .Section<DiagnosticSettings>()
                )
        );
    ...
}
```

`DiagnosticSettings` can be defined as a record:

```csharp
public record DiagnosticSettings(bool HasBeenLaunched);
```

Modify a setting value by calling `Update()` on the injected `IWritableOptions` instance:

```csharp
public MainViewModel(IWritableOptions<DiagnosticSettings> debug)
{
    debug.Update(debugSetting =>
        debugSetting with { HasBeenLaunched = true }
    );
}
```

## References

- [Using IConfiguration](https://learn.microsoft.com/aspnet/core/fundamentals/configuration)
- [Microsoft.Extensions.Options](https://learn.microsoft.com/dotnet/api/microsoft.extensions.options)
- [Microsoft.Extensions.Configuration](https://www.nuget.org/packages/Microsoft.Extensions.Configuration)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/DatePicker.md

---
uid: Uno.Controls.DatePicker
---

# DatePicker

## Summary

`DatePicker` is used to select a specific date.

## Managed vs. native implementation

On iOS and Android the `DatePicker` by default displays using the native time picker UI. If you prefer consistent UI across all targets, you can switch to the managed implementation by setting the `UseNativeStyle` property:

```xml
<DatePicker not_win:UseNativeStyle="False" ... />
```

To include the `not_win` XAML namespace on your page follow the instructions for [Platform-specific XAML](../platform-specific-xaml.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/DependencyInjection/DependencyInjectionOverview.md

---
uid: Uno.Extensions.DependencyInjection.Overview
---

# Dependency Injection

Apps built using hosting can leverage dependency injection (DI) to register services and make them available to app dependencies. This pattern enables apps to follow sound design principles, such as [SOLID](https://en.wikipedia.org/wiki/SOLID) and [Inversion of Control](https://en.wikipedia.org/wiki/Inversion_of_control). While the host builder implements standard functionality from the [Microsoft.Extensions.DependencyInjection](https://www.nuget.org/packages/Microsoft.Extensions.DependencyInjection) library, it also provides additional features to improve the developer experience.

## Registering Services

Services are registered with the host using the `ConfigureServices` method on the `IHostBuilder`. The following snippet shows how to register a service with the host:

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host =>
        {
            host
            .ConfigureServices((context, services) =>
            {
                services.AddSingleton<SimpleService>();
            })
        });

    Host = appBuilder.Build();
    ...
}
```

Before the `IHost` instance is created, the `ConfigureServices` method is called to register services with the host. The `ConfigureServices` method is called from the lambda expression passed into the `Configure` method. `ConfigureServices` itself takes two parameters: a `HostBuilderContext` and an `IServiceCollection`. The `HostBuilderContext` provides access to the host's configuration and environment. The `IServiceCollection` is used to register services with the host.

## Resolving Services

The recommended way to resolve services is to use constructor injection. The following snippet shows how to resolve a service from the host:

```csharp
public class SimpleViewModel : ObservableObject
{
    public SimpleViewModel(ISimpleService service)
    {
        Service = service;
    }

    public ISimpleService Service { get; }
}
```

Services can also be resolved from an `IHost` instance:

```csharp
var service = Host.Services.GetService<ISimpleService>();
```

## Service Lifetimes

Services can be registered with the host using different lifetimes. The following table shows the different service lifetimes:

| Lifetime | Description |
|----------|-------------|
| `Transient` | A new instance of the service is created each time it is requested. |
| `Scoped` | A single instance of the service is created per scope. |
| `Singleton` | A single instance of the service is created for the lifetime of the host. |

Typically, services are registered with the `Singleton` lifetime.

## Named Services

Uno.Extensions provides a way to register multiple services of the same type with different names. This is useful in scenarios where multiple implementations of the same service are configured differently in an implementation factory and the correct implementation needs to be resolved at runtime. The following snippet shows how to register a named service with the host:

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host =>
        {
            host
            .ConfigureServices((context, services) =>
            {
                services.AddNamedSingleton<ISimpleService, SimpleService>("SimpleNamedServiceOne");
                services.AddNamedSingleton<ISimpleService, SimpleService>("SimpleNamedServiceTwo");
            })
        });

    Host = appBuilder.Build();
    ...
}
```

Services can be resolved by name using the `GetNamedService` extension method:

```csharp
var service = Host.Services.GetNamedService<ISimpleService>("SimpleNamedServiceOne");
```

## Service Implementation Factories

Uno.Extensions provides a way to register services using a factory method. This is useful in scenarios where the service implementation is not known until runtime. The following snippet shows how to register a service with the host using a factory method:

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host =>
        {
            host
            .ConfigureServices((context, services) =>
            {
                services.AddSingleton<ISimpleService>(serviceProvider =>
                {
                    var configuration = serviceProvider.GetRequiredService<IConfiguration>();
                    var simpleService = new SimpleService();
                    simpleService.Configure(configuration);
                    return simpleService;
                });
            })
        });

    Host = appBuilder.Build();
    ...
}
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/ElevatedView.md

---
uid: Uno.Features.ElevatedView
---

# ElevatedView

In many design languages (like [_Material Design_](https://material.io/design)), there's a notion of 'elevation' where a portion of the UI should be presented as being _elevated_ over the rest of the content.

In this case, WinUI's native elevation API can't work on all platforms because of technical limitations. To address this problem, Uno provides a control called `ElevatedView`, able to produce a similar elevated effect on all platforms (WinUI, Android, iOS, macOS, WebAssembly, and Skia).

This control is very useful for creating cards with both rounded corners and an elevated effect - which could otherwise be challenging to produce on some platforms.

## How to use the `ElevatedView`

First you need to add the `toolkit` namespace in your XAML file:

```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
```

After that, use the `ElevatedView` to host the content you need to be elevated:

```xml
<StackPanel Orientation="Horizontal" Spacing="20">

    <Button>Non-Elevated Button</Button>

    <toolkit:ElevatedView Elevation="10" Background="Gray" ShadowColor="Black">
        <Button>Elevated Button</Button>
    </toolkit:ElevatedView>

</StackPanel>
```

Will produce the following result:

![ElevatedView sample](../Assets/features/elevatedview/elevatedview-sample.png)

> **ATTENTION FOR WinUI**: When there is an error resolving the `<toolkit:ElevatedView>` on WinUI, the common mistake is to forget to include the `Uno.WinUI` package for all platforms, including WinUI. On WinUI, the only component that the `Uno.WinUI` package adds is the Toolkit.

## Settings

You can set the following properties:

* `Elevation`: numeric number representing the level of the elevation effect. Typical values are between 5 and 30. The default is `0` - no elevation.
* `ShadowColor`: By default, the shadow will be `Black`, but you can set any other value. You can reduce the shadow effect by using the alpha channel.
* `Background`: The default is `null`, which does not show a shadow. You'll need to specify a color to avoid having a shadow below a transparent surface if the stretching does not match the child.
* `CornerRadius`: Use it to create rounded corner effects. The shadow will follow them.

## Particularities

* Make sure to _give room_ for the shadow in the layout (eg. by setting a `Margin` on the `ElevatedView`).  Some platforms like macOS may clip the shadow otherwise. For the same reason, avoid wrapping the `<toolkit:ElevatedView>` directly in a `<ScrollViewer>` because it's designed to clip its content.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/ExtensionsOverview.md

---
uid: Uno.Extensions.Overview
---
# Get to a fully functional project in minutes

Uno.Extensions is a series of NuGet packages designed to encapsulate common functions when building multi-platform mobile, desktop, and web applications using Uno Platform. Thoughtfully designed components and features retain easy extensibility and customization while providing a solid foundation for your application.

The Uno.Extensions follows 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.

## Learn about Uno.Extensions features

Alongside Uno, the app template references a lineup of battle-tested packages providing key features. The resources below are available to help you get started with them in your project.

|Feature|Description|
|---|---|
|[Authentication](xref:Uno.Extensions.Authentication.HowToAuthentication)|The Uno.Extensions.Authentication package provides authentication services.|
|[Configuration](xref:Uno.Extensions.Configuration.HowToConfiguration)|The Uno.Extensions.Configuration package provides a way to configure an application based on a list of name-value pairs.|
|[Dependency injection](xref:Uno.Extensions.DependencyInjection.HowToDependencyInjection)|The Uno.Extensions.DependencyInjection package provides a simple and lightweight dependency injection system for .NET.|
|[Http](xref:Uno.Extensions.Http.Overview)|The Uno.Extensions.Http package provides configuration for native Http handlers and registration of endpoints.|
|[Localization](xref:Uno.Extensions.Localization.HowToUseLocalization)|The Uno.Extensions.Localization package provides access to localizable resources.|
|[Logging](xref:Uno.Extensions.Logging.UseLogging)|The Uno.Extensions.Logging package provides a way to log messages to a variety of output targets.|
|[Navigation](xref:Uno.Extensions.Navigation.HowToNavigateBetweenPages)|The Uno.Extensions.Navigation package provides a routing framework for navigation.|
|[Reactive](xref:Uno.Extensions.Reactive.General)|The Uno.Extensions.Reactive package provides a development framework for reactive applications.|
|[Serialization](xref:Uno.Extensions.Serialization.Overview)|The Uno.Extensions.Serialization package provides helpers for JSON serialization.|
|[Validation](xref:Uno.Extensions.Validation.Overview)|The Uno.Extensions.Validation package provides support for data validation.|

> [!TIP]
> To view more detailed information about the specific APIs leveraged in each topic, expand the Reference section in the navigation pane.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/Flyout.md

---
uid: Uno.Controls.Flyout
---

# Flyout

If you want to show a dimmed overlay underneath the flyout, set the `Flyout.LightDismissOverlayMode` property to `On`.

If you wish to customize the overlay color, add the following to your top-level `App.Resources`:

```xml
<SolidColorBrush x:Key="FlyoutLightDismissOverlayBackground"
                 Color="Blue" />
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/Frame.md

---
uid: Uno.Controls.Frame
---

# Frame

> [!TIP]
> This article covers Uno-specific information for the `Frame` class. For a full description of the feature and instructions on using it, see [Frame class](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.frame)

* Displays Page instances, supports navigation to new pages, and maintains a navigation history to support forward and backward navigation.

## Using Frame with Uno

To improve performance during navigation, `Frame` on Android, iOS, and WebAssembly targets operates in different way than in WinUI. Whereas WinUI follows `NavigationCacheMode` property on individual `Page` instances, on iOS and Android we keep the individual page instances in the back stack in memory by default. This way they can be quickly surfaced back to the user during back navigation. This behavior can be controlled using the `FeatureConfiguration.Frame.UseWinUIBehavior` property. This defaults to `true` on Skia targets and to `false` on Android, iOS and WebAssembly.

If you set `UseWinUIBehavior` to `true` on Android and iOS, you also need to override the default style for the control. You can do this by explicitly setting the `Style` to `XamlDefaultFrame`:

```xml
<Frame Style="{StaticResource XamlDefaultFrame}" />
```

Or by creating an implicit style based on `XamlDefaultFrame`:

```xml
<Style TargetType="Frame" BasedOn="XamlDefaultFrame" />
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/GLCanvasElement.md

---
uid: Uno.Controls.GLCanvasElement
---

# GLCanvasElement

> [!IMPORTANT]
> This functionality is only available on WinAppSDK and Skia Desktop (`netX.0-desktop`) targets that are running on platforms with support for hardware acceleration. On Windows and Linux, OpenGL 3.0+ is used directly and on macOS, Metal is used through the [ANGLE](https://en.wikipedia.org/wiki/ANGLE_(software)) library.

`GLCanvasElement` is a control for drawing 3D graphics with OpenGL. It can be enabled by adding the [`GLCanvas` UnoFeature](xref:Uno.Features.Uno.Sdk). The OpenGL APIs provided are provided by [Silk.NET](https://dotnet.github.io/Silk.NET/).

## Using the GLCanvasElement

To use `GLCanvasElement`, create a subclass of `GLCanvasElement` and override the abstract methods `Init`, `RenderOverride` and `OnDestroy`.

```csharp
protected GLCanvasElement(Func<Window> getWindowFunc);

protected abstract void Init(GL gl);
protected abstract void RenderOverride(GL gl);
protected abstract void OnDestroy(GL gl);
```

These three abstract methods take a `Silk.NET.OpenGL.GL` parameter that can be used to make OpenGL calls.

### The GLCanvasElement constructor

The protected constructor requires a `Func<Window>` argument that fetches the `Microsoft.UI.Xaml.Window` object that the `GLCanvasElement` belongs to. This function is required because WinUI doesn't yet provide a way to get the `Window` of a `FrameworkElement`. This parameter is ignored on Uno Platform and can be set to null. This function is only called while the `GLCanvasElement` is still in the visual tree.

### The `Init` method

The `Init` method is a regular OpenGL setup method that you can use to set up the needed OpenGL objects, like textures, Vertex Array Buffers (VAOs), Element Array Buffers (EBOs), etc.  The `OnDestroy` method is the complement of `Init` and is used to clean up any allocated resources. `Init` and `OnDestroy` might be called multiple times alternatingly. In other words, 2 `OnDestroy` calls are guaranteed to have an `Init` call in between and vice versa.

### The `RenderOverride` method

The `RenderOverride` is the main render-loop function. When adding your drawing logic in `RenderOverride`, you can assume that the OpenGL viewport rectangle is already set and its dimensions are equal to the `RenderSize` of the `GLCanvasElement`.

### macOS Specifics

On MacOS, since OpenGL support is not natively present, we use [ANGLE](https://en.wikipedia.org/wiki/ANGLE_(software)) to provide OpenGL ES support. This means that we're actually using OpenGL ES 3.00, not OpenGL. Due to the similarity between desktop OpenGL and OpenGL ES, (almost) all the OpenGL ES functions are present in the `Silk.NET.OpenGL.GL` API surface and therefore we can use the same class to represent both the OpenGL and OpenGL ES APIs. To run the same `GLCanvasElement` subclasses on all supported platforms, make sure to use a subset of functions that are present in both APIs (which is almost all of OpenGL ES).

## Invalidating the canvas

Additionally, `GLCanvasElement` has an `Invalidate` method that requests a redrawing of the `GLCanvasElement`, calling `RenderOverride` in the process. Note that `RenderOverride` will only be called once per `Invalidate` call and the output will be saved to be used in future frames. To update the output, you must call `Invalidate`. If you need to continuously update the output (e.g. in an animation), you can add an `Invalidate` call inside `RenderOverride`.

## Detecting errors

To detect errors in initializing the OpenGL environment, `GLCanvasElement` exposes an `IsGLInitializedProperty` dependency property that shows whether or nor the loading of the element and its OpenGL setup were successful. This property is only valid when the element is loaded, i.e. its `IsLoaded` property is true. When the element is not loaded, the value of `IsGLInitialized` will be null. `GLCanvasElement` implements `INotifyPropertyChanged`, so you can use this property in a data bindings, for example to set the visibility of a control as a fallback. Attempting to change this property is illegal.

## How to use Silk.NET

To learn more about using [Silk.NET](https://www.nuget.org/packages/Silk.NET.OpenGL/) as a C# binding for OpenGL, see the [examples in the Silk.NET repository](https://github.com/dotnet/Silk.NET/tree/main/examples/CSharp). Note that the windowing and inputs APIs in Silk.NET are not relevant to `GLCanvasElement`, since we only use Silk.NET as an OpenGL binding library, not a windowing library.

## Full example

To see this in action, here's a complete sample that uses `GLCanvasElement` to draw a triangle. Note how you have to be careful with surrounding all the OpenGL-related logic in platform-specific guards. This is the case for both the [XAML](platform-specific-xaml) and the [code-behind](platform-specific-csharp). For complete C# projects, visit our [GLCanvasElement Samples in the Uno.Samples repository](https://aka.platform.uno/glcanvaselement-sample).

XAML:

```xaml
<!-- GLCanvasElementExample.xaml -->
<UserControl x:Class="BlankApp.GLCanvasElementExample"
             xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
             xmlns:local="using:BlankApp"
             xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
             xmlns:skia="http://uno.ui/skia#using:UITests.Shared.Windows_UI_Composition"
             xmlns:not_skia="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:win="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:not_win="http://uno.ui/not_win"
             mc:Ignorable="skia not_win">

    <Grid>
        <skia:SimpleTriangleGlCanvasElement />
        <win:Grid>
            <local:SimpleTriangleGlCanvasElement />
        </win:Grid>
        <not_win:Grid>
            <not_skia:TextBlock Text="This sample is only supported on skia targets and WinUI." />
        </not_win:Grid>
    </Grid>
</UserControl>
```

Code-behind:

```csharp
// GLCanvasElementExample.xaml.cs
public partial class GLCanvasElementExample : UserControl
{
    public GLCanvasElementExample()
    {
        this.InitializeComponent();
    }
}
```

```csharp
// GLTriangleElement.cs
#if DESKTOP || WINDOWS
// https://learnopengl.com/Getting-started/Hello-Triangle
public class SimpleTriangleGlCanvasElement()
    // Assuming that App.xaml.cs has a static property named MainWindow
    : GLCanvasElement(() => App.MainWindow)
{
    private uint _vao;
    private uint _vbo;
    private uint _program;

    unsafe protected override void Init(GL gl)
    {
        _vao = gl.GenVertexArray();
        gl.BindVertexArray(_vao);

        float[] vertices =
        {
            0.5f, -0.5f, 0.0f,  // bottom right
            -0.5f, -0.5f, 0.0f,  // bottom left
            0.0f,  0.5f, 0.0f   // top
        };

        _vbo = gl.GenBuffer();
        gl.BindBuffer(BufferTargetARB.ArrayBuffer, _vbo);
        gl.BufferData(BufferTargetARB.ArrayBuffer, new ReadOnlySpan<float>(vertices), BufferUsageARB.StaticDraw);

        gl.VertexAttribPointer(0, 3, GLEnum.Float, false, 3 * sizeof(float), (void*)0);
        gl.EnableVertexAttribArray(0);

        var slVersion = gl.GetStringS(StringName.ShadingLanguageVersion);
        var versionDef = slVersion.Contains("OpenGL ES", StringComparison.InvariantCultureIgnoreCase)
            ? "#version 300 es"
            : "#version 330";
        var vertexCode =
        $$"""
        {{versionDef}}
        precision highp float; // for OpenGL ES compatibility

        layout (location = 0) in vec3 aPosition;
        out vec4 vertexColor;

        void main()
        {
         gl_Position = vec4(aPosition, 1.0);
         vertexColor = vec4(aPosition.x + 0.5, aPosition.y + 0.5, aPosition.z + 0.5, 1.0);
        }
        """;

        var fragmentCode =
        $$"""
        {{versionDef}}
        precision highp float; // for OpenGL ES compatibility

        out vec4 out_color;
        in vec4 vertexColor;

        void main()
        {
            out_color = vertexColor;
        }
        """;

        uint vertexShader = gl.CreateShader(ShaderType.VertexShader);
        gl.ShaderSource(vertexShader, vertexCode);
        gl.CompileShader(vertexShader);

        gl.GetShader(vertexShader, ShaderParameterName.CompileStatus, out int vStatus);
        if (vStatus != (int)GLEnum.True)
        {
            throw new Exception("Vertex shader failed to compile: " + gl.GetShaderInfoLog(vertexShader));
        }

        uint fragmentShader = gl.CreateShader(ShaderType.FragmentShader);
        gl.ShaderSource(fragmentShader, fragmentCode);
        gl.CompileShader(fragmentShader);

        gl.GetShader(fragmentShader, ShaderParameterName.CompileStatus, out int fStatus);
        if (fStatus != (int)GLEnum.True)
        {
            throw new Exception("Fragment shader failed to compile: " + gl.GetShaderInfoLog(fragmentShader));
        }

        _program = gl.CreateProgram();
        gl.AttachShader(_program, vertexShader);
        gl.AttachShader(_program, fragmentShader);
        gl.LinkProgram(_program);

        gl.GetProgram(_program, ProgramPropertyARB.LinkStatus, out int lStatus);
        if (lStatus != (int)GLEnum.True)
        {
            throw new Exception("Program failed to link: " + gl.GetProgramInfoLog(_program));
        }

        gl.DetachShader(_program, vertexShader);
        gl.DetachShader(_program, fragmentShader);
        gl.DeleteShader(vertexShader);
        gl.DeleteShader(fragmentShader);
    }

    protected override void OnDestroy(GL gl)
    {
        gl.DeleteVertexArray(_vao);
        gl.DeleteBuffer(_vbo);
        gl.DeleteProgram(_program);
    }

    protected override void RenderOverride(GL gl)
    {
        gl.ClearColor(Color.Black);
        gl.Clear(ClearBufferMask.ColorBufferBit);

        gl.UseProgram(_program);

        gl.BindVertexArray(_vao);
        gl.DrawArrays(PrimitiveType.Triangles, 0, 3);
    }
}
#endif
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Hosting/HostingOverview.md

---
uid: Uno.Extensions.Hosting.Overview
---
# Hosting

`Hosting` provides an implementation of the abstraction for building applications which support initialization of dependencies, establishing different environment types, and the full breadth of extensible features offered by Uno.Extensions.

Hosting is provided as an Uno Feature. To enable `Hosting` support in your application, add `Hosting` to the `<UnoFeatures>` property in the Class Library (.csproj) file. For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

[!include[existing-app](../includes/existing-app.md)]

[!include[single-project](../includes/single-project.md)]

[!include[getting-help](../includes/getting-help.md)]

## Building a Hosted Application

Initialization of the `IHost` instance is done from the generated App.cs file of your solution. It should be created as soon as the application is launched. The following snippet uses the `CreateBuilder()` extension method to instantiate an `IApplicationBuilder` from your `Application`. It is then possible to configure the associated `IHostBuilder` to register services or use the numerous extensions offered by this library.

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host => {
            // Configure the host builder
        });

    Host = appBuilder.Build();
    ...
}
```

For a more specific tutorial about getting started with building hosted applications, see [Get Started with Hosting](xref:Uno.Extensions.Hosting.HowToHostingSetup).

## Service Initialization

Services are the primary way to access application functionality. Services are registered with the host using the `ConfigureServices` method on the `IHostBuilder`. Some services need to be created and initialized as soon as possible after the `IHost` has been built. The `IServiceInitialize` interface identifies services that need to be created and initialize immediately after the `IHost` instance is created.

```csharp
public interface IServiceInitialize
{
    void Initialize();
}
```

> [!TIP]
> Avoid using the `IServiceInitialize` interface unless absolutely required as it will add to the startup time for the application. It's recommended to implement the `IHostedService` interface for services that can be created and started asynchronously (see next section).

## Async Initialization with IHostedService

The initialization of the application hosting is intentionally a synchronous process which makes it unsuitable for long running initialization code. Asynchronous initialization can be done by registering an implementation of `IHostedService`.

```csharp
public class SimpleHostService : IHostedService
{
    public Task StartAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }
}
```

The implementation can be registered during the host initialization by calling the `AddHostedService` method on the `IServiceCollection` returned by the `ConfigureServices` method on the `IHostBuilder`.

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host => {
            host
            .ConfigureServices((context, services) =>
            {
                services.AddHostedService<SimpleHostService>()
            })
        });

    Host = appBuilder.Build();
}
...
```

In order for hosted services to be run, it is necessary to run the `IHost` implementation. It's recommended to do this in the OnLaunched method of the App.cs. This will ensure the application instance and associated window are accessible, should initialization of anything related to the UI be required.

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    ...
    await Task.Run(() => Host.StartAsync());
}
```

If a hosted service is required to complete startup prior to the first navigation (if using [Navigation](xref:Uno.Extensions.Navigation.Overview)), implement the `IStartupService` interface. A task will be returned that can be awaited in the `StartupComplete` method. This technique might be useful for pre-loading data in order to work out which view to navigate to.

```csharp
public class SimpleStartupService : IHostedService, IStartupService
{
    private TaskCompletionSource<object> _completion = new TaskCompletionSource<object>();
    public Task StartAsync(CancellationToken cancellationToken)
    {
        _completion.SetResult(true);
        return Task.CompletedTask;
    }

    public Task StopAsync(CancellationToken cancellationToken)
    {
        return Task.CompletedTask;
    }

    public Task StartupComplete()
    {
        return _completion.Task;
    }
}
```

## Hosting Environments

As part of initializing the host, an instance of `IHostEnvironment` is registered and can be retrieved to determine information about the current hosting environment.

```csharp
var env = Host.Services.GetService<IHostEnvironment>();
Debug.WriteLine($"Environment: {env.EnvironmentName}");
```

The current hosting environment can be changed with the `UseEnvironment()` extension method.

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host => {
            host
            .UseEnvironment("Staging")
        });

    Host = appBuilder.Build();
...
```

The current hosting environment can also be used when configuring the host builder.

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host => {
            host
            .ConfigureServices((context, services) =>
            {
                var isDevelopment = context.HostingEnvironment.IsDevelopment();
                var isStaging = context.HostingEnvironment.IsStaging();
                var isProduction = context.HostingEnvironment.IsProduction();
                var environment = context.HostingEnvironment.EnvironmentName;
                var isMyEnvironment = context.HostingEnvironment.IsEnvironment("MyEnvironment");
            })
        });

    Host = appBuilder.Build();
...
```

> [!TIP]
> Avoid writing code that contains logic specific to any environment. All environments should behave as close as possible to each other to minimize any environment specific bugs that may be introduced by environment specific code.
>
> Any environment specific secure variables (such as service URLs, application keys, account information) should be set as part of a multi-environment CI/CD pipeline. Non-secure per-environment variables can be included using a settings file which is covered in [Configuration](xref:Uno.Extensions.Configuration.Overview).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Navigation/HowTo-DefineRoutes.md

---
uid: Uno.Extensions.Navigation.HowToDefineRoutes
---

# How-To: Define Routes

Routes provide an easy and dynamic way of navigating through your app, either via code-behind or XAML. They are particularly useful when your application has a high degree of complexity in terms of navigation, especially when dealing with nested pages using TabBars and NavigationViews. In such cases, there are multiple levels of navigation rather than just one level, as in an application that simply navigates between, for instance, a Welcome page, Login page, Main page, and Second page.

This topic walks through the process of defining routes.

## Step-by-step

> [!IMPORTANT]
> This guide assumes you used the template wizard or `dotnet new unoapp` to create your solution. If not, it is recommended that you follow the [Creating an application with Uno.Extensions article](xref:Uno.Extensions.HowToGettingStarted) to create an application from the template.

### Understanding routes

In a new app with Navigation, you'll find some pre-set views: `Shell`, `MainPage`, and `SecondPage`. `Shell` acts as the main frame where views are set and navigation begins. When the app launches, it opens `MainPage`, which then leads to `SecondPage`.

So if we take a look at the `RegisterRoutes` method in the `App.xaml.cs` file, we can see how these pages are organized in terms of routes:

```csharp
private static void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
{
    views.Register(
        new ViewMap(ViewModel: typeof(ShellViewModel)),
        new ViewMap<MainPage, MainViewModel>(),
        new DataViewMap<SecondPage, SecondViewModel, Entity>()
    );

    routes.Register(
        new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
            Nested:
            [
                new ("Main", View: views.FindByViewModel<MainViewModel>()),
                new ("Second", View: views.FindByViewModel<SecondViewModel>()),
            ]
        )
    );
}
```

Firstly, we see that the views are registered using a `ViewMap` object. This object is also responsible for associating each View with its corresponding ViewModel. Next, we observe that the routes are being registered. Here, we can see that "Main" and "Second" are nested pages within "Shell", and both are at the same level. So if we take a look at the flow of the app, `ShellViewModel` opens `MainPage`, which in turn contains a button that navigates to `SecondPage`.

### ViewMap

When registering routes, we can take advantage of the `ViewMap` object and its variations `DataViewMap` and `ResultDataViewMap`, to correlate Views with ViewModels, specify the type of parameters ViewModels may take, and specify the type of return coming from a navigation.

Let's explore each of these arguments and how to effectively implement them:

1. **View** - The type of the View being registered. Example:

    ```csharp
    new ViewMap<MainPage>()
    ```

1. **ViewModel** - The type of the ViewModel being associated with the View. Example:

    ```csharp
    new ViewMap<MainPage, MainViewModel>()
    ```

    This correlation between View and ViewModel allows navigation through ViewModels. For example, when navigating to `MainPage` the following call could be made:

    ```csharp
     _navigator.NavigateViewModelAsync<MainViewModel>(this);
     ```

1. **Data** - In addition to associating Views with ViewModels, the Data type can also be associated with ViewModels. This Data type will be injected into the ViewModel constructor when an instance is created. To achieve this, we use the `DataViewMap` object instead of `ViewMap`.

    For example, let's say we have a `Product` class that holds product information, and we use `ProductDetailPage` to display the product details. We can register it as follows:

    ```csharp
    new DataViewMap<ProductDetailPage, ProductDetailViewModel, Product>()
    ```

    This allows navigation through data, for example when navigating to `ProductDetailPage` the following call could be made:

    ```csharp
    // Where `myProduct` is of type `Product`
    _navigator.NavigateDataAsync(this, myProduct);
    ```

    > [!NOTE]
    > In order to achieve this, ensure that your ViewModel constructor accepts the data type as a parameter.

1. **ResultData** - Defines an association between the view and the type of data being requested. For example, if you're navigating to a page that has a list of products and that page should return a product that was selected by the user you can achieve it by associating the `Product` type to the View and ViewModel using `ResultDataViewMap`:

    ```csharp
    new ResultDataViewMap<ProductsPage, ProductsViewModel, Product>()
    ```

    Then, when navigating to the `ProductsPage` and requesting a product from this navigation you can do:

    ```csharp
    public async Task GoToProductsPage()
    {
        var product = await _navigator.GetDataAsync<Product>(this);
    }
    ```

1. **FromQuery** - Used to convert a query parameter into entities when using deep linking.

    For example, let's say you have a route called "Product" which is associated with the `ProductDetailPage`. When navigating through a deep linking, you can reach that page by specifying the route name and the product you want to show by providing its ID. The way of converting the ID provided by the query string to a `Product` can be achieved with the `FromQuery` parameter, as follows:

    ```csharp
    new DataViewMap<ProductDetailPage, ProductDetailViewModel, Product>(
        FromQuery: async (sp, query) =>
        {
            var productService = sp.GetRequiredService<IProductService>();
            var id = query[nameof(Product.Id)];
            return await productService.GetById(id, default);
        }
    )
    ```

1. **ToQuery** - Used to convert entities into a query parameter.

    Following the same logic of the previous example, you can use the `ToQuery` parameter to provide the logic to convert the `Product` into a query string:

    ```csharp
    new DataViewMap<ProductDetailPage, ProductDetailViewModel, Product>(
        ToQuery: product => new Dictionary<string, string>
        {
            { nameof(Product.Id), $"{product.Id}" }
        }
    )
    ```

> [!NOTE]
> `FromQuery` and `ToQuery` are only available when using `DataViewMap`.

### RouteMap

RouteMaps are especially useful for managing complex navigation systems, including those with nested views. When defining routes, we utilize the `RouteMap` object. This object's constructor takes six arguments. Let's explore each of these arguments and how to effectively implement them:

#### Path

The first parameter is **Path**, serving as the identifier for the route. When navigating within your app using routes, this is the reference you'll use to reach the corresponding view.

> [!IMPORTANT]
> When creating route names, please use only alphanumeric characters (letters and numbers). Avoid using special characters such as punctuation marks, symbols, or spaces. Using special characters may lead to incorrect or invalid navigation.

When defining route names, it's crucial to choose names carefully to avoid potential conflicts and errors. Certain names, such as "List", "Grid", or "Page" could unintentionally resolve to existing control, element, or class names within the application. For example, a route named "List" might be mistakenly resolved as a "ListView" class, leading to an incorrect path and causing errors in navigation. To avoid these issues, it's best to avoid using common names that might conflict with existing control or class names in the application. Here are some examples of names to avoid:

**Names that could be mistaken for controls, elements, or components:**

- Scroll
- List
- Grid
- Tree
- Web
- Navigation
- Content
- User
- Items
- Menu

**Suffixes that could possibly resolve in an existing class:**

- Page
- Model
- ViewModel
- Service
- Helper
- Converter
- Manager
- Handler
- Exception
- Extension
- Settings

#### View

The **View** parameter refers to the view associated with the route. The view must be registered beforehand within the `IViewRegistry`, and you can establish the association using the `FindByViewModel` method. Note in the following example how we add a route for a new page called `LoginPage`:

```csharp
protected override void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
{
    views.Register(
        new ViewMap(ViewModel: typeof(ShellViewModel)),
        new ViewMap<LoginPage, LoginViewModel>()
    );

    routes.Register(
        new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
            Nested:
            [
                new ("Login", View: views.FindByViewModel<LoginViewModel>())
            ]
        )
    );
}
```

Note that adding a view is not mandatory. You can specify a route without a view. For example, if you want to add routes for the content of a `TabBar`, you can define the routes without the view, and in your markup file, you can use the attached property `uen:Region.Name` to bind the content view with the defined route.

Given the following routes:

```csharp
// Omitted for brevity
new RouteMap("Main", View: views.FindByViewModel<MainViewModel>(),
    Nested:
    [
        new ("ForYouTab"),
        new ("FavoritesTab")
    ]
)
```

We can specify the content view using the `uen:Region.Name` to link it to the given route name:

```xml
xmlns:uen="using:Uno.Extensions.Navigation.UI"

<Grid uen:Region.Attached="True">
    <utu:TabBar uen:Region.Attached="True">
        <utu:TabBarItem Content="For You"
                        uen:Region.Name="ForYouTab" />
        <utu:TabBarItem Content="Favorites"
                        uen:Region.Name="FavoritesTab"/>
    </utu:TabBar>
    <Grid uen:Region.Attached="True"
        uen:Region.Navigator="Visibility">
        <ListView uen:Region.Name="ForYouTab"
                ItemsSource="{Binding Items}">
            <ListView.ItemTemplate>
                <DataTemplate>
                    <TextBlock Text="{x:Bind Name}" />
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
        <Grid uen:Region.Name="FavoritesTab">
            <TextBlock Text="Favorites go here" />
        </Grid>
    </Grid>
</Grid>
```

In that example, we used the `uen:Region.Name` attached property on the `ListView` to associate it with the route named "ForYouTab" as defined in the `RouteMap`. Similarly, the `Grid` was linked to the "FavoritesTab" route using the same attached property.

#### Nested

The **Nested** property allows you to define hierarchical routes. It creates a parent-child relationship between routes. This helps organize navigation structure and manage complex navigation scenarios more effectively, for example when using `TabBar` or `NavigationView`. In the following example `MainPage` has two nested routes, that represents tabs within `MainPage`: "ForYouTab" and "FavoritesTab":

```csharp
protected override void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
{
    views.Register(
        new ViewMap(ViewModel: typeof(ShellViewModel)),
        new ViewMap<LoginPage, LoginViewModel>(),
        new ViewMap<MainPage, MainViewModel>()
    );

    routes.Register(
        new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
            Nested:
            [
                new ("Login", View: views.FindByViewModel<LoginViewModel>()),
                new ("Main", View: views.FindByViewModel<MainViewModel>(),
                    Nested:
                    [
                        new ("ForYouTab"),
                        new ("FavoritesTab")
                    ]
                )
            ]
        )
    );
}
```

#### IsDefault

**IsDefault** will make the navigator automatically shows that route when dealing with nested views. For example, imagine a scenario where you are defining routes within a `NavigationView`, such as nested routes inside a `MainPage`. You can set one of these routes as the default by setting `IsDefault: true`. This ensures that the specified route is automatically navigated to when the page is displayed.

```csharp
// Omitted for brevity
new RouteMap("Main", View: views.FindByViewModel<MainViewModel>(),
    Nested:
    [
        new ("ForYouTab", IsDefault: true),
        new ("FavoritesTab")
    ]
)
```

#### DependsOn

**DependsOn** enables you to establish a dependency between two views. This argument expects a route name and ensures that when you navigate to a view with dependencies, the dependent view will be navigated to first before opening the requested view. This is especially useful when using deep linking to navigate through pages. In the following example we add a new page called `ProductsPage` and we set this page as dependent of `MainPage`:

```csharp
protected override void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
{
    views.Register(
        // Omitted for brevity
        new ViewMap<ProductsPage, ProductsViewModel>()
    );

    routes
        .Register(
            new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
                Nested:
                [
                    // Omitted for brevity
                    new ("Main", View: views.FindByViewModel<MainViewModel>()),
                    new ("Products", View: views.FindByViewModel<ProductsViewModel>(), DependsOn: "Main"),
                ]
            )
        );
}
```

#### Init

**Init** allows you to customize the navigation request, enabling specific actions before displaying the associated view. For example, you can override the navigation request if the user is not logged in:

```csharp
new ("Login", View: views.FindByViewModel<LoginViewModel>()),
new ("Main", View: views.FindByViewModel<MainViewModel>(),
    Init: (request) => 
    {
        // Check if the user is logged in
        if (!User.IsLoggedIn())
        {
            // Redirect to the Login page if the user is not logged in
            request = request with { Route = Route.PageRoute("Login") };
        }
        return request;
    }),
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Navigation/HowTo-DisplayItem.md

---
uid: Uno.Extensions.Navigation.HowToDisplayItem
---
# How-To: Display Item Details

This topic walks through how to use Navigation to display the details of an item selected from a list. This demonstrates an important aspect of Navigation which is the ability to pass data as part of a navigation request.

[!include[getting-help](../includes/mvvm-approach.md)]

## Step-by-step

[!include[create-application](../includes/create-application.md)]

Often it is necessary to pass a data item from one page to another. This scenario will start with passing a newly created object along with the navigation request, and how the specified object can be accessed by the destination ViewModel.

### 1. Define the type of data to pass

- Define a `Widget` record (or class) for data to be passed between view models

    ```csharp
    public record Widget(string Name, double Weight);
    ```

- Change the `ViewMap` in `App.xaml.cs` that associates the `SecondPage` and `SecondViewModel`, to be a `DataViewMap` object that allows you to specify the `Widget` type.

    ```csharp
    new DataViewMap<SecondPage, SecondViewModel, Widget>()
    ```

### 2. Pass data when navigating

- Create a `Widget` inside the `GoToSecondPage` method in `MainViewModel.cs`, and pass it as `data` into the navigation method.

    ```csharp
    public async Task GoToSecondPage()
    {
        var widget = new Widget("CrazySpinner", 34.0);

        await _navigator.NavigateViewModelAsync<SecondViewModel>(this, data: widget);
    }
    ```

### 3. Receiving navigation data

- Update the `SecondViewModel` constructor to accept a `Widget` parameter.

    ```csharp
    public class SecondViewModel
    {
        public string Name { get; }

        public SecondViewModel(Widget widget)
        {
            Name = widget.Name;
        }
    }
    ```

- Add a `TextBlock` to `SecondPage.xaml`

    ```xml
    <TextBlock HorizontalAlignment="Center"
               VerticalAlignment="Center">
        <Run Text="Widget Name:" />
        <Run Text="{Binding Name}" />
    </TextBlock>
    ```

### 4. Navigating with data

- Because there's a mapping between the `Widget` and the `SecondViewModel` (in the `ViewMap` defined in `App.xaml.cs`), an alternative way to navigate is by calling the `NavigateDataAsync` and specifying the data object to pass in the navigation request. The type of the data object will be used to resolve which route to navigate to.

    ```csharp
    await _navigator.NavigateDataAsync(this, data: widget);
    ```

### 5. Navigating for selected value in a `ListView`

A common application scenario is to present a list of items, for example presented in a `ListView`. When the user selects an item, the application navigates to a new view in order to display the details of that item.

- Add a `Widgets` property to your `MainViewModel`

    ```csharp
    public Widget[] Widgets { get; } =
    [
        new Widget("NormalSpinner", 5.0),
        new Widget("HeavySpinner", 50.0)
    ];
    ```

- Update `MainPage.xaml` to replace the `Button` with a `ListView` which has the `ItemsSource` property data bound to the `Widgets` property. The `Navigation.Request` property defines the route that will be navigated to when an item in the `ListView` is selected.

    ```xml
    <ListView ItemsSource="{Binding Widgets}"
              uen:Navigation.Request="Second"
              Grid.Row="1"
              HorizontalAlignment="Center"
              VerticalAlignment="Center">
        <ListView.ItemTemplate>
            <DataTemplate>
                <StackPanel Orientation="Horizontal"
                            Padding="10">
                    <TextBlock Text="{Binding Name}" />
                    <TextBlock Text="{Binding Age}" />
                </StackPanel>
            </DataTemplate>
        </ListView.ItemTemplate>
    </ListView>
    ```

### 6. Navigating based on the type of data (again!)

If you have a `ListView` that has items of different types, the navigation route can be based on the type of selected item.

- Change the `Navigation.Request` property value to `""`. Navigation will use the type of the selected item to determine what route to use.

- Add two additional records, `BasicWidget` and `AdvancedWidget`, that derive from `Widget`.

    ```csharp
    public record Widget(string Name, double Weight);

    public record BasicWidget(string Name, double Weight) : Widget(Name, Weight);

    public record AdvancedWidget(string Name, double Weight) : Widget(Name, Weight);
    ```

- Change the `Widgets` property in `MainViewModel` to include an array of different types of widgets.

    ```csharp
    public Widget[] Widgets { get; } = 
    [
        new BasicWidget("NormalSpinner", 5.0),
        new AdvancedWidget("HeavySpinner", 50.0)
    ];
    ```

- Clone the `SecondPage.xaml` and `SecondPage.xaml.cs` files, and rename the files to `ThirdPage.xaml` and `ThirdPage.xaml.cs` respectively. Make sure you also change the class name in both files from `SecondPage` to `ThirdPage`, as well as the `Content` property of the `NavigationBar` to read "Third Page".
- Clone `SecondViewModel.cs` and rename to `ThirdViewModel.cs`. Also rename the class from `SecondViewModel` to `ThirdViewModel`
- Change the constructor of both the `SecondViewModel` and `ThirdViewModel` to accept widgets of different types

    ```csharp
    public class SecondViewModel
    {
        public string Name { get; }

        public SecondViewModel(BasicWidget widget)
        {
            Name = widget.Name;
        }
    }

    public class ThirdViewModel
    {
        public string Name { get; }

        public ThirdViewModel(AdvancedWidget widget)
        {
            Name = widget.Name;
        }
    }
    ```

- Add a `DataViewMap` and `RouteMap` for `ThirdPage` and `ThirdViewModel`, specifying the `AdvancedWidget`. Also, update `DataViewMap` for `SecondViewModel` to be `BasicWidget` instead of `Widget`

    ```csharp
    private static void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
    {
        views.Register(
            new ViewMap(ViewModel: typeof(ShellViewModel)),
            new ViewMap<MainPage, MainViewModel>(),
            new DataViewMap<SecondPage, SecondViewModel, BasicWidget>(),
            new DataViewMap<ThirdPage, ThirdViewModel, AdvancedWidget>()
        );

        routes.Register(
            new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
                Nested:
                [
                    new ("Main", View: views.FindByViewModel<MainViewModel>()),
                    new ("Second", View: views.FindByViewModel<SecondViewModel>()),
                    new ("Third", View: views.FindByViewModel<ThirdViewModel>()),
                ]
            )
        );
    }
    ```

- Picking an item from the list will either open `SecondPage` or `ThirdPage` based on the type of item selected.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Navigation/HowTo-DisplayMessageDialog.md

---
uid: Uno.Extensions.Navigation.HowToDisplayMessageDialog
---
# How-To: Display a Message Dialog

This topic walks through using Navigation to display a prompt using a `MessageDialog`. This can also be used for simple user interactions, such as a confirmation dialog, where the user is prompted with an Ok/Cancel, or Yes/No, question.

[!include[getting-help](../includes/mvvm-approach.md)]

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. Show an ad-hoc `MessageDialog`

- Update the existing `Button` on `MainPage.xaml`

    ```xml
    <Button Content="Show Simple Message Dialog"
            Click="{x:Bind ViewModel.ShowSimpleDialog}"
            Grid.Row="1"
            HorizontalAlignment="Center"
            VerticalAlignment="Center" />
    ```

- Add `ShowSimpleDialog` method to `MainViewModel`

    ```csharp
    public async Task ShowSimpleDialog()
    {
        _ = _navigator.ShowMessageDialogAsync(this, title: "This is Uno", content: "Hello Uno.Extensions!");
    }
    ```

    Run the application to see a `MessageDialog` displayed when you click the `Button`.

    ![Screenshot of a simple MessageDialog](images/BasicMessageDialog.png)

### 2. Accessing the `MessageDialog` response

- Change code in the `ShowSimpleDialog` method to await response

    ```csharp
    public async Task ShowSimpleDialog()
    {
        var result = await _navigator.ShowMessageDialogAsync<string>(this, title: "This is Uno", content: "Hello Uno.Extensions!");
    }
    ```

- Modify the `ShowMessageDialogAsync` method call to specify multiple buttons.

    ```csharp
    public async Task ShowSimpleDialog()
    {
        var result = await _navigator.ShowMessageDialogAsync<string>(
            this,
            title: "This is Uno",
            content: "Hello Uno.Extensions!",
            buttons:
            [
                new DialogAction("Ok"),
                new DialogAction("Cancel")
            ]);
    }
    ```

    The `result` variable will be set to the label of the selected button.

    ![Screenshot of the MessageDialog result](images/MessageDialogResult.png)

### 3. Using predefined `MessageDialog`

If you want to use the same `MessageDialog` in different places in your application you can define a `MessageDialogViewMap` and then reference it by the route you assign to it.

- Create a `MessageDialogViewMap` instance and register it with both `views` and `routes` in `App.xaml.cs`

    ```csharp
    private static void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
    {
        var messageDialog = new MessageDialogViewMap(
            Title: "This is Uno",
            Content: "Hello Uno.Extensions",
            Buttons:
            [
                new DialogAction(Label:"Yes"),
                new DialogAction(Label:"No")
            ]
        );

        views.Register(
            new ViewMap(ViewModel: typeof(ShellViewModel)),
            new ViewMap<MainPage, MainViewModel>(),
            new DataViewMap<SecondPage, SecondViewModel, Entity>(),
                messageDialog
            );

        routes.Register(
            new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
                Nested:
                [
                    new RouteMap("Main", View: views.FindByViewModel<MainViewModel>()),
                    new RouteMap("Second", View: views.FindByViewModel<SecondViewModel>()),
                    new RouteMap("MyMessage", View: messageDialog)
                ]
            )
        );
    }
    ```

- In `MainViewModel` change the `ShowMessageDialogAsync` method to specify the `route` argument, which should be the route specified in the `RouteMap`

    ```csharp
    var result = await _navigator.ShowMessageDialogAsync<string>(this, route: "MyMessage");
    ```

### 4. Localize the `MessageDialog`

- For a localized `MessageDialog` create a `LocalizableMessageDialogViewMap` instance and register it with both `views` and `routes` (as per previous step). Note that each of the properties in the `LocalizableMessageDialogViewMap` that were a simple `string` in the `MessageDialogViewMap`, are now call-back methods that provide an `IStringLocalizer` instance.

    ```csharp
    var localizedMessageDialog = new LocalizableMessageDialogViewMap(
        Content: localizer => localizer?["MyDialog_Content"] ?? string.Empty,
        Buttons:
        [
            new LocalizableDialogAction(LabelProvider: localizer => localizer?["Dialog_Ok"] ?? string.Empty),
            new LocalizableDialogAction(LabelProvider: localizer => localizer?["Dialog_Cancel"] ?? string.Empty)
        ]
    );
    ```

- Add resources for `MyDialog_Content`, `Dialog_Ok`, and `Dialog_Cancel` to `Resources.resw`
    ![Localized MessageDialog resources](images/LocalizedMessageDialogResources.png)

- Make sure the `UseLocalization` extension method is called in the `OnLaunched` method in `App.xaml.cs`

    ```csharp
    protected async override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var builder = this.CreateBuilder(args)
            .UseToolkitNavigation()
            .Configure(host => host
            // ... omitted for brevity
            .UseLocalization()
            // ... omitted for brevity
    }
    ```

- In `MainViewModel` change the `ShowMessageDialogAsync` method to use the `MyLocalizedMessage` route (this route should match the name of the route that was added to the `routes` earlier).

    ```csharp
    var result = await _navigator.ShowMessageDialogAsync<string>(this, route: "MyLocalizedMessage");
    ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Http/HowTo-Kiota.md

---
uid: Uno.Extensions.Http.HowToKiota
---
# How-To: Quickly create and register a Kiota Client for an API

When working with APIs in your application, having a strongly-typed client can simplify communication and reduce boilerplate code. **Kiota** is a tool that generates strongly-typed API clients from Swagger/OpenAPI definitions. With Uno.Extensions, you can easily register and use Kiota clients in your Uno Platform app without additional setup.

## Step-by-Step Guide

> [!IMPORTANT]
> This guide assumes you used the template wizard or `dotnet new unoapp` to create your solution. If not, it is recommended that you follow the [**Creating an application with Uno.Extensions** documentation](xref:Uno.Extensions.HowToGettingStarted) to create an application from the template.

### 1. Installation

* Add `HttpKiota` to the `<UnoFeatures>` property in the Class Library (`.csproj`) file:

    ```diff
    <UnoFeatures>
        Material;
        Extensions;
    +   HttpKiota;
        Toolkit;
        MVUX;
    </UnoFeatures>
    ```

### 2. Enable Http in Host Builder

* Add the UseHttp method to the `IHostBuilder`:

    ```csharp
    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var appBuilder = this.CreateBuilder(args)
            .Configure(hostBuilder =>
            {
                hostBuilder.UseHttp();
            });
        ...
    }
    ```

### 3. Generate the Kiota Client

* Install the Kiota tool:

    ```bash
    dotnet tool install --global Microsoft.OpenApi.Kiota
    ```

* Generate the Client using the OpenAPI specification URL or a local file:

    ```bash
    # From a static spec file
    kiota generate --openapi PATH_TO_YOUR_API_SPEC.json --language CSharp --class-name MyApiClient --namespace-name MyApp.Client.MyApi --output ./MyApp/Content/Client/MyApi
    # OR directly from the running server’s Swagger endpoint
    kiota generate --openapi http://localhost:5002/swagger/v1/swagger.json --language CSharp --class-name MyApiClient --namespace-name MyApp.Client.MyApi --output ./MyApp/Content/Client/MyApi
    ```

    This will create a client named `MyApiClient` in the Client folder.

### 4. Register the Kiota Client

* Register the generated client in the IHostBuilder using `AddKiotaClient` from `Uno.Extensions`:

    ```csharp

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var appBuilder = this.CreateBuilder(args)
            .Configure(hostBuilder =>
            {
                hostBuilder.UseHttp((context, services) =>
                    services.AddKiotaClient<MyApiClient>(
                        context,
                        options: new EndpointOptions { Url = "https://localhost:5002" }
                    )
                );
            });
    }
    ```

### 5. Use the Kiota Client in Your Code

* Inject the ApiClient into your view model or service and make API requests:

```csharp
public class MyViewModel
{
    private readonly MyApiClient _apiClient;

    public MyViewModel(MyApiClient apiClient)
    {
        _apiClient = apiClient;
    }

    public async Task GetAll()
    {
        var something = await _apiClient.Api.GetAsync();
        Console.WriteLine($"Retrieved {something?.Count}.");
    }
}

```

## Important Considerations

* With `Uno.Extensions.Authentication`, the HttpClient automatically includes the **Authorization** header. You don't need to manually handle token injection. The middleware ensures the access token is included in each request.

* Ensure your server is running and the swagger.json file is accessible at the specified URL when generating the Kiota client.

## See also

* [Overview: What is Kiota?](https://learn.microsoft.com/en-us/openapi/kiota/)
* [Overview: HTTP](xref:Uno.Extensions.Http.Overview)
* [How-To: Consume a web API with HttpClient](xref:Uno.Development.ConsumeWebApi)
* [How-To: Register an Endpoint for HTTP Requests](xref:Uno.Extensions.Http.HowToHttp)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Authentication/HowTo-MsalAuthentication.md

---
uid: Uno.Extensions.Authentication.HowToMsalAuthentication
---
# How-To: Get Started with MSAL Authentication

`MsalAuthenticationProvider` allows your users to sign in using their Microsoft identities. It wraps the [MSAL library](https://github.com/AzureAD/microsoft-authentication-library-for-dotnet) from Microsoft into an implementation of `IAuthenticationProvider`. This tutorial will use MSAL authorization to validate user credentials.

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. Prepare for MSAL authentication

- For this type of authentication, the application must be registered with the Microsoft identity platform. For more information, see [Register an application with the Microsoft identity platform](https://learn.microsoft.com/azure/active-directory/develop/quickstart-register-app).

- The identity provider will provider you with a client ID and guidance on scopes to use.

- Add `AuthenticationMsal` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

    ```diff
    <UnoFeatures>
        Material;
    +   AuthenticationMsal;
        Toolkit;
        MVUX;
    </UnoFeatures>
    ```

### 2. Set up MSAL authentication

- Use the `UseAuthentication()` extension method to configure the `IHostBuilder` to use an authentication provider. In our case, we will be using the `MsalAuthenticationProvider`.

    ```csharp
    private IHost Host { get; set; }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var builder = this.CreateBuilder(args)
            .Configure(host =>
            {
                host
                .UseAuthentication(builder =>
                {
                    // Add the authentication provider here
                });
            });
        ...
    }
    ```

- Use the `Configure` method overload that provides access to a `Window` instance. Add the `MsalAuthenticationProvider` using the `AddMsal()` extension method which configures the `IAuthenticationBuilder` to use it.

    ```csharp
    private IHost Host { get; set; }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var builder = this.CreateBuilder(args)
            .Configure((host, window) =>
            {
                host
                .UseAuthentication(builder =>
                {
                    builder.AddMsal(window);
                });
            });
        ...
    }
    ```

> [!IMPORTANT]
> The `AddMsal()` method requires a `Window` instance, which the `MsalAuthenticationProvider` uses to set up the authentication dialog. You can access the `Window` instance through the `Configure()` method overload that provides it.
> **Note:** Failing to pass a valid `Window` instance could result in a `MsalClientException` with the message:
> *"Only loopback redirect uri is supported, but <your_redirect_uri> was found. Configure http://localhost or http://localhost:port both during app registration and when you create the PublicClientApplication object. See https://aka.ms/msal-net-os-browser for details."*

- The `IAuthenticationBuilder` is responsible for managing the lifecycle of the associated provider that was built.

- Because it is configured to use MSAL, the user will eventually be prompted to sign in to their Microsoft account when they use your application. `MsalAuthenticationProvider` will then store the user's access token in credential storage. The token will be automatically refreshed when it expires.

### 3. Configure the provider

- While `MsalAuthenticationProvider` is added using the `AddMsal()` extension method, you will need to add a configuration section to your appsettings.json file with your client ID and scopes.

    The following example shows how to configure the provider using the default section name:

    ```json
    {
      "Msal": {
        "ClientId": "161a9fb5-3b16-487a-81a2-ac45dcc0ad3b",
        "Scopes": [ "Tasks.Read", "User.Read", "Tasks.ReadWrite" ]
      }
    }
    ```

    This configuration can also be done in the root App.cs file:

    ```csharp
    private IHost Host { get; set; }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var builder = this.CreateBuilder(args)
            .Configure((host, window) =>
            {
                host
                .UseAuthentication(builder =>
                {
                    builder.AddMsal(window, msal =>
                        msal
                        .Builder(msalBuilder => 
                            msalBuilder.WithClientId("161a9fb5-3b16-487a-81a2-ac45dcc0ad3b"))
                        .Scopes(new[] { "Tasks.Read", "User.Read", "Tasks.ReadWrite" })
                    );
                });
            });
        ...
    }
    ```

    > [!WARNING]
    > A ClientId of GUID format is required for MSAL Authentication to work. You can specify it in the appsettings.json file, or in the code itself.
    > If the ClientId cannot be found, the app will crash with the following error:

    ```xml
    Exception thrown: 'Microsoft.Identity.Client.MsalClientException' in Microsoft.Identity.Client.dll
    No ClientId was specified.
    ```

### 4. Use the provider in your application

- Update the `MainPage` to include a `Button` labeled to sign in with Microsoft.

    ```xml
    <Page
        x:Class="MyApp.MainPage"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:MyApp"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        mc:Ignorable="d">

        <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
            <Button x:Name="SignInButton" Content="Sign in with Microsoft" Command="{x:Bind ViewModel.Authenticate}" />
        </Grid>
    </Page>
    ```

- Because the `IAuthenticationService` instance will be injected into our view models, we can now update the `MainViewModel` to include a `Command` that will use that service to sign in a user.

    ```csharp
    public class MainViewModel : ObservableObject
    {
        private readonly IAuthenticationService _authenticationService;

        public MainViewModel(IAuthenticationService authenticationService)
        {
            _authenticationService = authenticationService;
            Authenticate = new AsyncRelayCommand(AuthenticateAsync);
        }

        public ICommand Authenticate { get; }

        private async Task AuthenticateAsync()
        {
            await _authenticationService.LoginAsync(/* ... */);
        }
    }
    ```

- Finally, we can run the application and sign in with our Microsoft account. The user will be prompted to sign in to their Microsoft account when they tap the button in the application.

- `MsalAuthenticationProvider` will then store the user's access token in credential storage. The token will be automatically refreshed when it expires.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Navigation/HowTo-NavigateBetweenPages.md

---
uid: Uno.Extensions.Navigation.HowToNavigateBetweenPages
---
# How-To: Navigate Between Pages

This topic covers using Navigation to navigate between two pages using frame-based navigation.

[!include[getting-help](../includes/mvvm-approach.md)]

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. Installation

* Add `Navigation` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

    ```diff
    <UnoFeatures>
        Material;
        Extensions;
    +   Navigation;
        Toolkit;
        MVUX;
    </UnoFeatures>
    ```

### 2. Navigating to a New Page

* Add a new `Page` to navigate to, `SamplePage.xaml`
* In `MainPage.xaml` replace the existing `Button` with the following XAML, which includes a handler for the Click event

    ```xml
    <Button Content="Go to SamplePage"
            Click="GoToSamplePageClick" />
    ```

* In the `GoToSamplePageClick` method, use the `Navigator` extension method to get a reference to an  `INavigator` instance and call `NavigateViewAsync` to navigate to the `SamplePage`. This will push a new instance of the `SamplePage` onto the current Frame, pushing the `MainPage` to the back-stack.

    ```csharp
    private void GoToSamplePageClick(object sender, RoutedEventArgs e)
    {
        _ = this.Navigator()?.NavigateViewAsync<SamplePage>(this);
    }
    ```

### 3. Navigating Back to the Previous Page

* In `SamplePage.xaml` add a `Button` with a handler for the `Click` event

    ```xml
    <Button Content="Go Back"
            Click="GoBackClick" />
    ```

* Again, use the `Navigator` extension method to access the `INavigator` instance and call `NavigateBackAsync`. This will cause the frame to navigate to the previous page on the back-stack and releasing the `SamplePage` instance.

    ```csharp
    private void GoBackClick(object sender, RoutedEventArgs e)
    {
        _ = this.Navigator()?.NavigateBackAsync(this);
    }
    ```

### 4. Defining ViewMap and RouteMap

At this point, if you inspect the Output window you'll see a line that says something similar to:
`For better performance (avoid reflection), create a mapping for for path 'Sample', view 'SamplePage', view model`
This warning exists because Navigation uses reflection as a fallback mechanism to associate types and the corresponding navigation route. This can be resolved by specifying a `ViewMap` and a `RouteMap` for the `SamplePage` to eliminate the need for reflection

* Update the `RegisterRoutes` method in the `App.xaml.cs` file

    ```csharp
    private static void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
    {
        views.Register(
            new ViewMap(ViewModel: typeof(ShellViewModel)),
            new ViewMap<MainPage, MainViewModel>(),
            new DataViewMap<SecondPage, SecondViewModel, Entity>(),
            new ViewMap<SamplePage>()
        );

        routes.Register(
            new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
                Nested:
                [
                    new ("Main", View: views.FindByViewModel<MainViewModel>()),
                    new ("Second", View: views.FindByViewModel<SecondViewModel>()),
                    new ("Sample", View: views.FindByView<SamplePage>()),
                ]
            )
        );
    }
    ```

### 5. Associating a View Model

By defining a `ViewMap` that associates a view with a view model, an instance of the view model can dynamically be created and is subsequently set as the `DataContext` on the view that's navigated to.

* Create a new class `SampleViewModel` in the Presentation folder

    ```csharp
    public class SampleViewModel
    {
        public string Title => "Sample Page";
        public SampleViewModel()
        {
        }
    }
    ```

* Update `ViewMap` in `App.xaml.cs` to include `SampleViewModel`

    ```csharp
    new ViewMap<SamplePage, SampleViewModel>()
    ```

* Add `TextBlock` to the `SamplePage.xaml` and data bind to the `Title` property

    ```xml
    <TextBlock Text="{Binding Title}" />
    ```

### 6. Navigating via View Models

The Navigation code can be moved from the `SamplePage.cs` code-behind file to the `SampleViewModel`.

* Update `SampleViewModel` to take a constructor dependency on `INavigator` and add a `GoBack` method that will call the `NavigateBackAsync` method

    ```csharp
    private readonly INavigator _navigator;
    public SampleViewModel(INavigator navigator)
    {
        _navigator = navigator;
    }

    public Task GoBack()
    {
        return _navigator.NavigateBackAsync(this);
    }
    ```

* In order to use `x:Bind` to invoke the `GoBack` method on the `SampleViewModel` the `SamplePage` needs to expose a property that returns the `DataContext` as a `SampleViewModel`.

    ```csharp
    public SampleViewModel? ViewModel  => DataContext as SampleViewModel;

    public SamplePage()
    {
        this.InitializeComponent();
    }
    ```

* Update the `Button` in `SamplePage.xaml` to set the `Click` method to `x:Bind` to the `GoBack` method

    ```xml
    <Button Content="Go Back (View Model)"
            Click="{x:Bind ViewModel.GoBack}" />
    ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Navigation/HowTo-NavigateInCode.md

---
uid: Uno.Extensions.Navigation.HowToNavigateInCode
---
# How-To: Navigate in Code

This topic walks through controlling Navigation from code, either in the code-behind file of a Page or in the corresponding view model. One of the Navigation objectives was a single navigation construct that applies wherever you choose to write your navigation code.

[!include[getting-help](../includes/mvvm-approach.md)]

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. Navigating to a New Page

Navigation can be invoked in the code-behind file of a `Page` by using the `Navigator` extension method to get an `INavigator` instance.

- Add a new `Page` to navigate to, `SamplePage.xaml`
- In `MainPage.xaml` update the `Button` to the following XAML, which includes a handler for the `Click` event

    ```xml
    <Button Content="Go to SamplePage"
            Click="GoToSamplePageClick" />
    ```

- In the `GoToSamplePageClick` method, use the `Navigator` extension method to get a reference to an  `INavigator` instance and call `NavigateViewAsync` to navigate to the `SamplePage`. This will push a new instance of the `SamplePage` onto the current frame, pushing the `MainPage` to the back-stack.

    ```csharp
    private void GoToSamplePageClick(object sender, RoutedEventArgs e)
    {
        _ = this.Navigator()?.NavigateViewAsync<SamplePage>(this);
    }
    ```

### 2. Navigating Back to the Previous Page

- In `SamplePage.xaml` add a `Button` with a handler for the `Click` event

    ```xml
    <Button Content="Go Back"
            Click="GoBackClick" />
    ```

- Again, use the `Navigator` extension method to access the `INavigator` instance and call `NavigateBackAsync`. This will cause the frame to navigate to the previous page on the back-stack and releasing the `SamplePage` instance.

    ```csharp
    private void GoBackClick(object sender, RoutedEventArgs e)
    {
        _ = this.Navigator()?.NavigateBackAsync(this);
    }
    ```

### 3. Navigate to a ViewModel

The `NavigateViewAsync` method uses the type of the view, i.e. `SamplePage`, to determine the view to navigate to. By associating a view model with a view, Navigation can be defined based on the type of view model to navigate to. This means that the Navigation logic isn't dependent on the UI layer of the application. The Navigation logic can then be moved into a view model and thus making it easier to test.

- Create a new class `SampleViewModel` in the `ViewModels` folder of the class library project

    ```csharp
    public class SampleViewModel
    {
        public SampleViewModel()
        {
        }
    }
    ```

- Add `ViewMap` and `RouteMap` instances in the `RegisterRoutes` method in `App.xaml.cs`. This associates the `SampleViewModel` with the `SamplePage`, as well as avoiding the use of reflection for route discovery.

    ```csharp
    private static void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
    {
        views.Register(
            new ViewMap(ViewModel: typeof(ShellViewModel)),
            new ViewMap<MainPage, MainViewModel>(),
            new DataViewMap<SecondPage, SecondViewModel, Entity>(),
            new ViewMap<SamplePage, SampleViewModel>()
        );

        routes.Register(
            new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
                Nested:
                [
                    new ("Main", View: views.FindByViewModel<MainViewModel>()),
                    new ("Second", View: views.FindByViewModel<SecondViewModel>()),
                    new ("Sample", View: views.FindByViewModel<SampleViewModel>()),
                ]
            )
        );
    }
    ```

- Now that there's an association between `SamplePage` and `SampleViewModel` the code in `MainPage.xaml.cs` can be updated to use the `NavigateViewModelAsync` method.

    ```csharp
    private void GoToSamplePageClick(object sender, RoutedEventArgs e)
    {
        _ = this.Navigator()?.NavigateViewModelAsync<SampleViewModel>(this);
    }
    ```

### 4. View Model Navigation

- The logic for navigating back from `SamplePage` to `MainPage` can be moved into the `SampleViewModel`. Add the `GoBack` method to `SampleViewModel` that uses the `INavigator` instance that's injected via the constructor.

    ```csharp
    public SampleViewModel(INavigator navigator)
    {
        _navigator = navigator;
    }

    public Task GoBack()
    {
        return _navigator.NavigateBackAsync(this);
    }

    private readonly INavigator _navigator;
    ```

- During Navigation from `MainPage` to `SamplePage` an instance of the `SampleViewModel` will get created and assigned as the `DataContext` of the newly created `SamplePage`. In order to `x:Bind` to properties and methods on the `SampleViewModel`, expose a `ViewModel` property that returns the `DataContext` property as a `SampleViewModel`.

    ```csharp
    public SampleViewModel? ViewModel => DataContext as SampleViewModel;

    public SamplePage()
    {
        this.InitializeComponent();
    }
    ```

- Update the `Button` in `SamplePage.xaml` to use `x:Bind` to define the event handler for the `Click` event.

    ```xml
    <Button Content="Go Back (View Model)"
            Click="{x:Bind ViewModel.GoBack}" />
    ```

> [!TIP]
> The logic to navigate from `MainPage` to `SamplePage` can also be refactored into the `MainViewModel`. Irrespective of whether the logic is in the code-behind or in the view model, it would use the same `NavigateViewModelAsync<SampleViewModel>` method call.

There are many other extension methods on the `INavigator` interface that can be used from either the code-behind or view model. Here are a few of the key navigation methods:
**NavigateRouteAsync** - Navigates to a route specified as a string
**NavigateViewAsync** - Navigates to a route that matches the view type specified
**NavigateViewModelAsync** - Navigates to a route that matches the view model type specified
**NavigateDataAsync** - Navigates to a route that is registered for the data type specified
**NavigateForResultAsync** - Navigates to a route that is registered to return the result data type specified

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Navigation/HowTo-NavigateInXAML.md

---
uid: Uno.Extensions.Navigation.HowToNavigateInXAML
---
# How-To: Navigate in XAML

This topic walks through controlling Navigation from XAML. This includes specifying data that should be attached to the navigation request.

[!include[getting-help](../includes/mvvm-approach.md)]

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. Navigation.Request

Navigation can be defined in XAML by placing the `Navigation.Request` attached property on a specific XAML element. The string value specified in the `Navigation.Request` is the route to be navigated to.
Depending on the type of the XAML element, the `Navigation.Request` property will attach to an appropriate event in order to trigger navigation. For example, on a `Button`, the `Click` event will be used to trigger navigation, whereas the `SelectionChanged` event on a `ListView` is used. If you place a `Navigation.Request` property on a static element, such as a `Border`, `Image`, or `TextBlock`, the `Tapped` event will be used to trigger navigation.

- Add a new `Page` to navigate to, `SamplePage.xaml`

- Add a new class, `SampleViewModel`, to the class library project

    ```csharp
    public class SampleViewModel
    {
        public SampleViewModel(INavigator navigator)
        {
            _navigator = navigator;
        }

        private readonly INavigator _navigator;
    }
    ```

- In `MainPage.xaml` update the `Button` to use the `Navigation.Request` attached property instead of the `Click` event handler.

    ```xml
    <Button Content="Go to SamplePage"
            uen:Navigation.Request="Sample" />
    ```

    > [!TIP]
    > As Navigation.Request attached property exists in the `Uno.Extensions.Navigation.UI` namespace you will need to import this namespace on the `Page` element with

    ```csharp
    <Page x:Class="NavigateInXAML.Views.SamplePage"
        ...
        xmlns:uen="using:Uno.Extensions.Navigation.UI">
    ```

- In `SamplePage.xaml` add a `Button`, again with the `Navigation.Request` attached property. The "-" navigation route is used to navigate back.

    ```xml
    <Button Content="Go Back"
            uen:Navigation.Request="-" />
    ```

    > [!TIP]
    > While this works, it relies on reflection to convert the request path "Sample" to the corresponding view, i.e. `SamplePage`. It's better to define `ViewMap` and `RouteMap`

- Add a `ViewMap` and a `RouteMap` for the `SamplePage` into the `RegisterRoutes` method in the `App.xaml.cs` file

    ```csharp
    private static void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
    {
        views.Register(
            new ViewMap(ViewModel: typeof(ShellViewModel)),
            new ViewMap<MainPage, MainViewModel>(),
            new DataViewMap<SecondPage, SecondViewModel, Entity>(),
            new ViewMap<SamplePage, SampleViewModel>()
        );

        routes.Register(
            new RouteMap("", View: views.FindByViewModel<ShellViewModel>(),
                Nested:
                [
                    new ("Main", View: views.FindByViewModel<MainViewModel>()),
                    new ("Second", View: views.FindByViewModel<SecondViewModel>()),
                    new ("Sample", View: views.FindByViewModel<SampleViewModel>()),
                ]
            )
        );
    }
    ```

### 2. Navigation.Data

In addition to specifying the route to navigate to, the Navigation.Data attached property can be used to define the data to be attached to the navigation request. The data can be accessed by the view model associated with the route using constructor injection.

- Define a record (or class), `Widget`, that is the type of data that will be attached to the navigation request.

    ```csharp
    public record Widget(string Name, double Weight);
    ```

- Add a property, `Widgets`, to `MainViewModel` that returns an array of predefined `Widget` instances.

    ```csharp
    public Widget[] Widgets { get; } =
    [
        new Widget("NormalSpinner", 5.0),
        new Widget("HeavySpinner", 50.0)
    ];
    ```

- Replace the `Button` with a `ListView` in `MainPage.xaml` that has the `ItemsSource` property data bound to the `Widgets` property.

    ```xml
    <StackPanel Grid.Row="1"
                HorizontalAlignment="Center"
                VerticalAlignment="Center">
        <ListView ItemsSource="{Binding Widgets}"
                  x:Name="WidgetsList"
                  SelectionMode="Single">
            <ListView.ItemTemplate>
                <DataTemplate>
                    <StackPanel Orientation="Horizontal"
                                Padding="10">
                        <TextBlock Text="{Binding Name}" />
                        <TextBlock Text="{Binding Age}" />
                    </StackPanel>
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
    </StackPanel>
    ```

- Add a `Button` to the `StackPanel` on  `MainPage.xaml` that has both `Navigation.Request`, that specified the navigation route, and the `Navigation.Data` properties. In this case the `Navigation.Data` attached property is data bound to the `SelectedItem` property on the named element `WidgetsList` (which matches the `x:Name` set on the previously added `ListView`)

    ```xml
    <Button Content="Go to Sample Page"
            uen:Navigation.Request="Sample"
            uen:Navigation.Data="{Binding SelectedItem, ElementName=WidgetsList}"/>
    ```

- Update `SecondViewModel` to accept a `Widget` as the second constructor parameter

    ```csharp
    public class SampleViewModel
    {
        public string Title => "Sample Page";

        public string Name { get; }

        public SampleViewModel(Widget widget)
        {
            Name = widget.Name;
        }
    }

    ```

- Add a `TextBlock` to `SecondPage.xaml` that shows the name of the `Widget` supplied during navigation.

    ```xml
    <TextBlock HorizontalAlignment="Center"
               VerticalAlignment="Center">
        <Run Text="Widget Name:" />
        <Run Text="{Binding Name}" />
    </TextBlock>
    ```

- In order for the `Widget` to be injected into the `SampleViewModel` during navigation, a `DataMap` has to be added to the `ViewMap`. Therefore, we can change the `ViewMap` instantiation to `DataViewMap` and provide the `Widget` as a generic argument:

    ```csharp
    new DataViewMap<SamplePage, SampleViewModel, Widget>()
    ```

### 3. Navigating To SelectedItem

Instead of having to select an item in the `ListView` and then clicking on the `Button`, Navigation can be triggered when the user selects an item in the `ListView`.

- Add the `Navigation.Request` property to the `ListView`. The `Navigation.Data` property is not required as the selected item will automatically be attached to the navigation request. Also remove the `SelectionMode` property as it is no longer necessary for the `ListView` to track the selected item.

    ```xml
    <ListView ItemsSource="{Binding Widgets}"
              uen:Navigation.Request="Sample">
        <ListView.ItemTemplate>
            <DataTemplate>
                <StackPanel Orientation="Horizontal"
                            Padding="10">
                    <TextBlock Text="{Binding Name}" />
                    <TextBlock Text="{Binding Age}" />
                </StackPanel>
            </DataTemplate>
        </ListView.ItemTemplate>
    </ListView>
    ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Authentication/HowTo-OidcAuthentication.md

---
uid: Uno.Extensions.Authentication.HowToOidcAuthentication
---
# How-To: Get Started with Oidc Authentication

`OidcAuthenticationProvider` is a specific implementation of `IAuthenticationProvider` that allows your users to sign in using their identities from a participating identity provider. It provides seamless integration with any [OpenID Connect](https://openid.net/connect/) backend, such as [Duende.IdentityServer](https://duendesoftware.com/products/identityserver). By acting as an adapter, it integrates OpenID Connect authentication into the Uno.Extensions ecosystem, allowing you to leverage a unified approach across platforms.

Under the hood, `OidcAuthenticationProvider` relies on [Duende.IdentityModel.OidcClient](https://docs.duendesoftware.com/identitymodel-oidcclient/), for all non-windows targets, as a widely-used .NET library that handles the core OpenID Connect and OAuth 2.0 protocols. This library manages the complex operations like token handling and user authentication.

> [!NOTE]
> It may be useful to familiarize yourself with the [OpenID Connect](https://openid.net/connect/) protocol before proceeding.
> You can also explore the [Uno Tutorial for Oidc Authentication](xref:Uno.Tutorials.OpenIDConnect) to learn more about the particularities for different platforms.

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. Prepare for OIDC authentication

- For this type of authentication, the application must already be registered with the desired identity provider.

- A client id (and client secret) will be provided to you.

- Add `AuthenticationOidc` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

    ```diff
    <UnoFeatures>
        Material;
    +   AuthenticationOidc;
        Toolkit;
        MVUX;
    </UnoFeatures>
    ```

### 2. Set up OIDC authentication

- Use the `UseAuthentication()` extension method to configure the `IHostBuilder` to use an authentication provider. In our case, we will be using the `OidcAuthenticationProvider`.

    ```csharp
    private IHost Host { get; set; }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var builder = this.CreateBuilder(args)
            .Configure(host =>
            {
                host
                .UseAuthentication(builder =>
                {
                    // Add the authentication provider here
                });
            });
        ...
    }
    ```

- Add the `OidcAuthenticationProvider` using the `AddOidc()` extension method which configures the `IAuthenticationBuilder` to use it.

    ```csharp
    private IHost Host { get; set; }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var builder = this.CreateBuilder(args)
            .Configure(host =>
            {
                host
                .UseAuthentication(builder =>
                {
                    builder.AddOidc();
                });
            });
        ...
    }
    ```

- The `IAuthenticationBuilder` is responsible for managing the lifecycle of the associated provider that was built.

- Because it is configured to use OpenID Connect, the user will eventually be prompted to sign in to their identity provider account when they use your application. `OidcAuthenticationProvider` will then store the user's access token in credential storage. The token will be automatically refreshed when it expires.

### 3. Configure the OidcAuthenticationProvider

- While the `AddOidc()` extension method will configure the `IAuthenticationBuilder` to use the `OidcAuthenticationProvider`, it will not configure the provider itself. The `OidcAuthenticationProvider` can be configured using a configuration section.

- We will use the default section name `Oidc` in this example:

  ```json
  {
      "Oidc": {
          "Authority": "https://demo.duendesoftware.com/",
          "ClientId": "interactive.confidential",
          "ClientSecret": "secret",
          "Scope": "openid profile email api offline_access",
          "RedirectUri": "oidc-auth://callback",
      }
  }
  ```

  > Common scopes include `openid`, `profile`, `email`, and `offline_access`. The `openid` scope is required for OpenID Connect authentication. The `profile` and `email` scopes are used to request additional user information, and the `offline_access` scope is used to request a refresh token. Your identity provider may provide additional scopes, such as `api`, to request access to specific APIs.

- `Authority`: The URL of the identity provider.

- `ClientId` and `ClientSecret`: The client ID and client secret that were provided to you.

- `Scope`: The scope of the access token.

- `RedirectUri`: The URL that the identity provider will redirect to after the user has authenticated.
  > It is also possible to populate this setting automatically from the WebAuthenticationBroker using the `.AutoRedirectUriFromAuthenticationBroker()` extension method, which will set the redirect URI to the value returned by the `WebAuthenticationBroker.GetCurrentApplicationCallbackUri()` method, which should discover the correct redirect URI for the application/platform. More information can be found in the [Web Authentication Broker documentation](xref:Uno.Features.WAB).
  >
  > When used, this setting will override the value set in the configuration file for both the redirect URI and the post-logout redirect URI.
  > **This setting is ON by default on WebAssembly but opt-in on other platforms.**

- **Advanced settings**: some advanced settings may need to access directly the `OidcClientOptions` from `IdentityModel.OidcClient` used by this extension. This can be done by using the `.ConfigureOidcClientOptions()` extension method.

    ```csharp
    builder.AddOidc()
        .ConfigureOidcClientOptions(options =>
        {
            // Example of advanced settings for the OidcClientOptions
            options.DisablePushedAuthorization  = false; // Disable the PAR endpoint
            options.Policy.RequireIdentityTokenOnRefreshTokenResponse = true; // Require an identity token on refresh token response
            options.Policy.Discovery.ValidateIssuerName = false; // Disable issuer name validation
        });
    ```

### 4. Use the provider in your application

- Update the `MainPage` to include a button that will allow the user to sign in with your desired service.

    ```xml
    <Page
        x:Class="UnoOidcAuthentication.MainPage"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:UnoOidcAuthentication"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        mc:Ignorable="d">

        <Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
            <Button x:Name="SignInButton" Content="Sign In" Command="{x:Bind ViewModel.Authenticate}" />
        </Grid>
    </Page>
    ```

- Update the `MainViewModel` to include a command that will allow the user to sign in with your desired service.

    ```csharp
    public class MainViewModel : ObservableObject
    {
        private readonly IAuthenticationService _authenticationService;

        public MainViewModel(IAuthenticationService authenticationService)
        {
            _authenticationService = authenticationService;
        }

        public ICommand Authenticate => new AsyncRelayCommand(AuthenticateImpl);

        private async Task AuthenticateImpl()
        {
            await _authenticationService.LoginAsync(/* ... */);
        }
    }
    ```

- Finally, we can pass the login credentials to the `LoginAsync()` method and authenticate with the identity provider. The user will be prompted to sign in to their account when they tap the button in the application.

- `OidcAuthenticationProvider` will then store the user's access token in credential storage. The token will be automatically refreshed when it expires.

## Advanced Customizations

- You can use your own implementation of `IBrowser` (an interface from the `IdentityModel.OidcClient` library) to customize the browser behavior. This should be done by creating a class that implements the interface and register it using the `.ConfigureServices()` in the `App.xaml.cs` file.

  ```csharp
    .ConfigureServices((context, services) =>
    {
        services.AddTransient<IBrowser, CustomBrowser>();
    })

  ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Http/HowTo-Refit.md

---
uid: Uno.Extensions.Http.HowToRefit
---
# How-To: Quickly Create a Strongly-Typed REST Client for an API

When accessing resources with a [REST-style](https://www.ics.uci.edu/~fielding/pubs/dissertation/rest_arch_style.htm) API is a significant part of your application, it is common to look for an SDK that provides a strongly-typed client for the API. This allows you to avoid writing boilerplate code to make requests and deserialize responses. There is sometimes no SDK available yet for the API you want to use, or it's not compatible with your target platform. With the design goal of avoiding boilerplate code in mind, we will walk through how to use [Refit](https://github.com/reactiveui/refit) to quickly create a strongly-typed client for a REST API and register it with the service collection as an endpoint.

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. Installation

* Add `HttpRefit` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

    ```diff
    <UnoFeatures>
        Material;
        Extensions;
    +   HttpRefit;
        Toolkit;
        MVUX;
    </UnoFeatures>
    ```

### 2. Enable HTTP

* When working with a complex application, centralized registration of your API endpoints is a good practice. This allows you to easily change the endpoint for a given service. It also reduces the complexity to adding new services which can then have their `HttpClient` instance reused across multiple instances of view models or other services.

* The first step to centrally registering any API endpoint is to enable HTTP on the `IHostBuilder`:

    ```csharp
    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var appBuilder = this.CreateBuilder(args)
            .Configure(hostBuilder =>
            {
                hostBuilder.UseHttp();
            });
        ...
    }
    ```

* This feature requires the [Uno.Extensions.Http.WinUI](https://www.nuget.org/packages/Uno.Extensions.Http.WinUI) package. It uses [Microsoft Extensions](https://www.nuget.org/packages/Microsoft.Extensions.Http) for any HTTP-related [work](https://learn.microsoft.com/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests#benefits-of-using-ihttpclientfactory) such as naming or configuring the `HttpClient` instance associated with your endpoints.

### 3. Define the live interface

* For the purposes of this tutorial, we will create and register an interface for the Chuck Norris facts web API which is documented [here](https://api.chucknorris.io/)

* This interface will be used to generate the strongly-typed client. It will be used to make requests to the web service and deserialize responses.

* Start by defining an interface `IChuckNorrisEndpoint` with a method `Search()` that returns a `Task` of type `ApiResponse<ChuckNorrisData>`:

    ```csharp
    [Headers("Content-Type: application/json")]
    public interface IChuckNorrisEndpoint
    {
        [Get("/jokes/search")]
        Task<ApiResponse<ChuckNorrisData>> Search(CancellationToken ct, [AliasAs("query")] string searchTerm);
    }
    ```

    > [!NOTE]
    > A class named `ChuckNorrisData` will be defined in the next section of this guide. It will be used to deserialize the response from the API.

* The `Headers` attribute is used to specify the `Content-Type` header for the request. `Get` specifies the relative path for a `Search` request. Notice that the `searchTerm` parameter for the request is aliased as `query` using an `AliasAs` attribute.

* `ApiResponse<T>` is used to deserialize the response from the API. It is defined in the `Refit` package.

### 4. Generate a data model from the API response

* The next step is to generate a data model from the response we will get from the API. This will be used to deserialize the response which we'll learn is a JSON object with a `total` property and `result` that contains an array of Chuck Norris data objects.

* By the end of this section, a `ChuckNorrisData` class will be defined in the `Models` namespace to represent each object in the array.

* We will use [Hoppscotch](https://hoppscotch.io) to make an HTTP request and inspect the response. Open it, and make a `GET` request to the `/jokes/search` endpoint with the query parameter `query` set to `fight`.

  * Your screen should appear similar to this:

    ![Hoppscotch](../images/http-refit-hoppscotch.png)

  * For informational purposes, this is the full HTTP request URL:

    ```http
    GET https://api.chucknorris.io/jokes/search?query=fight
    ```

  * The **response body** pane will populate with a formatted JSON object that looks similar to this:

    ```json
    {
        "total": 111,
        "result": [
            {
                "categories": [],
                "created_at": "2020-01-05 13:42:18.823766",
                "icon_url": "https://assets.chucknorris.host/img/avatar/chuck-norris.png",
                "id": "VvGL-lRHSsOL-jj9IEDWRA",
                "updated_at": "2020-01-05 13:42:18.823766",
                "url": "https://api.chucknorris.io/jokes/VvGL-lRHSsOL-jj9IEDWRA",
                "value": "Chuck Norris doesn't beat people up he looks at them they get scared and fight their self to the death"
            },
        ...
        ]
    }
    ```

  * Since this response is needed for the next step, copy the entire JSON object from the **response body** pane

* Next, we need to use a language-agnostic tool that infers a data model from the response we recieved. We will open [quicktype](https://app.quicktype.io/) and use it to generate a data model from the JSON we copied above

  * Replace any demo text in the left **JSON** pane with our text by pasting the JSON object into editor

  * Within the properties box on the right side, make the following selections:

    * **C#** as the _language_

    * **System Text Json**  as the _serialization framework_

    * **Complete** as the _output features_

  * Your screen should appear similar to this:

    ![Hoppscotch](../images/http-refit-quicktype.png)

  * For the purposes of this tutorial, only select and copy the two model classes `Welcome` and `Result` from the right side containing the generated C# code.

    * What you copied should appear like this:

        ```csharp
        public partial class Welcome
        {
            [JsonPropertyName("total")]
            public long Total { get; set; }

            [JsonPropertyName("result")]
            public List<Result> Result { get; set; }
        }

        public partial class Result
        {
            [JsonPropertyName("categories")]
            public List<Category> Categories { get; set; }

            [JsonPropertyName("created_at")]
            public DateTimeOffset CreatedAt { get; set; }

            [JsonPropertyName("icon_url")]
            public Uri IconUrl { get; set; }

            [JsonPropertyName("id")]
            public string Id { get; set; }

            [JsonPropertyName("updated_at")]
            public DateTimeOffset UpdatedAt { get; set; }

            [JsonPropertyName("url")]
            public Uri Url { get; set; }

            [JsonPropertyName("value")]
            public string Value { get; set; }
        }
        ```

  * Go back to Visual Studio and create a new folder named `Models` in the shared project. Create a new file named `ChuckNorrisData.cs` in the `Models` folder and paste the code you copied into it.

  * Rename the partial classes `Welcome` to `ChuckNorrisData` and `Result` to `ChuckNorrisDataResult`

### 5. Register the endpoint

* Unlike standard HTTP endpoints, Refit endpoints you define will be registered as a service with the `AddRefitClient<T>()` extension method, where the type argument `T` corresponds to an interface you define.

* This extension method can take a delegate as its argument:

    ```csharp
    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var appBuilder = this.CreateBuilder(args)
            .Configure(hostBuilder =>
            {
                hostBuilder.UseHttp((context, services) =>
                    services.AddRefitClient<IChuckNorrisEndpoint>(context, httpClient =>
                    {
                        httpClient.BaseAddress = new Uri("https://api.chucknorris.io/");
                    })
                );
            });
        ...
    }
    ```

* Another way to configure an HTTP client is to specify a configuration section name. This allows you to configure the added HTTP client using the `appsettings.json` file. This tutorial demonstrates use of the configuration section method.

* Add the Refit client to the service collection with the following code instead:

    ```csharp
    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        var appBuilder = this.CreateBuilder(args)
            .Configure(hostBuilder =>
            {
                hostBuilder.UseHttp((context, services) =>
                    services.AddRefitClient<IChuckNorrisEndpoint>(context)
                );
            });
        ...
    }
    ```

* Look for a file named `appsettings.json` in the shared project. If it does not exist, create it. Open this file and add the following JSON:

    ```json
    {
        "ChuckNorrisEndpoint": {
            "Url": "https://api.chucknorris.io/",
            "UseNativeHandler": true
        }
    }
    ```

* The `Url` property specifies the base URL for the API.

* We set `UseNativeHandler` to `true` to use the native HTTP handler for the platform. This is recommended for production apps unless you have a specific reason to use the managed handler.

  * On Windows, intercepting the network traffic of your app with tools like **Fiddler** is not possible when using the native handler. This is because it does not use a compatible network stack.

  * In these cases, you can set `UseNativeHandler` to `false` to use the managed handler instead

* That block of JSON from the above file is called a configuration section. In this case, it's used to configure the HTTP client associated with the endpoint. For more information, see the [overview](xref:Uno.Extensions.Configuration.Overview#sections) for configuration sections.

* Observe that the name of the configuration section is similar to that of the endpoint interface we defined earlier. By default, the interface name without the leading `I` prefix is assumed to be the section name. This can be overridden by specifying a name while registering the service. The name you use should be the second argument to `AddRefitClient<T>()`.

### 6. Use the endpoint

* `IChuckNorrisEndpoint` can now be used in a service implementation by injecting it into the constructor.  This interface will be used to make requests to the web service and deserialize responses.

* For the purposes of this tutorial, we will create a view model for the page that triggers the request for a Chuck Norris fact named `FactViewModel`. It will have a method `SearchAsync()` that returns a `Task` of type `ChuckNorrisData`:

    ```csharp
    public class FactViewModel
    {
        private readonly IChuckNorrisEndpoint _endpoint;

        public FactViewModel(IChuckNorrisEndpoint endpoint)
        {
            _endpoint = endpoint;
        }

        public async Task<ChuckNorrisData> SearchAsync(string searchTerm)
        {
            var response = await _endpoint.Search(CancellationToken.None, searchTerm);

            if (response.IsSuccessStatusCode && response.Content is not null)
            {
                // Return first result
                var content = response.Content;
                return content.Result[0];
            }

            _logger.LogError(response.Error, "An error occurred while retrieving the latest fact.");
            return Task.FromException<ChuckNorrisData>(response.Error);
        }
    }
    ```

* Now, any views that need to display a Chuck Norris fact can use the `FactViewModel` to retrieve one. Thanks to the use of Refit, the details of HTTP requests and deserialization are abstracted away from the view, and boilerplate code is avoided.

## See also

* [How-To: Consume a web API with HttpClient](xref:Uno.Development.ConsumeWebApi)
* [How-To: Register an Endpoint for HTTP Requests](xref:Uno.Extensions.Http.HowToHttp)
* [Overview: HTTP](xref:Uno.Extensions.Http.Overview)
* [Overview: Use HttpClientFactory to implement resilient HTTP requests](https://learn.microsoft.com/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests#benefits-of-using-ihttpclientfactory)
* [Overview: What is Refit?](https://github.com/reactiveui/refit)
* [Explore: Hoppscotch tool](https://hoppscotch.io)
* [Explore: quicktype tool](https://app.quicktype.io/)
* [Explore: TestHarness Refit Endpoints](https://github.com/unoplatform/uno.extensions/tree/main/testing/TestHarness/TestHarness.Shared/Ext/Http/Refit)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Storage/HowTo-RequiredEntitlements.md

---
uid: Uno.Extensions.Storage.HowToRequiredEntitlements
---
# How-To: Add Required Entitlements

On Apple platforms (iOS, Mac Catalyst) the Uno storage extension uses the OS Key Chain service to store secrets. This requires your application to have the [`keychain-access-groups`](https://developer.apple.com/documentation/bundleresources/entitlements/keychain-access-groups) entitlement to work properly.

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. Add the Entitlements.plist file

The default location, inside your project, for the new file(s) should be:

* iOS: `iOS/Entitlements.plist`
* Mac Catalyst: `MacCatalyst/Entitlements.plist`

The content of the file(s) should be:

```xml
<key>keychain-access-groups</key> 
 <array> 
     <string>$(AppIdentifierPrefix)$(CFBundleIdentifier)</string> 
 </array>
```

For more information see Apple's documentation related to the [Key Chain](https://developer.apple.com/documentation/security/keychain_services/keychain_items/sharing_access_to_keychain_items_among_a_collection_of_apps?language=objc).

The variables `$(AppIdentifierPrefix)` and `$(CFBundleIdentifier)` will be replaced with the correct values at build time. For more information about how the Microsoft .NET SDK works with entitlements you can consult:

* [Microsoft iOS](https://learn.microsoft.com/en-us/dotnet/maui/ios/entitlements)
* [Microsoft Mac Catalyst](https://learn.microsoft.com/en-us/dotnet/maui/mac-catalyst/entitlements)

### 2. Add capabilities in your Apple Developer Account

Adding the `Entitlements.plist` to your project is not enough. You must also add the capability inside your Apple Developer Account and create a provisioning profile specific for your application. You can follow Microsoft's instructions for both steps:

* [Microsoft iOS](https://learn.microsoft.com/en-us/dotnet/maui/ios/capabilities?#add-capabilities-in-your-apple-developer-account)
* [Microsoft Mac Catalyst](https://learn.microsoft.com/en-us/dotnet/maui/mac-catalyst/capabilities?#add-capabilities-in-your-apple-developer-account)

> [!NOTE]
> You can use XCode to create a project, go to the **Signing and Capabilities**, use the same bundle identifier, add the **Keychain Sharing** capacity (again using the same bundle identifier) then ask Xcode to _fix_ your `Xcode Managed Profile`.

### 3. Modifying the `*.Mobile.csproj`

A new property group should be added to your `*.csproj` project file. The example below will work for both iOS and Mac Catalyst targets.

```xml
<PropertyGroup>
    <CodesignEntitlements Condition="$(IsIOS)">iOS\Entitlements.plist</CodesignEntitlements>
    <CodesignEntitlements Condition="$(IsMacCatalyst)">MacCatalyst\Entitlements.plist</CodesignEntitlements>
    <CodesignKey>Apple Development: Some User (XXXXXXXXXX)</CodesignKey>
    <CodesignProvision>Mac Catalyst Team Provisioning Profile: com.companyname.maccatalyst</CodesignProvision>
</PropertyGroup>
```

The values for the `CodesignKey` and `CodesignProvision` **must** match the values from the [Apple Developer Portal](https://developer.apple.com/account).

> [!NOTE]
> If you used Xcode earlier then build the application and get both values from the build logs.

### 4. Rebuilding your application

Finally rebuilding the application for your target(s) will now code sign your application. This makes the entitlements valid and allows the Key Chain API to work properly at runtime.

### 5. Troubleshooting

Code signing issues can be difficult to diagnose as the application won't start (or hang) if misconfigured. The operating systems (both iOS or macOS) will log code signing failures. You can see the logs by using Apple's [Console.app](https://support.apple.com/en-ca/guide/console/welcome/mac).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Navigation/HowTo-SelectValue.md

---
uid: Uno.Extensions.Navigation.HowToSelectValue
---
# How-To: Select a Value

This topic walks through using Navigation to request a value from the user. For example selecting a value from a list of items.

[!include[getting-help](../includes/mvvm-approach.md)]

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. GetDataAsync

This scenario will use Navigation to navigate to a page in order for the user to select an item. The item will be returned via Navigation to the calling code.

- Define a `Widget` record in the class library for data to be passed during navigation

    ```csharp
    public record Widget(string Name, double Weight);
    ```

- Add `Widgets` property to `SecondViewModel` to define the list of items to pick from.

    ```csharp
    public Widget[] Widgets { get; } =
    [
        new Widget("NormalSpinner", 5.0),
        new Widget("HeavySpinner", 50.0)
    ];
    ```

- Add a `ListView` to `SecondPage.xaml` to display the items returned by the `Widgets` property. The `Navigation.Request` property specifies a route of `-` which will navigate back to the previous page.

    ```xml
    <ListView ItemsSource="{Binding Widgets}"
              uen:Navigation.Request="-"
              HorizontalAlignment="Center"
              VerticalAlignment="Center">
        <ListView.ItemTemplate>
            <DataTemplate>
                <StackPanel Orientation="Horizontal"
                            Padding="10">
                    <TextBlock Text="{Binding Name}" />
                    <TextBlock Text="{Binding Age}" />
                </StackPanel>
            </DataTemplate>
        </ListView.ItemTemplate>
    </ListView>
    ```

- Update `MainViewModel` to use the `GetDataAsync` method in the `GoToSecondPage` method.

    ```csharp
    public async Task GoToSecondPage()
    {
        var widget = await _navigator.GetDataAsync<SecondViewModel, Widget>(this);
    }
    ```

- The selected value from the `ListView` on `SecondPage` will get returned to the `widget` variable in `MainViewModel`.

### 2. Navigating ForResult Type

In the preceding step, the `GetDataAsync` method call specified two generic arguments, `SecondViewModel` which defines the view to navigate to, and `Widget` which defines the type of data to be returned. The `ViewMap` can be updated to `ResultDataViewMap` to define an association between the view and the type of data being requested.

- Update the `ViewMap` for `SecondViewModel` as follows:

    ```csharp
    new ResultDataViewMap<SecondPage, SecondViewModel, Widget>()
    ```

- Update the `GetDataAsync` method call to only specify the result data type, `Widget`.

    ```csharp
    public async Task GoToSecondPage()
    {
        var widget = await _navigator.GetDataAsync<Widget>(this);
    }
    ```

Navigation is able to resolve which view to navigate to based on the type of data being requested, in this case `Widget`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Navigation/HowTo-ShowDialog.md

---
uid: Uno.Extensions.Navigation.HowToShowDialog
---
# How-To: Display a Dialog (modal or flyout)

This topic provides a step-by-step guide on using Navigation to display a Dialog.

## Step-by-step

[!include[create-application](../includes/create-application.md)]

### 1. Displaying a dialog from code

- Add a new `Page`, `SamplePage.xaml`, which will be used to display content inside the flyout.

    ```xml
    <Page x:Class="ShowDialog.Views.SamplePage"
          xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
          xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
          xmlns:local="using:ShowDialog.Views"
          xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
          xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
          mc:Ignorable="d"
          Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

        <Grid>
            <TextBlock Text="Dialog Navigation"
                       FontSize="32"
                       HorizontalAlignment="Center"
                       VerticalAlignment="Center" />
        </Grid>
    </Page>
    ```

- Update the `Button` in `MainPage.xaml` as follows, which wires up the `Click` event to the `ShowDialogClick` method:

    ```xml
    <Button Content="Show flyout"
            Click="ShowDialogClick"
            Grid.Row="1"
            HorizontalAlignment="Center"
            VerticalAlignment="Center"/>
    ```

- Add the `ShowDialogClick` method to the `MainPage.xaml.cs` file:

    ```csharp
    private void ShowDialogClick(object sender, RoutedEventArgs e)
    {
        _ = this.Navigator()?.NavigateViewAsync<SamplePage>(this, qualifier: Qualifiers.Dialog);
    }
    ```

### 2. Displaying a dialog from XAML

- Add another `Button` with the content `Show flyout from XAML` to `MainPage.xaml`. Set the `Navigation.Request` property to `!Sample` which indicates the `Sample` route should be opened as a Dialog in a Flyout.

    ```xml
    <StackPanel Grid.Row="1"
                HorizontalAlignment="Center"
                VerticalAlignment="Center">
        <Button Content="Show flyout"
                Click="ShowDialogClick" />
        <Button Content="Show flyout from XAML"
                uen:Navigation.Request="!Sample" />
    </StackPanel>
    ```

## Flyout vs. Modal

It is important to understand that "!" and `Qualifiers.Dialog` do not automatically determine whether the content will be displayed as a Flyout or as a Modal. These elements indicate a dialog, with the specific behavior (Flyout or Modal) being determined by the type of view used. In the previous example, we used a `Page`, which is displayed as a Flyout. If the intended behavior is to display a Modal, we need to change the `Page` to a `ContentDialog`.

### Example

- The result of our previous example, where a `Page` is used, displays as a Flyout:

  ![Page as Flyout](images/ShowDialogFlyout.png)

- If we modify the example to use a `ContentDialog` instead of a `Page`, the result will be displayed as a Modal. Here is the XAML code for the `ContentDialog`:

    ```xml
    <ContentDialog x:Class="ShowDialog.Views.SamplePage"
                   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
                   xmlns:local="using:ShowDialog.Views"
                   xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
                   Title="Modal"
                   PrimaryButtonText="Ok"
                   SecondaryButtonText="Cancel"
                   Style="{ThemeResource DefaultContentDialogStyle}">

        <Grid>
            <TextBlock HorizontalAlignment="Center"
                       VerticalAlignment="Center"
                       FontSize="32"
                       Text="Dialog Navigation" />
        </Grid>
    </ContentDialog>
    ```

    This change results in the following display:

    ![ContentDialog as Modal](images/ShowDialogModal.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Http/HttpOverview.md

---
uid: Uno.Extensions.Http.Overview
---
# 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](https://www.nuget.org/packages/Microsoft.Extensions.Http) for any HTTP related work.

For additional documentation on HTTP requests, read the references listed at the bottom.

## Installation

`Http`, `HttpRefit` and `HttpKiota` are provided as Uno Features. To enable HTTP client support in your application, add `Http`, `HttpRefit` or `HttpKiota` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

[!include[existing-app](../includes/existing-app.md)]

[!include[single-project](../includes/single-project.md)]

For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

## Register Endpoints

Web resources exposed through an API are defined in the application as clients. These client registrations include type arguments and endpoints to be used for the client. The endpoint is defined in the `EndpointOptions` class. While it uses the platform-native HTTP handler by default, this value can be configured.

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    var builder = this.CreateBuilder(args)
        .Configure(host => {
            host
            .UseHttp((context, services) =>
            {
                services
                .AddClient<IShowService, ShowService>(context, "configsectionname");
            });
        });
    ...
}
```

> [!TIP]
> If configuration sections are already used elsewhere, continuing to use that approach offers uniformity and broader accessibility of endpoint options. Consider whether this type of access is needed before using the alternate method below.

`EndpointOptions` can also be loaded from a specific instance.

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    var builder = this.CreateBuilder(args)
        .Configure(host => {
            host
            .UseHttp((context, services) =>
            {
                services
                .AddClient<IShowService, ShowService>(context,
                    new EndpointOptions
                    {
                        Url = "https://ch9-app.azurewebsites.net/"
                    }
                    .Enable(nameof(EndpointOptions.UseNativeHandler)));
            });
        });
    ...
}
```

### Custom Endpoint Options

`EndpointOptions` is a base class that provides a `Url` property. This property is used to specify the URL of the endpoint. Subclassing `EndpointOptions` allows for custom options beyond the `Url` such as a proxy, timeout, and adding headers. Using this method, the `HttpClient` associated with the endpoint can be configured from a single section in `appsettings.json`.

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(hostBuilder =>
        {
            hostBuilder.UseHttp((ctx, services) => {
                services.AddClientWithEndpoint<IShowService, ShowService, CustomEndpointOptions>();
            });
        });
    ...
}
```

For more information about configuring `HttpClient` with custom endpoint options, see the [Configure `HttpClient` with Custom Endpoint Options tutorial](xref:Uno.Extensions.Http.HowToEndpointOptions).

## Refit

Similarly, **Refit endpoints** can be registered as services and configured in a similar way.

```csharp
private IHost Host { get; set; }

protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    var builder = this.CreateBuilder(args)
        .Configure(host => {
            host
            .UseHttp((context, services) =>
            {
                services
                .AddRefitClient<IChuckNorrisEndpoint>(context);
            });
        });
    ...
}
```

In this case, the endpoint options will be loaded from configuration section _ChuckNorrisEndpoint_ which can be defined as the following JSON:

```json
{
  "ChuckNorrisEndpoint": {
    "Url": "https://api.chucknorris.io/",
    "UseNativeHandler": true
  }
}
```

For more information on using Refit, see the [Quickly Create a Strongly-Typed REST Client for an API tutorial](xref:Uno.Extensions.Http.HowToRefit).

## Kiota

You can generate a strongly-typed client from an **OpenAPI/Swagger** spec using **Kiota**, then register it just like any other endpoint.

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs args)
{
    var builder = this.CreateBuilder(args)
        .Configure(host =>
        {
            host.UseHttp((context, services) =>
            // MyApiClient is generated by Kiota
                services.AddKiotaClient<MyApiClient>(
                    context,
                    options: new EndpointOptions { Url = "https://localhost:5002" }
                )
            );
        });
    ...
}
```

For more information on using Kiota to generate and register your client see the [How-To: Create and register a Kiota client for an API](xref:Uno.Extensions.Http.HowToKiota) guide.

## References

- [How-To: Consume a web API with HttpClient](xref:Uno.Development.ConsumeWebApi)
- [How-To: Register an Endpoint for HTTP Requests](xref:Uno.Extensions.Http.HowToHttp)
- [How-To: Configure with Custom Endpoint Options](xref:Uno.Extensions.Http.HowToEndpointOptions)
- [How-To: Create a Strongly-Typed REST Client for an API](xref:Uno.Extensions.Http.HowToRefit)
- [Overview: Use HttpClientFactory to implement resilient HTTP requests](https://learn.microsoft.com/dotnet/architecture/microservices/implement-resilient-applications/use-httpclientfactory-to-implement-resilient-http-requests#benefits-of-using-ihttpclientfactory)
- [Overview: Delegating handlers](https://learn.microsoft.com/aspnet/web-api/overview/advanced/http-message-handlers)
- [Overview: Polly and HttpClientFactory](https://github.com/App-vNext/Polly/wiki/Polly-and-HttpClientFactory)
- [Overview: What is Refit?](https://github.com/reactiveui/refit)
- [Overview: What is Kiota?](https://learn.microsoft.com/en-us/openapi/kiota/)
- [Explore: TestHarness HTTP](https://github.com/unoplatform/uno.extensions/tree/main/testing/TestHarness/TestHarness/Ext/Http/)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/Internal-DependencyProperty-Generator.md

---
uid: Uno.Contributing.DependencyPropertyGenerator
---

# The DependencyProperty Generator

Uno provides an internal `DependencyPproperty` code generator, used to provide the boiler plate for the property, as well as the handling of local-precedence property value caching.

This generator is not available outside of Uno as it is very specific to the needs of the internals of Uno.

The property getters and setters are not generated to avoid VS2019 (as of 16.7 Pre 2) intellisense issues when opening the Uno.UI solution for the first time or after a repository cleanup.

## DependencyProperty declaration

To declare a dependency property, the following code must be provided:

```csharp
[Uno.UI.Xaml.GeneratedDependencyProperty(DefaultValue = "")]
public static readonly DependencyProperty MyStringProperty = CreateMyStringProperty();

public string MyString
{
    get => GetMyStringValue();
    set => SetMyStringValue(value);
}
```

This will automatically generate the `MyStringProperty` member.

## DependencyProperty property changed

```csharp
[Uno.UI.Xaml.GeneratedDependencyProperty(DefaultValue = "")]
public static readonly DependencyProperty MyStringProperty = CreateMyStringProperty();

public string MyString
{
    get => GetMyStringValue();
    set => SetMyStringValue(value);
}

private void OnMyStringChanged(string oldValue, string newValue) 
{
}
```

Declaring an `OnMyStringChanged` will automatically include that method for the property changed. To ensure that the method is defined and used, set the `PropertyChangedCallback` attribute parameter.

The following callback signature is also supported:

```csharp
private void OnMyStringChanged(DependencyPropertyChangedEventArgs args) 
{
}
```

## Attached DependencyProperties generation

Attached dependency properties need to be declared this way, with the `GeneratedDependencyProperty` located on the `GetXXX` method:

```csharp
[GeneratedDependencyProperty(DefaultValue = 0.0d, AttachedBackingFieldOwner = typeof(UIElement), Attached = true)]
public static readonly DependencyProperty LeftProperty = CreateLeftProperty();

public static double GetLeft(DependencyObject obj)
    => GetLeftValue(obj);

public static void SetLeft(DependencyObject obj, double value)
    => SetLeftValue(obj, value);
```

This dependency property will be declared as `LeftProperty`, with the local-precedence cache backing field included in the `UIElement` class.

## DependencyProperty local precedence caching

This feature is about storing the current value that can be read through the C# property getter, or the `GetXXX` method of an attached property. The objective of this feature is to avoid spending time in the dependency property system to read the value, and avoid the type cast required when getting a `DependencyProperty` value.

Backing fields are automatically generated and maintained current through `FrameworkPropertyMetadata.BackingFieldUpdateCallback` which is invoked when the highest precedence value of a `DependencyProperty` is changed.

## GeneratedDependencyProperty options

Other attribute properties are available on `GeneratedDependencyProperty` to include:

- `PropertyChangedCallback` to force the inclusion of a property changed callback method and fail the build if there is none
- `CoerceCallback` to force the inclusion of a coerce callback method and fail the build if there is none
- `Options` to specify which `FrameworkPropertyMetadataOptions` to use
- `LocalCache` to enable or disable local precedence value caching (enabled by default)
- `AttachedBackingFieldOwner` to provide the type hosting the local cache backing field for attached properties
- `ChangedCallbackName` to control the name of the property changed callback method

## Benchmarks

### WebAssembly, using the interpreter (Uno.Wasm.Bootstrap 1.3.0-dev.42)

Before DP caching:

```console
SimpleDPBenchmark.DP_Write: InProcess(Toolchain=InProcessToolchain, IterationCount=5, LaunchCount=1, WarmupCount=1)
Runtime = ; GC = 
Mean = 885.7123 us, StdErr = 12.2709 us (1.39%); N = 5, StdDev = 27.4385 us
Min = 850.0629 us, Q1 = 860.1191 us, Median = 886.3569 us, Q3 = 910.9833 us, Max = 921.5082 us
IQR = 50.8643 us, LowerFence = 783.8227 us, UpperFence = 987.2797 us
ConfidenceInterval = [780.0563 us; 991.3684 us] (CI 99.9%), Margin = 105.6560 us (11.93% of Mean)
Skewness = 0, Kurtosis = 1.19, MValue = 2
-------------------- Histogram --------------------
[846.079 us ; 879.367 us) | @@
[879.367 us ; 907.448 us) | @@
[907.448 us ; 935.549 us) | @
---------------------------------------------------

SimpleDPBenchmark.DP_Read: InProcess(Toolchain=InProcessToolchain, IterationCount=5, LaunchCount=1, WarmupCount=1)
Runtime = ; GC = 
Mean = 83.8832 us, StdErr = 0.7938 us (0.95%); N = 5, StdDev = 1.7749 us
Min = 82.4768 us, Q1 = 82.5403 us, Median = 83.0732 us, Q3 = 85.6311 us, Max = 86.6846 us
IQR = 3.0908 us, LowerFence = 77.9041 us, UpperFence = 90.2674 us
ConfidenceInterval = [77.0487 us; 90.7177 us] (CI 99.9%), Margin = 6.8345 us (8.15% of Mean)
Skewness = 0.6, Kurtosis = 1.39, MValue = 2
-------------------- Histogram --------------------
[81.867 us ; 83.683 us) | @@@
[83.683 us ; 85.486 us) | @
[85.486 us ; 87.593 us) | @
---------------------------------------------------
```

After DP caching:

````console
// * Detailed results *
SimpleDPBenchmark.DP_Write: InProcess(Toolchain=InProcessToolchain, IterationCount=5, LaunchCount=1, WarmupCount=1)
Runtime = ; GC = 
Mean = 938.0835 us, StdErr = 10.0558 us (1.07%); N = 5, StdDev = 22.4856 us
Min = 910.9253 us, Q1 = 915.3540 us, Median = 940.2124 us, Q3 = 959.7485 us, Max = 961.5698 us
IQR = 44.3945 us, LowerFence = 848.7622 us, UpperFence = 1,026.3403 us
ConfidenceInterval = [851.4996 us; 1,024.6674 us] (CI 99.9%), Margin = 86.5839 us (9.23% of Mean)
Skewness = -0.09, Kurtosis = 0.87, MValue = 2
-------------------- Histogram --------------------
[903.848 us ; 939.385 us) | @@
[939.385 us ; 962.397 us) | @@@
---------------------------------------------------

SimpleDPBenchmark.DP_Read: InProcess(Toolchain=InProcessToolchain, IterationCount=5, LaunchCount=1, WarmupCount=1)
Runtime = ; GC = 
Mean = 10.1375 us, StdErr = 0.1325 us (1.31%); N = 5, StdDev = 0.2964 us
Min = 9.6547 us, Q1 = 9.8525 us, Median = 10.2910 us, Q3 = 10.3457 us, Max = 10.3603 us
IQR = 0.4931 us, LowerFence = 9.1128 us, UpperFence = 11.0854 us
ConfidenceInterval = [8.9962 us; 11.2788 us] (CI 99.9%), Margin = 1.1413 us (11.26% of Mean)
Skewness = -0.7, Kurtosis = 1.52, MValue = 2
-------------------- Histogram --------------------
[ 9.503 us ;  9.806 us) | @
[ 9.806 us ; 10.174 us) | @
[10.174 us ; 10.512 us) | @@@
---------------------------------------------------
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/Internal-WeakEventHelper.md

---
uid: Uno.Contributing.WeakEventHelper
---

# The WeakEventHelper class

The WeakEventHelper class is an internal method that is designed to provide a
memory-friendly environment for registering to events internally in Uno.

This class is not exposed to the end-user because its patterns do not fit with the
original WinUI event-based designs of the API.

## The RegisterEvent method

The bi-directional relation of the weak registration is defined by the fact
that both the source and the target are weak. The source must be kept alive by
another longer-lived reference, and the target is kept alive by the
return disposable.

If the provided handler is collected, the registration will
be collected as well. The returned disposable is not tracked, which means that it will
not remove the registration when collected, unless the provided handler is a lambda. In
this case, the lambda's lifetime is tied to the returned disposable.

The WeakEventCollection automatically manages its internal registration list using GC events.

Here's a usage example:

 ```csharp
 private WeakEventHelper.WeakEventCollection? _sizeChangedHandlers;

 internal IDisposable RegisterSizeChangedEvent(WindowSizeChangedEventHandler handler)
 {
  return WeakEventHelper.RegisterEvent(
   _sizeChangedHandlers ??= new(),
   handler,
   (h, s, e) => (h as WindowSizeChangedEventHandler)?.Invoke(s, (WindowSizeChangedEventArgs)e)
  );
 }

 internal void RaiseEvent()
 {
    _sizeChangedHandlers?.Invoke(this, new WindowSizeChangedEventArgs());
 }
 ```

The RegisterEvent method is intentionally non-generic to avoid the cost related to AOT performance. The
performance cost is shifted to downcast and upcast checks in the `EventRaiseHandler` handlers.

The returned disposable must be used as follows :

 ```csharp
 private IDisposable? _sizeChangedSubscription;

 ...

 _sizeChangedSubscription?.Dispose();

 _sizeChangedSubscription = Window.Current.RegisterSizeChangedEvent(OnCurrentWindowSizeChanged);
 ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/ListViewBase.md

---
uid: Uno.Controls.ListViewBase
---

# ListViewBase in Uno Platform

Uno Platform's implementation of ListViewBase supports shared styling and template use with WinUI apps, whilst internally delegating to the native list view on Android and iOS for high performance. This document explains how Uno's implementation differs in some details from Windows.

For contributors, see in-depth documentation on [the internals of ListView](../uno-development/listviewbase-internals.md).

## Style reuse

This is a stripped-down view of the default style for ListView in Uno:

```xml
<!-- Default style for Windows.UI.Xaml.Controls.ListView -->
<not_win:Style TargetType="ListView">
  <Setter Property="ItemsPanel">
    <Setter.Value>
      <ItemsPanelTemplate>
        <ItemsStackPanel Orientation="Vertical" />
      </ItemsPanelTemplate>
    </Setter.Value>
  </Setter>
  <Setter Property="Template">
    <Setter.Value>
      <ControlTemplate TargetType="ListView">
        <Border>
          <ScrollViewer
              x:Name="ScrollViewer"
              not_win:Style="{StaticResource ListViewBaseScrollViewerStyle}">
            <ItemsPresenter/>
          </ScrollViewer>
        </Border>
      </ControlTemplate>
    </Setter.Value>
  </Setter>
</not_win:Style>
```

As on Windows, the `ItemsPanelTemplate` can be set; `ItemsStackPanel` and `ItemsWrapGrid` are the supported panels, and each of these supports most of the same properties as on Windows.

In fact there is only one difference from the Windows style, which is a custom Style on the `ScrollViewer` element. Below is the custom `ScrollViewer` style in its entirety:

```xml
<!-- This is an Uno-only Style which removes the ScrollContentPresenter, in order for ListViewBase to use the default Windows style (nearly)
     while delegating to a native implementation for performance. -->
<not_win:Style TargetType="ScrollViewer" x:Key="ListViewBaseScrollViewerStyle">
  <Setter Property="Template">
    <Setter.Value>
      <ControlTemplate TargetType="ScrollViewer">
        <ListViewBaseScrollContentPresenter
            x:Name="ScrollContentPresenter"
            Content="{TemplateBinding Content}"
            ContentTemplate="{TemplateBinding ContentTemplate}"
            ContentTemplateSelector="{TemplateBinding ContentTemplateSelector}"/>
      </ControlTemplate>
    </Setter.Value>
  </Setter>
</not_win:Style>
```

This style replaces the internal `ScrollPresenter` with a `ListViewBaseScrollContentPresenter`, for reasons explained below. Custom ListView/GridView styles should modify the ScrollViewer template part's style to the one shown above.

## Performance tips

### Observable collections

If you use a collection type like an array or a `List<T>` as an `ItemsSource`, then whenever you change the `ItemsSource`, all the item views will be removed and recreated. Often it's preferable to support incremental changes to your source collection.

`ListViewBase` implicitly supports incremental collection changes whenever the ItemsSource is a collection which implements the `INotifyCollectionChanged` interface. The `ObservableCollection<T>` class in the standard library is one such collection. Whenever an item is added, removed, or replaced in the collection, the corresponding `CollectionChanged` event is raised. `ListViewBase` listens to this event and only visually modifies the items that have actually changed, using platform-specific animations. The list also maintains the scroll position if possible and maintains the current selected item (unless it's removed).

Using `ObservableCollection` (or another `INotifyCollectionChanged` implementation) has performance benefits in certain situations:

1. When only modifying one or two items.
2. When modifying items out of view.
3. When fetching 'new' data that hasn't actually changed (e.g. auto refresh).

It also has UX benefits in certain situations:

1. When only adding/removing a couple of items (esp. in response to user action).
2. When modifying the items source shouldn't affect the scroll position.
3. When modifying the items source shouldn't change the user's selection.
4. When item changes should be visually highlighted.

A good use case might be, for instance, a list of reminders that the user can remove by swiping them out of view.

Note that using an observable collection adds complexity and there are some cases when it can even be anti-performant. For example, consider a list of items that can be filtered by a search term. Modifying the search term by one character (i.e., when the user types in a `TextBox`) might remove or add hundreds of items from the filtered source. Particularly on iOS, and to a lesser extent on Android, the list tries to do preprocessing on each change to determine what animations it needs, etc. The result is a noticeable lag, where changing the `ItemsSource` completely would have been nearly instantaneous.

So consider using a non-observable collection, or use the Uno-only `RefreshOnCollectionChanged` flag (which causes the native list to refresh without animations when any `CollectionChanged` event is raised), if your scenario matches the following:

1. Large numbers of items may change at once, and
2. Changes are not particularly 'meaningful' to the user.

## Internal implementation

Internally Uno's implementation differs from WinUI's. On WinUI the ScrollViewer handles scrolling, while the ItemsStackPanel or ItemsWrapGrid handles virtualization (reuse of item views). On Uno, both scrolling and virtualization are handled by NativeListViewBase, an internal panel which inherits from the native list class on each platform. ItemsStackPanel/ItemsWrapGrid exist only as logical elements of ListView/GridView, they aren't in the visual tree. Their properties are redirected to ItemsStackPanelLayout/ItemsWrapGridLayout, non-visual classes which instruct NativeListViewBase on how to lay out its views.

Since NativeListViewBase class handles scrolling, the ScrollViewer contains a ListViewBaseScrollContentPresenter which is essentially a placeholder with no functionality.

Note that this only applies when ItemsStackPanel/ItemsWrapGrid are used. When any other panel is used, ListViewBase will use an ordinary ScrollViewer + ScrollContentPresenter.

### Difference in the visual tree

```schema
 WinUI                                                    Uno
+--ListView------------------------------------------+   +--ListView------------------------------------------+
|                                                    |   |                                                    |
| +--ScrollViewer----------------------------------+ |   | +--ScrollViewer----------------------------------+ |
| |                                                | |   | |                                                | |
| | +--ScrollContentPresenter--------------------+ | |   | | +--ListViewBaseScrollContentPresenter--------+ | |
| | |                                            | | |   | | |                                            | | |
| | | +--ItemsPresenter------------------------+ | | |   | | | +--ItemsPresenter------------------------+ | | |
| | | |                                        | | | |   | | | |                                        | | | |
| | | | +--Header----------------------------+ | | | |   | | | | +--NativeListViewBase----------------+ | | | |
| | | | |                                    | | | | |   | | | | |                                    | | | | |
| | | | +------------------------------------+ | | | |   | | | | | +--Header------------------------+ | | | | |
| | | |                                        | | | |   | | | | | |                                | | | | | |
| | | | +--ItemsStackPanel-------------------+ | | | |   | | | | | +--------------------------------+ | | | | |
| | | | |                                    | | | | |   | | | | |                                    | | | | |
| | | | | +--ListViewItem------------------+ | | | | |   | | | | | +--ListViewItem------------------+ | | | | |
| | | | | |                                | | | | | |   | | | | | |                                | | | | | |
| | | | | +--------------------------------+ | | | | |   | | | | | +--------------------------------+ | | | | |
| | | | |                                    | | | | |   | | | | |                                    | | | | |
| | | | | +--ListViewItem------------------+ | | | | |   | | | | | +--ListViewItem------------------+ | | | | |
| | | | | |                                | | | | | |   | | | | | |                                | | | | | |
| | | | | +--------------------------------+ | | | | |   | | | | | +--------------------------------+ | | | | |
| | | | |                                    | | | | |   | | | | |                                    | | | | |
| | | | |                                    | | | | |   | | | | | +--Footer------------------------+ | | | | |
| | | | |                                    | | | | |   | | | | | |                                | | | | | |
| | | | |                                    | | | | |   | | | | | +--------------------------------+ | | | | |
| | | | +------------------------------------+ | | | |   | | | | |                                    | | | | |
| | | |                                        | | | |   | | | | |                                    | | | | |
| | | | +--Footer----------------------------+ | | | |   | | | | |                                    | | | | |
| | | | |                                    | | | | |   | | | | |                                    | | | | |
| | | | +------------------------------------+ | | | |   | | | | +------------------------------------+ | | | |
| | | |                                        | | | |   | | | |                                        | | | |
| | | +----------------------------------------+ | | |   | | | +----------------------------------------+ | | |
| | |                                            | | |   | | |                                            | | |
| | +--------------------------------------------+ | |   | | +--------------------------------------------+ | |
| |                                                | |   | |                                                | |
| +------------------------------------------------+ |   | +------------------------------------------------+ |
|                                                    |   |                                                    |
+----------------------------------------------------+   +----------------------------------------------------+
```

### Other differences from WinUI

* The ListView doesn't use XAML animations (`AddDeleteThemeTransition`, etc) for collection modifications, instead, it uses the animations provided by the native collection class. On iOS, these can be disabled by setting the `ListViewBase.UseCollectionAnimations` flag to `false`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Localization/LocalizationOverview.md

---
uid: Uno.Extensions.Localization.Overview
---

# Localization

It is often necessary to adapt an application to a specific subset of users within a market. **Localization** includes the type of actions developers take to modify both user interface elements and content to adhere to more languages or cultures. Specifically, text **translation** is done by applying alternate strings of text at runtime which accommodate a user's language preference.

Many apps store these pieces of text in dedicated resource files that the app parses and assigns as text throughout the application. `Uno.Extensions.Localization` provides a consistent way to resolve the text of a specific culture or locale across platforms. This feature allows for modifying them to be applied upon app restart.

It uses [Microsoft.Extensions.Localization](https://www.nuget.org/packages/Microsoft.Extensions.Localization) for any localization-related work. For documentation on the broader process of localization, read the references listed at the bottom.

## Installation

`Localization` is provided as an Uno Feature. To enable `Localization` support in your application, add `Localization` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

[!include[existing-app](../includes/existing-app.md)]

[!include[single-project](../includes/single-project.md)]

For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

## Set up localization

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host =>
        {
            host.UseLocalization()
        });
    ...
}
```

An implementation of `IStringLocalizer` (`ResourceLoaderStringLocalizer`) will be registered as a service. This service offers a consistent way to resolve localized strings. Behind the scenes, it will automatically use `ResourceManager` on Windows and `ResourceLoader` on other platforms.

### Adding language-specific resources

The `ResourceLoaderStringLocalizer` will look for `.resw` files in folders corresponding to the well-known language tag (eg en-US). For example, if the current culture is `en-US`, the `ResourceLoaderStringLocalizer` will look for `.resw` files in the `en-US` folder. If the current culture is `fr-FR`, the `ResourceLoaderStringLocalizer` will look for `.resw` files in the `fr-FR` folder.

#### Planning to support different locales

The cultures which the app will support are enumerated in a specific section of the `appsettings.json` configuration file. The `LocalizationConfiguration` section of the file should look like the code example below:

```json
{
  "LocalizationConfiguration": {
    "Cultures": [ "fr", "en" ]
  },
  ...
}
```

#### Add resource files

To add a new resource file, right-click on the project and select **Add > New Item...**. Select **Resource File (.resw)** and name it `Resources.resw`. Resource files have a key-value pair structure. The key is used to identify the resource, and the value can represent any valid property value such as translated text, the width of an item, or a color.

### Resolving localized strings

Once local-specific resources are included, the localization feature can be used to resolve those localized values.

#### Using resources in XAML

The key contains a name that corresponds to the `x:Uid` and the intended property of the XAML element. The value contains the localized text.

For example, if the `x:Uid` property of a `TextBlock` is `MyTextBlock`, the key in the resource file should be `MyTextBlock.Text`. In XAML, assigning a localized value to an element with an `x:Uid` property looks like this:

```xml
<TextBlock x:Uid="MyTextBlock" />
```

#### Using resources in code-behind

Setting the `x:Uid` property in markup is not required to resolve localized resources like text. The `IStringLocalizer` service can be resolved by the service provider. This service can be used to resolve localized strings in code behind.

```csharp
var stringLocalizer = serviceProvider.GetService<IStringLocalizer>();
```

Strings can be resolved using the indexer on the `IStringLocalizer` as a dictionary. This indexer takes a key and returns the localized string value.

```csharp
string myString = stringLocalizer["MyKey"];
```

`LocalizedString` objects are the primary type resolved from `IStringLocalizer`. While these objects can be implicitly converted to strings, they also contain additional information which may be desirable. For instance, `LocalizedString` includes a boolean indicating whether the resource was not found. This can be used to determine whether a fallback value should be used.

```csharp
LocalizedString myString = stringLocalizer["MyKey"];
var isResourceNotFound = myString.ResourceNotFound;
```

## UI Culture

Current culture or locale can be changed using `ILocalizationService`. This action requires an app restart.

```csharp
public class MainViewModel
{
    private readonly ILocalizationService localizationService;

    public MainViewModel(ILocalizationService localizationService)
    {
        this.localizationService = localizationService;
    }

    public Task ToggleLocalizationAsync()
    {
        var currentCulture = localizationService.CurrentCulture;
        var culture = localizationService.SupportedCultures.First(culture => culture.Name != currentCulture.Name);

        return localizationService.SetCurrentCultureAsync(culture);
    }
}
```

## See also

- [Software Localization](https://learn.microsoft.com/globalization/localization/localization)
- [Localization](https://learn.microsoft.com/dotnet/core/extensions/localization)
- [Using IStringLocalizer](https://learn.microsoft.com/aspnet/core/fundamentals/localization)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Logging/LoggingOverview.md

---
uid: Uno.Extensions.Logging.Overview
---

# Logging

Apps that record events typically do so for informational or diagnostic purposes, depending on the desired level of verbosity. **Logging** is the process of recording events to either a _persistent_ store such as a text file or database, or a _transient_ location like the standard output console. The `Uno.Extensions.Logging` library leverages logging capabilities tailored to the target platform to easily write entries for both app-specific and Uno internal events to one or more locations. These locations where logs can be written are referred to as **providers**. This feature enables a simple way to wire up custom log providers for locations not included by the runtime libraries or extensions.

It uses [Microsoft.Extensions.Logging](https://www.nuget.org/packages/Microsoft.Extensions.Logging) for logging abstractions. For more documentation about logging, read the references listed at the bottom.

## Installation

> [!NOTE]
> If you already have `Extensions` in `<UnoFeatures>`, then `Logging` is already installed, as its dependencies are included with the `Extensions` feature.

`Logging` is provided as an Uno Feature. To enable `Logging` support in your application, add `Logging` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

[!include[existing-app](../includes/existing-app.md)]

[!include[single-project](../includes/single-project.md)]

For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

## Platform Log Providers

To wire-up the platform-specific log providers for debug and console logging, use the extension method `UseLogging()` on the `IHostBuilder` instance:

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host => {
            host.UseLogging();
        });
    ...
}
```

## Logging

When the `UseLogging()` extension method is called, an `ILogger<T>` is registered in the service provider. This logger can be used to log messages to the console. It can then be injected into any class that needs to log messages. The `ILogger<T>` interface is generic, where `T` is the class that is logging the message. The `ILogger<T>` interface is generic, and it must be retrieved from the service provider this way. In order to scope the logger to a specific class, it cannot be used without the generic type parameter.

The library offers a number of extension methods to simplify logging messages for a multitude of situations.

## Log Levels

Sometimes it is necessary to write information to the log that varies in its verbosity or severity. For this reason, there are six log levels available to delineate the severity of an entry.

Use the following convention as a guide when logging messages:

| Level | Description |
|-------|-------------|
| Trace | Used for parts of a method to capture a flow. |
| Debug | Used for diagnostics information. |
| Information | Used for general successful information. Generally the default minimum. |
| Warning | Used for anything that can potentially cause application oddities. Automatically recoverable. |
| Error | Used for anything that is fatal to the current operation but not to the whole process. Potentially recoverable. |
| Critical | Used for anything that is forcing a shutdown to prevent data loss or corruption. Not recoverable. |

_These descriptions are adapted from those documented for the `LogLevel` enum [here](https://learn.microsoft.com/dotnet/api/microsoft.extensions.logging.loglevel)._

Because these extension methods are scoped to a specific log level, the standard `Log()` method on the `ILogger<T>` interface does not need to be used. This example shows how to log a message using the `LogInformation()` extension method:

```csharp
public class MyClass
{
    private readonly ILogger<MyClass> _logger;

    public MyClass(ILogger<MyClass> logger)
    {
        _logger = logger;
    }

    public void MyMethod()
    {
        _logger.LogInformation("My message");
    }
}
```

## Configuring Logging Output

The `UseLogging()` extension method accepts an optional `Action<ILoggingBuilder>` parameter that can be used to configure the logging output.

### Setting the Minimum Log Level

The minimum log level can be set by calling the `SetMinimumLevel()` extension method on the `ILoggingBuilder` instance. If no LogLevel is specified, logging defaults to the `Information` level which may not always be desirable. The following example shows how to change the minimum log level to `Debug`:

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host => {
            host
#if DEBUG
            .UseEnvironment(Environments.Development)
#endif
            .UseLogging(configure:
                (context, services) =>
                    services.SetMinimumLevel(
                    context.HostingEnvironment.IsDevelopment() ?
                        LogLevel.Trace :
                        LogLevel.Error)
                    )
        });
    ...
}
```

This example configures the minimum log level to `Trace` when the app is running in the `Development` environment, and `Error` otherwise. This is useful for increasing the amount of logging that occurs in that environment, and only emitting `Error` or `Critical` messages when in production.

## Serilog

Serilog is a third-party logging framework that is otherwise available as a [NuGet package](https://www.nuget.org/packages/Serilog). The benefit of using Serilog is that it provides a more robust logging framework that can be configured to log to a variety of different sinks, including the console and file. Examples of other sinks include Azure Application Insights, Seq, and many more.

An option to use Serilog is available by calling the `UseSerilog()` extension method on the `IHostBuilder` instance. This method will configure the Serilog logger to specifically not use the console or file sink by default. The following example shows how to enable Serilog:

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var appBuilder = this.CreateBuilder(args)
        .Configure(host => {
            host
            .UseSerilog();
        });
    ...
}
```

For more information about Serilog, check out [Getting Started with Serilog](https://github.com/serilog/serilog/wiki/Getting-Started).

## Uno Internal Logging

The same logging system is wired up for Uno internal messages when `UseLogging()`  is called on the `IHost` instance. This is useful for debugging Uno internals like XAML parsing and layout. While this system is enabled as part of the standard logger, it is set by default to filter out messages with a level lower than `Warning`. This is to reduce noise in the log output.

The following table describes the aspects of this Uno internal logging system which can be configured for a more suitable experience while diagnosing issues during the development process.

| ILoggingBuilder Extension method | Filtered Events  | Affected Namespace(s) |
|------------------|-------------|---------------------|
| `XamlLogLevel()` | Messages emitted by specific XAML types | `Microsoft.UI.Xaml`, `Microsoft.UI.Xaml.VisualStateGroup`, `Microsoft.UI.Xaml.StateTriggerBase`, `Microsoft.UI.Xaml.UIElement`, `Microsoft.UI.Xaml.FrameworkElement` |
| `XamlLayoutLogLevel()` | Messages emitted by the layout system | `Microsoft.UI.Xaml.Controls`, `Microsoft.UI.Xaml.Controls.Layouter`, `Microsoft.UI.Xaml.Controls.Panel` |

## See also

- [Understanding logging providers](https://learn.microsoft.com/aspnet/core/fundamentals/logging/)
- [Getting started with Serilog](https://github.com/serilog/serilog/wiki/Getting-Started)
- [List of Serilog sinks](https://github.com/serilog/serilog/wiki/Provided-Sinks)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/Lottie.md

---
uid: Uno.Features.Lottie
---

# Lottie for Uno Platform

> [!TIP]
> This article covers Uno-specific information for `Lottie`. For a full description of the feature and instructions on using it, see [Lottie](https://learn.microsoft.com/windows/communitytoolkit/animations/lottie).

* The `CommunityToolkit.WinUI.Lottie` (for WinUI) namespace provides classes for rendering Lottie animations in a `Microsoft.UI.Xaml.Controls.AnimatedVisualPlayer`.

## Using the `LottieVisualSource`

Add the following namespaces:

```xml
<Page
    ...
    xmlns:winui="using:Microsoft.UI.Xaml.Controls"
    xmlns:lottie="using:CommunityToolkit.WinUI.Lottie"
    ...>
```

```xml
<winui:AnimatedVisualPlayer
    x:Name="player"
    AutoPlay="true">

    <lottie:LottieVisualSource
        UriSource="ms-appx:///Lottie/4930-checkbox-animation.json" />
</winui:AnimatedVisualPlayer>
```

### References in a Single Project

In Uno Platform Single Project, you'll need to add the `Lottie` [Uno Feature](xref:Uno.Features.Uno.Sdk#uno-platform-features) as follows:

```xml
<UnoFeatures>
    ...
    Lottie;
    ...
</UnoFeatures>
```

### References in a Legacy Project

On all Uno Platform targets, you'll need the following packages:

* `Uno.WinUI.Lottie` (for the `LottieVisualSource`)

Additionally, on Skia Desktop targets, you'll need the following packages:

* `SkiaSharp.Views.Uno.WinUI` version 3.119.0 or later
* `SkiaSharp.Skottie` version 3.119.0 or later

On Windows/WinAppSDK, use the [`CommunityToolkit.WinUI.Lottie` NuGet package](https://www.nuget.org/packages/CommunityToolkit.WinUI.Lottie).

For more information, see [AnimatedVisualPlayer Class](https://learn.microsoft.com/uwp/api/microsoft.ui.xaml.controls.animatedvisualplayer).

## Lottie JSON file location

On WASM, iOS, and macOS, you can put the Lottie .json files directly in a folder of your app's head project (for example "Lottie/myanimation.json") and set their Build action as Content.

On Android, Lottie .json files need to be added to the Assets folder. To match the same path as for the other platforms, the file could be stored at `Assets/Lottie/myanimation.json`. Set its Build action to AndroidAsset.

To reference the animations in XAML, use the `ms-appx:` URI, in this case `ms-appx:///Lottie/myanimation.json`.

## Using `embedded://` scheme

> [!WARNING]
> This feature is only available on Uno Platform targets. WinUI on Windows is not supported.

You can put the file as `<EmbeddedResource>` in your assembly and retrieve it using the following URL format as `UriSource`:

```uri
embedded://<assemblyname>/<resource name>
```

* You can specify `.` in assembly name to use the Application's assembly.
* You can specify `(assembly)` in path: will be replaced by assembly name.
* AssemblyName is case insensitive, **but the resource name is**.

## Theme Properties

As Microsoft documented in the [release notes for Lottie-Windows v6.1.0](https://github.com/windows-toolkit/Lottie-Windows/releases/tag/v6.1.0), there is a new feature called _Theme property binding_. This allows to dynamically change a value (usually a color) at runtime.

To use this feature on Windows, you need to generate code with the [`LottieGen` tool](https://learn.microsoft.com/windows/communitytoolkit/animations/lottie-scenarios/getting_started_codegen). On Uno supported platforms, it's available at runtime using the `ThemableLottieVisualSource` instead of the original `LottieAnimatedVisualSource`.

Here's how to use this feature:

1. Add a _css-like_ declaration to your Lottie shape like this then put this in the name of the shape. That means the `nm` property in the json-generated file.

   ```css
   { Color: var(MyColor); }
   ```

   In that case, it will create a property (variable) named `MyColor`. It is possible to reuse the same property name on many layers in the same lottie file.

2. Use it that way:

   ```xml
   <winui:AnimatedVisualPlayer
       x:Name="player"
       AutoPlay="true">

       <lottie:ThemableLottieVisualSource
           x:Name="animation"
           UriSource="ms-appx:///Assets/Lottie/CheckBoxAnimation.json" />
   </winui:AnimatedVisualPlayer>
   ```

3. Change the property in your code:

   ```csharp
   animation.SetColorThemeProperty("MyColor", Color.FromArgb(1, 255, 0, 0));
   ```

**Notes**:

* Changing a property will force the player to reload its animation. Not only the animation will be restarted, but it can also be heavy on the CPU. Animating these properties should be avoided.

* To reach compatibility with code generated by _LottieGen_ on Windows, it is possible to derive from `ThemableLottieVisualSource` and create required properties like this:

  ```csharp
  [Bindable]
  public sealed class CheckBoxAnimation : ThemableLottieVisualSource
  {
    public Color MyColor
    {
      get => GetColorThemeProperty(nameof(MyColor));
      set => SetColorThemeProperty(nameof(MyColor), value);
    }
  }
  ```

## Limitations

On Android, the `Stretch` mode of `Fill` is not currently supported.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/interop/MSAL.md

---
uid: Uno.Interop.MSAL
---

# Azure Authentication with MSAL

Uno can be used to build applications using authentication. A popular mechanism is Azure Authentication (Azure AD, Azure AD B2C or ADFS) and it can be used directly using the Microsoft Authentication Library for .NET (MSAL.NET) available from NuGet.

> MSAL.NET is the successor of ADAL.NET library which shouldn't be used for new apps. If you are migrating an application to Uno using ADAL.NET, you should first [migrate it to MSAL.NET](https://learn.microsoft.com/azure/active-directory/develop/msal-net-migration).

Quick-start for MSAL: https://learn.microsoft.com/azure/active-directory/develop/quickstart-v2-uwp

## General usage

To use MSAL into an Uno project, follow the following steps:

1. Add a reference to [`Uno.WinUI.MSAL`](https://www.nuget.org/packages/Uno.UI.MSAL) (or `Uno.UI.MSAL` for UWP) package to all your heads - including UWP.

2. Follow [Initialize client applications using MSAL.NET](https://learn.microsoft.com/azure/active-directory/develop/msal-net-initializing-client-applications) to integrate with your app.

3. Change the `IPublicCLientApplication` initialization to add a call to `.WithUnoHelpers()` like this:

   ```csharp
   IPublicClientApplication _app = PublicClientApplicationBuilder.Create(clientId)
       [...]
       .WithUnoHelpers() // Add this line before the .Build()
       .Build();
   ```

4. Where you are using the *Interactive* mode (`_app.AcquireTokenInteractive`), add another call to `.WithUnoHelpers()` like this:

   ```csharp
   var authResult = await _app.AcquireTokenInteractive(scopes)
       .WithPrompt(Prompt.SelectAccount)
       [...]
       .WithUnoHelpers() // Add this line on interactive token acquisition flow
       .ExecuteAsync();
   ```

By adding those helpers, Uno will correctly add required initializations to MSAL for all supported platforms.

## WinUI

There is nothing to change for WinUI. The `.WithUnoHelpers()` does nothing on WinUI, they are just there to allow the code to compile without introducing `#if` conditionals in your code.

## Android

You'll need to setup the return URI following the Microsoft documentation:

* [Configuration requirements and troubleshooting tips for Xamarin Android with MSAL.NET](https://learn.microsoft.com/entra/identity-platform/msal-net-xamarin-android-considerations)

* [Microsoft Authentication Library for .NET](https://learn.microsoft.com/entra/msal/dotnet/)

* There is no need to call `.WithParentActivity()` as it is already initialized by `.WithUnoHelpers()`.

## iOS & macOS

Follow [Considerations for using Xamarin iOS with MSAL.NET](https://learn.microsoft.com/entra/identity-platform/msal-net-xamarin-ios-considerations).

* There is no need to call `.WithParentActivity()` as it is already initialized by `.WithUnoHelpers()`.

## WebAssembly

Particularities for WASM:

* Currently, .NET 9 [enforces COOP/COEP](https://github.com/dotnet/runtime/issues/109937) for WebAssembly applications. This prevents any cross-site behavior, including authentication through a browser window popup. There are currently two workarounds for this:

  * Use an Uno [Server project](xref:Uno.GettingStarted.UsingWizard#server) which will host the WASM app on its own, and will not have COOP enabled. WASM Debugging may not work as intended in this context. Starting the Server project without the debugger will work.
  * Run the app via `dotnet serve` from the CLI. This approach will not allow for debugging.

* Because of browser security requirements, the `redirectUri` must be on the same **protocol** (http/https), **hostname** & **port** as your application. The path is not particularly important and there's a good practice to set the callback URI to some static content defined in your `wwwroot` folder (could be an empty page). For example:

  * Define this *Redirect URI* in Azure AD: `http://localhost:5000/authentication/login-callback.htm` - for local development using the port  `5000` with `http` protocol. (Azure AD accepts non-`https` redirect URIs for localhost to simplify development - `https` will work too).

    > Note about the port number: If you're using IISExpress to run your application from VisualStudio, it could be on another port. That's the default port for Kestrel. Make sure to register the right port in Azure AD and provide the right uri at runtime.
    >
    > You'll also need to register addresses for the other environments and adjust the code to use the right IDs & URIs. The redirect Uri must always be on the same hostname & port or otherwise it won't work.

  * Optionally, a file in the Wasm project `wwwroot/authentication/login-callback.htm` with empty content (you could display a message like « *Please wait while the authentication process completes* » for slower browsers).

* Token cache is *in-memory* for now­. The library is not persisting the token anywhere in the browser yet. The app can save it.

## More resources

* [Best practices for MSAL.NET](https://learn.microsoft.com/entra/msal/dotnet/getting-started/best-practices)
* [Handle errors and exceptions in MSAL.NET](https://learn.microsoft.com/entra/msal/dotnet/advanced/exceptions/msal-error-handling)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Maui/MauiOverview.md

---
uid: Uno.Extensions.Maui.Overview
---
# .NET MAUI Embedding

With .NET MAUI Embedding 3rd party control libraries for .NET MAUI can be used within an Uno Platform application. Note that these controls work only for target platforms .NET MAUI reaches – iOS, Android, MacOS, and Windows.

## Overview

The integration of .NET MAUI controls into an Uno application consists of two parts, the .NET MAUI class library and the MauiHost control.

The `MauiHost` control (that's part of the Uno.Extensions.Maui.WinUI package) is added to any Uno page or control to embed a .NET MAUI control. The `Source` property on the `MauiHost` is the type of .NET MAUI control that will be added as a child of the `MauiHost` control. As the .NET MAUI control will be added as a child, it will inherit the data context of the `MauiHost` control. The DataContext on the `MauiHost` is mapped to the `BindingContext` of the .NET MAUI control.

It's recommended that instead of hosting individual .NET MAUI controls in a `MauiHost` element, a `ContentView` should be created inside a .NET MAUI class library and set as the `Source` on a `MauiHost` element. This makes it easier to add multiple .NET MAUI controls, as well as setting properties, including data binding, in XAML.

## MAUI Embedding with Skia rendered applications

.NET MAUI Embedding is also supported in applications that use Skia rendering via [Native Control Embedding](xref:Uno.Skia.Embedding.Native).

> [!IMPORTANT]
> Native elements require non-infinite layout bounds in order to render correctly. Refer to the [Features section](xref:Uno.Skia.Embedding.Native#features) of the Native Control Embedding documentation for more information on how to use Skia rendering with native controls.

## Get Started - New Uno Application

> [!NOTE]
> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.vs2022).

For new applications created using the Uno Platform Template Wizard for Visual Studio, .NET MAUI Embedding can be selected as a feature when creating the application.

1. Start by selecting either the **Blank** or **Recommended** preset template.

    ![Select startup type](Assets/GettingStarted01-StartupType.png)

1. Select the Features section and include the MAUI Embedding feature, before clicking the Create button to complete the creation of the application.

    ![Select feature - .NET MAUI Embedding](Assets/GettingStarted03-MAUIEmbedding.png)

1. In addition to the typical Uno Platform application structure, there is a .NET MAUI class library (e.g. SimpleMauiApp.MauiControls). The MauiControls class library is where you add references to third-party .NET MAUI control libraries, add any services or call registration/initialization methods on the third-party libraries, and of course, define the .NET MAUI controls that you want to display within the application.

    ![Project structure](Assets/GettingStarted04-ProjectStructure.png)

1. The application can be run by selecting the desired platform in the dropdown, then pressing F5 or clicking the Run button. The default layout shows a text, "Hello Uno Platform", which is an Uno TextBlock, followed by an Image, two TextBlock, and, a Button, which are all .NET MAUI controls. For more detailed instructions specific to each platform, refer to the [Debug the App](xref:Uno.GettingStarted.CreateAnApp.VS2022#debug-the-app) documentation.

    ![Selecting target](Assets/GettingStarted04.1-ProjectStructure.png)

    ![Running on Windows](Assets/GettingStarted05-RunningOnWindows.png)

These steps can also be achieved via the command lines by invoking the following commands

```dotnetcli
dotnet new install uno.templates
dotnet new unoapp -preset blank -maui -o SimpleMauiApp
```

## Get Started - Existing Uno Application

.NET MAUI Embedding can be added to any existing Uno application via the following steps. The .NET MAUI Embedding feature is only supported in Uno applications that target iOS, Android, MacCatalyst, and Windows, as shown in the Platforms folder in the following solution structure.

### MauiEmbedding Dependencies

#### [**Single Project Template**](#tab/single-project)

![Starting solution structure - SingleProject](Assets/GettingStartedExisting01-StartSingleProjectStructure.png)

##### UnoFeatures

In the **.csproj** file, find the `<UnoFeatures>` property and add `MauiEmbedding`. This step adds all the dependencies you need for you to have Maui Embedding working with your project.

```diff
<UnoFeatures>
   ...
   Serialization;
   Localization;
   Navigation;
+  MauiEmbedding;
</UnoFeatures>
```

#### [**Multi-Head Project Template (Legacy)**](#tab/multi-project)

![Starting solution structure](Assets/GettingStartedExisting01-StartProjectStructure.png)

1. **Uno.Extensions.Maui.WinUI**
Add a reference in the existing class library to [Uno.Extensions.Maui.WinUI](https://www.nuget.org/packages/Uno.Extensions.Maui.WinUI). It's not necessary to add this package to other projects.

    ![Adding reference to Uno.Extensions.Maui.WinUI](Assets/GettingStartedExisting02-AddingReference.png)

1. **Package References**

    If the application is using Central Package Management, remove PackageVersion elements for the following packages

    ```xml
    <Project ToolsVersion="15.0">
      <ItemGroup>
        ...
        <!--<PackageVersion Include="Microsoft.Windows.SDK.BuildTools" Version="10.0.22621.3233" /> -->
        <!-- <PackageVersion Include="Microsoft.WindowsAppSDK" Version="1.5.240311000" />-->
        ...
        <!--<PackageVersion Include="Xamarin.Google.Android.Material" Version="1.9.0.2" />-->
        ...
      </ItemGroup>
    </Project>
    ```

    In the project file for the existing Class Library, add the following ItemGroup, and remove the specified PackageReferences

    ```xml
    <Project Sdk="Microsoft.NET.Sdk">
      ...
      <!-- Add this ItemGroup to add references to Android packages -->
      <ItemGroup Condition="$(IsAndroid)">
        <PackageReference Include="Xamarin.Google.Android.Material" VersionOverride="1.9.0.2" />
        <PackageReference Include="Xamarin.AndroidX.Navigation.UI" VersionOverride="2.6.0.1" />
        <PackageReference Include="Xamarin.AndroidX.Navigation.Fragment" VersionOverride="2.6.0.1" />
        <PackageReference Include="Xamarin.AndroidX.Navigation.Runtime" VersionOverride="2.6.0.1" />
        <PackageReference Include="Xamarin.AndroidX.Navigation.Common" VersionOverride="2.6.0.1" />
      </ItemGroup>
      ...
      <Choose>
        <When Condition="$(IsWinAppSdk)">
          ...
          <!-- Remove these package references and default to those specified by .NET Maui -->
          <!--<ItemGroup>
            <PackageReference Include="Microsoft.WindowsAppSDK" />
            <PackageReference Include="Microsoft.Windows.SDK.BuildTools" />
          </ItemGroup>-->
        </When>
    </Project>
    ```

    Update the project file (csproj) for the Mobile target with the following PackageReferences

    ```xml
    <Project Sdk="Microsoft.NET.Sdk">
      ...
      <Choose>
        <When Condition="$(IsAndroid)">
          <ItemGroup>
            <!-- Add, or amend, the reference to Xamarin.Google.Android.Material with the VersionOverride -->
            <PackageReference Include="Xamarin.Google.Android.Material" VersionOverride="1.9.0.2" />

            <!-- Add reference to additional Android wrapper libraries -->
            <PackageReference Include="Xamarin.AndroidX.Navigation.UI" VersionOverride="2.6.0.1" />
            <PackageReference Include="Xamarin.AndroidX.Navigation.Fragment" VersionOverride="2.6.0.1" />
            <PackageReference Include="Xamarin.AndroidX.Navigation.Runtime" VersionOverride="2.6.0.1" />
            <PackageReference Include="Xamarin.AndroidX.Navigation.Common" VersionOverride="2.6.0.1" />
            ...
          </ItemGroup>
          ...
    </Project>
    ```

    Update the project file (csproj) for the Windows target to remove the following PackageReferences

    ```xml
    <Project Sdk="Microsoft.NET.Sdk">
      ...
      <ItemGroup>
        <PackageReference Include="Uno.WinUI" />

        <!-- Remove the following PackageReferences and use the packages included by .NET MAUI -->
        <!-- <PackageReference Include="Microsoft.WindowsAppSDK" /> -->
        <!-- <PackageReference Include="Microsoft.Windows.SDK.BuildTools" />-->
      </ItemGroup>
    </Project>
    ```

***

### Add MAUI Application

1. **MAUI Class Library**

    Add a new .NET MAUI Class Library to the application, `ExistingUnoApp.MauiControls`.

    ![.NET MAUI Class Library](Assets/GettingStartedExisting03-MauiClassLibrary.png)

1. **MauiControls - EmbeddedControl**

    Remove the Class1.cs file that was created by the .NET MAUI Class Library template and add a .NET MAUI ContentView, `EmbeddedControl`

    ![.NET MAUI ContentView](Assets/GettingStartedExisting04-ContentView.png)

1. **MauiControls - App**

    Add a new .NET MAUI Resource Dictionary called App.

    ![.NET MAUI ResourceDictionary](Assets/GettingStartedExisting05-ResourceDictionary.png)

    This will generate App.xaml and App.xaml.cs, which we'll update to inherit from the `Application` base class instead of being a ResourceDictionary

    ```xml
    <?xml version = "1.0" encoding = "UTF-8" ?>
    <Application xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
          xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
          x:Class="ExistingUnoApp.MauiControls.App">
      <Application.Resources>
        <ResourceDictionary>
          <ResourceDictionary.MergedDictionaries>
          </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
      </Application.Resources>
    </Application>
    ```

    ```csharp
    public partial class App : Application
    {
        public App()
        {
            InitializeComponent();
        }
    }
    ```

1. **ProjectReference - MauiControls**

    In the project file (csproj) for the Uno class library, add a reference to the .NET MAUI class library

    ```xml
    <Project Sdk="Microsoft.NET.Sdk">
      ...
      <ItemGroup>
        <!-- Add the reference to the .NET MAUI class library as a ProjectReference -->
        <ProjectReference Include="..\..\ExistingUnoApp.MauiControls\ExistingUnoApp.MauiControls.csproj" />
      </ItemGroup>
      ...
    </Project>

    ```

1. **EmbeddingApplication**

    Back in the Uno class library, change the base class in `App.xaml.cs` (XAML) or `App.cs` (C# Markup) from `Application` to `EmbeddingApplication`

    ```csharp
    public class App : EmbeddingApplication
    {
        protected Window? MainWindow { get; private set; }
        protected IHost? Host { get; private set; }
    }
    ```

    Also, in the `App.xaml` file, change the type of the root element to `EmbeddingApplication`

    ```xml
    <unoxt:EmbeddingApplication xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                                xmlns:unoxt="using:Uno.Extensions.Maui.Platform"
                                x:Class="ExistingUnoApp.MauiControls.App">
        <Application.Resources>
            <ResourceDictionary>
                <ResourceDictionary.MergedDictionaries>
                </ResourceDictionary.MergedDictionaries>
            </ResourceDictionary>
        </Application.Resources>
    </unoxt:EmbeddingApplication>
    ```

1. **UseMauiEmbedding**

    If using Uno.Extensions, add UseMauiEmbedding to the IHost builder, before the Customize method. Alternatively, add a call to the UseMauiEmbedding extension method for the application instance.

    **With** Uno.Extensions

    ```csharp
    public class App : EmbeddingApplication
    {
        protected async override void OnLaunched(LaunchActivatedEventArgs args)
        {
            var builder = this.CreateBuilder(args)
                ...
                .UseMauiEmbedding<MauiControls.App>()
                ...
                .Configure(host => host
                ...
    ```

    **Without** Uno.Extensions

    ```csharp
    public class App : EmbeddingApplication
    {
        protected async override void OnLaunched(LaunchActivatedEventArgs args)
        {
          ...
          this.UseMauiEmbedding<MauiControls.App>(MainWindow);
          ...
    ```

1. **MauiHost**

    Add a `MauiHost` element to the MainPage and set the Source property to match the EmbeddedControl

    ```xml
    <Page x:Class="ExistingUnoApp.Presentation.MainPage"
      ... >

      <Grid>
        ...
        <embed:MauiHost x:Name="MauiHostElement"
                MaxHeight="500"
                xmlns:embed="using:Uno.Extensions.Maui"
                xmlns:controls="using:ExistingUnoApp.MauiControls"
                Source="controls:EmbeddedControl" />
        ...
      </Grid>
    </Page>
    ```

> [!NOTE]
> A MaxHeight is set here to ensure proper layout and rendering of the embedded control on Skia rendered applications. Refer to the [MAUI Embedding with Skia rendered applications](#maui-embedding-with-skia-rendered-applications) section for more information.

Build and run on each target platform to see the .NET MAUI control embedded within the Uno application.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/MediaPlayerElement.md

---
uid: Uno.Controls.MediaPlayerElement
---

# MediaPlayerElement

See [Microsoft API reference for MediaPlayerElement](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediaplayerelement).

## Media formats

| Supported Formats          | iOS | Android | Wasm | Skia Desktop  | Remarks                                              |
|----------------------------|:----:|:---------:|:------:|:---------:|------------------------------------------------------------------------------|
| Local/Remote MP3 Support   |  ✅  |    ✅    |  ✅   |    ✅     |                                                                              |
| Local/Remote MPEG4 Support |  ✅  |    ✅    |  ✅   |    ✅     |                                                                            |
| HLSv3 Support              |  ✅  |    ✅    |  ✅   |    ✅     |                                                                            |
| HLSv4 Support              |  ✅  |    ✅    |  ✅   |    ✅     |                                                                            |
| 3GP Support                |  ✅  |    ✅    |  ✅   |    ✅     |3GP with AMR Narrow Band (SAMR) audio codec does not work on iOS (See notes) |
| FLV Support                |  -    |    ✅   |  ✅   |    ✅     |                                                                            |
| MOV Support                |  ✅  |    -     |  -     |    -      |                                                                           |
| MKV Support                |  -    |    ✅   |  ✅   |    ✅     |                                                                            |
| AVI Support                |  -    |    ✅   |  ✅   |    ✅     |                                                                             |
| OGG Support                |  -    |    -    |  ✅   |    ✅     |                                                                            |
| MPEG-Dash Support          |  -    |    -    |  -     |    -      |                                                                           |
| Smooth Streaming Support   |  -    |    -    |  -     |    -      |                                                                           |

### Notes

- Uno's MediaPlayerElement relies on AVPlayer for iOS and AndroidMediaPlayer for Android. Please, refer to those native players documentation for more information about supported audio and video formats.
- Uno's MediaPlayerElement relies on VLC and libvlc on Linux. please follow [these instructions](https://github.com/videolan/libvlcsharp/blob/3.x/docs/linux-setup.md) to get the necessary dependencies.
- If you need to set source programmatically (i.e., using `_mediaPlayerElement.Source = [source]`), please note that only sources created with `MediaSource.CreateFromUri()` are currently supported.

## Features

| Section            | Feature                                        | iOS & Android (native) | Wasm (native) | Skia | Remarks                                       |
| ------------------ | ---------------------------------------------- | :--------------------: | :-----------: | :--: | --------------------------------------------- |
| MediaPlayerElement | AutoPlay                                       |            ✅           |       ✅       |   ✅  |                                               |
|                    | Poster image                                   |            ✅           |       ✅       |   ✅  | Does not show when playing music              |
|                    | Enable/Disable MediaTransportControls          |            ✅           |       ✅       |   ✅  |                                               |
|                    | Stretch                                        |            ✅           |       ✅       |   ✅  | Stretch.None behaves like Stretch.Fill on iOS |
|                    | Pause media when headphones unplugged          |            ✅           |       -         |   -   |                                               |
| TransportControls  | Transport controls custom style                |            ✅           |       ✅       |   ✅  |                                               |
|                    | Play/Pause                                     |            ✅           |       ✅       |   ✅  |                                               |
|                    | Stop                                           |            ✅           |       ✅       |   ✅  |                                               |
|                    | Seek                                           |            ✅           |       ✅       |   ✅  |                                               |
|                    | Volume change                                  |            ✅           |       ✅       |   ✅  |                                               |
|                    | Mute                                           |            ✅           |       ✅       |   ✅  |                                               |
|                    | Show elapsed time                              |            ✅           |       ✅       |   ✅  |                                               |
|                    | Show remaining time                            |            ✅           |       ✅       |   ✅  |                                               |
|                    | Show/Hide MediaTransportControls automatically |            ✅           |       ✅       |   ✅  |                                               |
|                    | MediaTransportControls compact mode            |            ✅           |       ✅       |   ✅  |                                               |
|                    | Show/Hide MediaTransportControls commands      |            ✅           |       ✅       |   ✅  |                                               |
|                    | Enable/Disable MediaTransportControls commands |            ✅           |       ✅       |   ✅  |                                               |
|                    | Skip forward                                   |            ✅           |       ✅       |   ✅  |                                               |
|                    | Skip backward                                  |            ✅           |       ✅       |   ✅  |                                               |
|                    | Show buffering progress                        |            ✅           |       ✅       |   ✅  |                                               |
|                    | Zoom mode                                      |            ✅           |       ✅       |   ✅  |                                               |
|                    | Full-screen mode                               |            ✅           |       ✅       |   -    |                                               |
|                    | Playlists support                              |            ✅           |       -        |   -    |                                               |
|                    | Change playback rate                           |            -             |       ✅       |   ✅  |                                               |
|                    | Player controls on locked screen support       |            -             |       -        |   -   |                                               |
|                    | Subtitles support                              |            -             |       -        |   -   |                                               |
|                    | Languages support                              |            -             |       -        |   -   |                                               |

## Getting Started

To add video playback functionality, include the following XAML snippet:

```xml
<MediaPlayerElement Source="ms-appx:///Assets/SampleMedia/myfile.mp4"
                    MaxWidth="400"
                    AutoPlay="False"
                    AreTransportControlsEnabled="True" />
```

Make sure to enable the required feature in your `UnoFeatures` to include the necessary packages. Add `MediaPlayerElement;` as shown below:

```diff
<UnoFeatures>
<!-- Existing features -->
+  MediaPlayerElement;
</UnoFeatures>
```

### iOS

Add the following to your info.plist:

```xml
<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsArbitraryLoads</key>
    <true/>
    <key>NSExceptionMinimumTLSVersion</key>
    <string>TLSv1.2</string>
</dict>
```

__Note:__ Don't just copy/paste, but properly setup `NSAppTransportSecurity` as required by your project

### Android

Add the following to your AndroidManifest.xml

```xml
<!-- Required to play remote media -->
<uses-permission android:name="android.permission.INTERNET" />
<!-- Required to keep the screen on while playing -->
<uses-permission android:name="android.permission.WAKE_LOCK" />
```

### Skia

On some weaker devices, the first load of a `MediaPlayerElement` instance is extremely slow. To attempt to preload media playback resources on app startup, enable the `PreloadMediaPlayer` option in the host builder where supported.

```csharp
var host = UnoPlatformHostBuilder.Create()
            .App(() => new App())
            .UseX11(hostBuilder => hostBuilder.PreloadMediaPlayer(true))
            .UseWin32(hostBuilder => hostBuilder.PreloadMediaPlayer(true))
            .Build();
```

## Future improvement

- React to audio focus changes (pause/stop playback or reduce audio volume)
- Subtitles support
- Languages support
- Buffering of next playlist element when using MediaPlaybackList
- Cast to device
- Playlist for Wasm
- Download option

## Known issues

- `[iOS]` Volume flyout does not display (Uno issue)
- `[All]` Dynamic width/height not supported when playing audio
- `[All]` Sometimes flickers during resizing when using dynamic width/height

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/MenuFlyout.md

---
uid: Uno.Controls.MenuFlyout
---

# MenuFlyout

MenuFlyout is implemented to provide support for `ContextMenu` and `MenuBar` features.

## Platform-specific behavior

On iOS and Android, the flyout can either be displayed using native popup, or Uno managed popups.

The default behavior of the MenuFlyout is to follow the value `FeatureConfiguration.Style.UseUWPDefaultStyles`, but this can be changed per MenuFlyout using the `FlyoutBase.UseNativePopup` property.

### iOS (native)

#### Destructive action

> If an alert button results in a destructive action, such as deleting content, set the button’s style to Destructive so that it gets appropriate formatting by the system.

```xml
xmlns:toolkit="using:Uno.UI.Toolkit"

<MenuFlyoutItem Text="Dangerous Menu Item 1"
                toolkit:MenuFlyoutItemExtensions.IsDestructive="True" />
```

#### Cancel button text

```xml
xmlns:toolkit="using:Uno.UI.Toolkit"

<MenuFlyout UseNativePopup="True"
            toolkit:MenuFlyoutExtensions.CancelTextIosOverride="Custom cancel text">
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Navigation/NavigationOverview.md

---
uid: Uno.Extensions.Navigation.Overview
---

# Introduction

## What is Navigation?

Navigation needs to encompass a range of UI concepts:

* Navigation between pages in a <a href="https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.frame" target="_blank">`Frame`</a> (forward and backwards)
* Switching between menu items in a <a href="https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.navigationview?view=winui-3.0" target="_blank">`NavigationView`</a>, or between tab items in a <a href="https://platform.uno/uno-toolkit/" target="_blank">`TabBar`</a>
* Loading content into a <a href="https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.contentcontrol" target="_blank">ContentControl</a>
* Loading and toggling visibility of child elements in a <a href="https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.grid" target="_blank">`Grid`</a>
* Displaying a <a href="https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.primitives.popup" target="_blank">`Popup`</a> or <a href="https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/flyouts" target="_blank">`Flyout`</a>
* Prompt a <a href="https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.contentdialog" target="_blank">`ContentDialog`</a> or <a href="https://learn.microsoft.com/uwp/api/windows.ui.popups.messagedialog" target="_blank">`MessageDialog`</a>

[!include[getting-help](../includes/getting-help.md)]

## Installation

`Navigation` is provided as an Uno Feature. To enable `Navigation` support in your application, add `Navigation` to the `<UnoFeatures>` property in the Class Library (.csproj) file.

[!include[existing-app](../includes/existing-app.md)]

[!include[single-project](../includes/single-project.md)]

For more information about `UnoFeatures` refer to our [Using the Uno.Sdk](xref:Uno.Features.Uno.Sdk) docs.

## What triggers Navigation?

Navigation can be triggered for a number of reasons:

* Change view
Either based on the type of View or the type of ViewModel to show
* Display data
The view to show is based on the type of data to display (eg display ProductX)
* Prompt, or request, for data
The view to show is based on the type of data being requested (eg Country picker)
Prompt the user using a flyout or content dialog to get a response

## Architecture Objectives

### Navigation needs to be accessible from anywhere

* View (Code behind)
i.e. in context of a page/usercontrol
* View (XAML)
i.e. using attached properties
* ViewModel (Presentation)
i.e. in a context that doesn't have access to the UI layer

### Navigation needs to make use of available data

* Uri
Used to share links to the app (eg deeplink)
* DTO
If an instance of an entity is already in memory, navigation should support passing the existing entity between views
* ViewModel
The type of viewmodel (associated with the view) to navigate to
* View
The type of view to navigate to

## Common Scenarios

### 1. Navigating between pages (code behind)

* Navigate forward to a new page by calling `NavigateRouteAsync` with the route to navigate to

    **XAML**

    ```xml
    <Page x:Class="Playground.Views.HomePage">
        <Button Click="{x:Bind GoToSecondPageClick}"
                Content="Go to Second Page - Code behind" />
    </Page>
    ```

    **C#**

    ```csharp
    public sealed partial class HomePage : Page
    {
        public async void GoToSecondPageClick()
        {
            var nav = this.Navigator();
            await nav.NavigateRouteAsync(this, "Second");
        }
    }
    ```

* Navigate back to the previous page by calling `NavigateBackAsync`

    **XAML**

    ```xml
    <Page x:Class="Playground.Views.SecondPage">
        <Button Click="{x:Bind GoBackClick}"
                Content="Go Back" />
    </Page>
    ```

    **C#**

    ```csharp
    public sealed partial class SecondPage : Page
    {
        public async void GoBackClick()
        {
            var nav = this.Navigator();
            await nav.NavigateBackAsync(this);
        }
    }
    ```

### 2. Navigating between view models

* Navigate forward to a new page by calling `NavigateViewModelAsync` with the route to navigate to

    **XAML**

    ```xml
    <Page x:Class="Playground.Views.HomePage">
        <Button Click="{x:Bind ViewModel.GoToSecondPageClick}"
                Content="Go to Second Page - View Model" />
    </Page>
    ```

    **C#**

    ```csharp
    public sealed partial class HomeViewModel
    {
        private readonly INavigator _navigator;
        public HomeViewModel(INavigator navigator)
        {
            _navigator = navigator;
        }

        public async void GoToSecondPageClick()
        {
            await _navigator.NavigateViewModelAsync<SecondViewModel>(this);
        }
    }
    ```

* Navigate back to the previous page by calling `NavigateBackAsync`

    **XAML**

    ```xml
    <Page x:Class="Playground.Views.SecondPage">
        <Button Click="{x:Bind ViewModel.GoBackClick}"
                Content="Go Back" />
    </Page>
    ```

    **C#**

    ```csharp
    public sealed partial class SecondViewModel
    {
        private readonly INavigator _navigator;
        public SecondViewModel(INavigator navigator)
        {
            _navigator = navigator;
        }

        public async void GoBackClick()
        {
            await _navigator.NavigateBackAsync(this);
        }
    }
    ```

### 3. Navigating between pages (XAML)

* Navigate forward to new page by specifying the route in the `Navigation.Request` attached property

    **XAML**

    ```xml
    <Page x:Class="Playground.Views.HomePage">
        <Button uen:Navigation.Request="Second"
                Content="Go to Second Page - XAML" />
    </Page>
    ```

* Navigate to previous page by specifying the back qualifier in the `Navigation.Request` attached property
    **XAML**

    ```xml
    <Page x:Class="Playground.Views.SecondPage">
        <Button uen:Navigation.Request="-"
                Content="Go Back" />
    </Page>
    ```

### 4. Navigating between pages (XAML)

* Navigate forward to new page and clearing back-stack by specifying the route in the `Navigation.Request` attached property with the clear back-stack qualifier ("-/")
    **XAML**

    ```xml
    <Page x:Class="Playground.Views.HomePage">
        <Button uen:Navigation.Request="-/Second"
                Content="Go to Second Page - XAML" />
    </Page>
    ```

### 5. Prompt user - Message Dialog

* Prompt the user with a message using the `ShowMessageDialogAsync` method.
    **C#**

    ```csharp
    public sealed partial class HomePage : Page
    {
        public async void PromptWithMessageDialogClick()
        {
            var nav = this.Navigator();
            var messageResult = await nav.ShowMessageDialogAsync(this,"Warning about something","Alert");
        }
    }
    ```

### 6. Switching items in NavigationView

* Define selectable navigation view items by setting the `Region.Name`. When an item is selected, the child element of the `Grid` with the same `Region.Name` will be set to `Visible` (and the others set back to `Collapsed`)
    **XAML**

    ```xml
    <Page x:Class="Playground.Views.NavigationViewPage">

        <Grid>
            <muxc:NavigationView uen:Region.Attached="true">
                <muxc:NavigationView.MenuItems>
                    <muxc:NavigationViewItem Content="Products"
                                             uen:Region.Name="Products" />
                    <muxc:NavigationViewItem Content="Deals"
                                             uen:Region.Name="Deals" />
                    <muxc:NavigationViewItem Content="Profile"
                                             uen:Region.Name="Profile" />
                </muxc:NavigationView.MenuItems>
                <Grid uen:Region.Attached="True">
                    <StackPanel uen:Region.Name="Products"
                                Visibility="Collapsed">
                        <TextBlock Text="Products" />
                    </StackPanel>
                    <StackPanel uen:Region.Name="Deals"
                                Visibility="Collapsed">
                        <TextBlock Text="Deals" />
                    </StackPanel>
                    <StackPanel uen:Region.Name="Profile"
                                Visibility="Collapsed">
                        <TextBlock Text="Profile" />
                    </StackPanel>
                </Grid>
            </muxc:NavigationView>
        </Grid>
    </Page>
    ```

### 7. Displaying content in a ContentControl

* Specify the `Region.Name` of the nested control and the route of the `UserControl` to display in the `Navigation.Request` attached property
    **XAML**

    ```xml
    <Page x:Class="Playground.Views.ContentControlPage">
        <Grid>
            <Grid.RowDefinitions>
                <RowDefinition />
                <RowDefinition Height="Auto" />
            </Grid.RowDefinitions>
                <Button Content="Show profile"
                        uen:Navigation.Request="./Info/Profile" />
                <ContentControl uen:Region.Attached="True"
                                uen:Region.Name="Info"
                                Grid.Row="1" />
        </Grid>
    </Page>

    <UserControl x:Class="Playground.Views.ProfileUserControl">
    …
    </UserControl>
    ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/NavigationView.md

---
uid: Uno.Controls.NavigationView
---

# NavigationView

The `NavigationView` control provides top-level navigation for your app. It adapts to a variety of screen sizes and supports both top and left navigation styles. For more information about its usage, see [NavigationView Microsoft documentation](https://learn.microsoft.com/windows/apps/design/controls/navigationview).

## Back button visibility

The `IsBackButtonVisible` property is by default set to `Auto`. This means the system chooses whether or not to display the back button. As per the design guidelines on Android, this means it is not shown by default and the [**hardware back button**](xref:Uno.Features.HardwareBackButton) should be used instead. If you prefer to always display the back button, set the `IsBackButtonVisible` property to `Visible`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/external/uno.chefs/doc/Overview.md

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/xf-migration/overview.md

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/external/uno.chefs/doc/Overview.md

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Mvux/Overview.md

# Source: https://raw.githubusercontent.com/unoplatform/uno.chefs/refs/heads/master/doc/Overview.md

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Mvux/Overview.md

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Markup/Overview.md

---
uid: Uno.Extensions.Markup.Overview
---

# C# Markup

## Overview

C# Markup is a declarative, fluent-style syntax for defining the layout of an application in C#. With C# Markup you can define both the layout and the logic of your application using the same language. C# Markup leverages the same underlying object model as XAML, meaning that it has all the same capabilities such as data binding, converters, and access to resources. You can use all the built-in controls, any custom controls you create, and any 3rd party controls all from C# Markup.

You will quickly discover why C# Markup is a developer favorite with:

- A Declarative syntax
- Strongly typed data binding
- Intellisense and compile-time validation
- Refactoring support
- Custom Controls and 3rd party libraries

> [!Video https://www.youtube-nocookie.com/embed/BC3c1qO_kbU]

Let's jump in and take a look at a simple sample that displays 'Hello Uno Platform!' in the center of the screen:

```cs
public sealed partial class MainPage : Page
{
    public MainPage()
    {
        this.Content
        (
            new StackPanel()
                .VerticalAlignment(VerticalAlignment.Center)
                .HorizontalAlignment(HorizontalAlignment.Center)
                .Children
                (
                    new TextBlock()
                        .Text("Hello Uno Platform!")
                )
        );
    }
}
```

The first thing you will notice with C# Markup is that there is nothing special to learn. You can simply create a new instance of the controls you want to work with (eg `new TextBlock()`) and set properties using the generated extension method with the same name (eg `.Text("Hello Uno Platform!')`).

Unlike XAML which is littered with string constants, C# Markup provides a strongly typed API for setting properties. For example, in XAML you would set `HorizontalAlignment` with `HorizontalAlignment="Center"`, but in C# Markup you would use the `HorizontalAlignment` enum with `HorizontalAlignment.Center`, ensuring that you get compile time validation and intellisense for all the available values.

## Getting Started

Let's take a look at how to get started with C# Markup. We'll start with a simple sample that displays a counter and a button that increments the counter by a step size. The sample will have a ViewModel that has a `Count` and a `Step` property, as well as an `IncrementCommand` that increments the `Count` by the `Step` when executed.

### Constructor and Properties

We'll start with creating a control and setting some properties, as shown in the following example that creates a `TextBlock`. The fluent API allows you to chain together multiple properties, as shown in the following example that sets the `Margin`, `TextAlignment`, and `Text` properties.

```cs
new TextBlock()
    .Margin(12)
    .TextAlignment(TextAlignment.Center)
    .Text("Counter: 0")
```

Similar to the `HorizontalAlignment` property mentioned earlier, the `TextAlignment` property is set using an enum rather than a string constant. This ensures that you get compile time validation and intellisense for all the available values.

In XAML you would set the `Margin` property using a single number (for example `<TextBlock Margin="12" />`), but the actual `Margin` property on the `TextBlock` class requires a `Thickness` type, resulting in the following C# Markup:

```cs
new TextBlock().Margin(new Thickness(12))
```

However, C# Markup provides automatic type conversion for common types such as `Thickness`, as well as a number of other types such as `Brush`, `Color`, `CornerRadius`, `FontFamily`, `Geometry` and `ImageSource`. This means that you can set the `Margin` property using a single number, as shown in the following example.

```cs
new TextBlock().Margin(12)
```

### Data Binding

Since our counter example requires the value of the `TextBlock` to be updated each time the counter changes, we'll need to use data binding. C# Markup provides a strongly typed API for data binding, as shown in the following example that binds the `Text` property to the `Count` property of the ViewModel.

```cs
new TextBlock().Text(() => vm.Count)
```

At this point, you might be wondering what the `vm` is. The `vm` is a placeholder reference for the ViewModel type that you provide to the `DataContext` extension.

```cs
.DataContext(new MainViewModel(), (page, vm) => page
    .Content(
        new TextBlock().Text(() => vm.Count)
    )
);
```

We refer to `vm` as a placeholder because at this point it is not actually a reference to the ViewModel. It is simply a placeholder that allows us to provide a strongly typed API for data binding. Rather than invoking the code `vm.Count` when the `TextBlock` is created, the expression tree, `() => vm.Count` is used to create a binding expression that will be evaluated when the `DataContext` for the `TextBlock` is set.

In the above example, an instance of `MainViewModel` is provided to the `DataContext` extension method. If an instance of the ViewModel isn't available at the time the `DataContext` is set, you can provide the type of the ViewModel instead, as shown in the following example.

```cs
.DataContext<MainViewModel>((page, vm) => page
    .Content(
        new TextBlock().Text(() => vm.Count)
    )
);
```

Currently, the data binding is directly on the `Count` property meaning that the text shown in the `TextBlock` will just be the value of the `Count` property. However, we want to display the text "Counter: {value}" where {value} is the value of the `Count` property. To do this we can provide a delegate that will be invoked each time the value of the `Count` property changes, as shown in the following example.

```cs
new TextBlock().Text(() => vm.Count, count => $"Counter: {count}")
```

In some cases, you need more control over the binding, such as when you need to change the binding mode or provide a converter. In these cases, you can use the `Bind` extension method, as shown in the following example that two-way data binds the `Step` property to the `Text` property of a `TextBox`.

```cs
new TextBox().Text(x => x.Bind(() => vm.Step).TwoWay()),
```

### Resources

C# Markup provides a strongly typed API to get, create, and add both static and theme resources. For example, to set the `Background` to the theme resource, get the `ApplicationPageBackgroundThemeBrush` from the default WinUI Fluent theme:

```cs
this.Background(ThemeResource.Get<Brush>("ApplicationPageBackgroundThemeBrush"));
```

## Counter Sample

Putting all the pieces we've just covered together, we have the layout of a counter application that will increment the `Count` by the `Step`.

```csharp
public sealed partial class MainPage : Page
{
    public MainPage()
    {
        this.DataContext(new MainViewModel(),(page, vm) => page
            .Background(ThemeResource.Get<Brush>("ApplicationPageBackgroundThemeBrush"))
            .Content(new StackPanel()
                .VerticalAlignment(VerticalAlignment.Center)
                .Children(
                    new Image()
                        .Width(150)
                        .Height(150)
                        .Margin(12)
                        .HorizontalAlignment(HorizontalAlignment.Center)
                        .Source("ms-appx:///Assets/logo.png"),
                    new TextBox()
                        .Margin(12)
                        .HorizontalAlignment(HorizontalAlignment.Center)
                        .PlaceholderText("Step Size")
                        .Text(x => x.Bind(() => vm.Step).TwoWay()),
                    new TextBlock()
                        .Margin(12)
                        .HorizontalAlignment(HorizontalAlignment.Center)
                        .TextAlignment(TextAlignment.Center)
                        .Text(() => vm.Count, txt => $"Counter: {txt}"),
                    new Button()
                        .Margin(12)
                        .HorizontalAlignment(HorizontalAlignment.Center)
                        .Command(() => vm.IncrementCommand)
                        .Content("Click me to increment Counter by Step Size")
                )
            )
        );
    }
}
```

## Conclusion

This overview provides a brief introduction to C# Markup, including how to create controls, set properties, and use data binding and resources. For a comprehensive guide on using C# Markup to build a complete application, check out the full [Counter tutorial](xref:Uno.Workshop.Counter). This tutorial offers two variants: [C# Markup + MVUX](xref:Uno.Workshop.Counter.CSharp.MVUX) and [C# Markup + MVVM](xref:Uno.Workshop.Counter.CSharp.MVVM).

## Next Steps

Learn more about:

- [Binding, Static & Theme Resources](xref:Uno.Extensions.Markup.DependencyPropertyBuilder)
  - [Binding 101](xref:Uno.Extensions.Markup.Binding101)
  - [Converters](xref:Uno.Extensions.Markup.Converters)
  - [Using Static & Theme Resources](xref:Uno.Extensions.Markup.StaticAndThemeResources)
  - [Using Uno.Themes.WinUI.Markup](xref:Uno.Extensions.Markup.UnoThemes)
- [Attached Properties](xref:Uno.Extensions.Markup.AttachedProperties)
- [Styles](xref:Uno.Extensions.Markup.Styles)
- [Templates](xref:Uno.Extensions.Markup.Templates)
- [VisualStateManagers](xref:Uno.Extensions.Markup.VisualStateManager)
  - [Storyboards](xref:Uno.Extensions.Markup.Storyboards)
- [Generating C# Extensions for your libraries](xref:Uno.Extensions.Markup.GeneratingExtensions)
- [Upgrading C# Markup](xref:Uno.Extensions.Markup.Upgrading)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/PasswordVault.md

---
uid: Uno.Features.PasswordVault
---

# Credentials storage

> [!TIP]
> This article covers Uno-specific information for `Windows.Security.Credentials.PasswordVault` API. For a full description of the feature and instructions on using it, see [PasswordVault Class](https://learn.microsoft.com/uwp/api/windows.security.credentials.passwordvault).

* The `PasswordVault` is a credentials manager that is persisted using a secured storage.
* `PasswordCredential` is used to manipulate passwords in the vault.

## Supported features

| Feature              | Windows | Android | iOS     | Web (WASM)  Linux (Skia) | Win 7 (Skia) | Tizen |
|----------------------|---------|---------|---------|--------------------------|--------------|-------|
| `PasswordVault`      | ✔       | ✔       | ✔       | ✖           | ✖            | ✖            | ✖     |
| `PasswordCredential` | ✔       | Partial | Partial | Partial   | ✖            | ✖            | ✖     |

## `PasswordVault`

The `PasswordVault` is designed to be a safe place to store the user's credentials and tokens.
It's backed by the hardware encryption mechanism of each platform, which provides a high level of security.
However, the `PasswordVault` does **not** offer any memory security feature.

Below see the implementation information for each platform:

### [**Android**](#tab/android)

The implementation uses the `AndroidKeyStore` which was introduced with API 18 (4.3).
The `KeyStore` is used to generate a symmetric key which is then used to encrypt and decrypt a file persisted in the application directory.
The key is managed by the `KeyStore` itself, which usually uses the hardware component to persist it. The key is not even accessible to the application.

For more information, see [KeyStore](https://developer.android.com/reference/java/security/KeyStore).

### [**iOS**](#tab/iOS)

The `PasswordVault` is directly stored in the iOS `KeyChain` which is the recommended way to store secrets on iOS devices.
It's backed by hardware components that ensure that the data is almost impossible to retrieve if not granted.

For more information, see [Storing Keys in the Keychain](https://developer.apple.com/documentation/security/certificate_key_and_trust_services/keys/storing_keys_in_the_keychain).

### [**WebAssembly**](#tab/WebAssembly)

There is no way to persist a secured data in a Web browser. Even if we generate a key to encrypt it,
there is no safe place to store this key except by relying on server components, which broke the offline support (and Progressive Web App).
So currently we preferred to **not** implement the `PasswordVault`. It will throw a `NotSupportedException` when you try to create a new instance.

---

## PasswordCredential

This class is implemented, however, it never hides the password like the WinUI does.
This means that the [`RetrievePassword` method](https://learn.microsoft.com/uwp/api/windows.security.credentials.passwordcredential.retrievepassword#Windows_Security_Credentials_PasswordCredential_RetrievePassword) does nothing, but we recommend still using it in order to ensure cross-platform compatibility.

The [`Properties` property](https://learn.microsoft.com/uwp/api/windows.security.credentials.passwordcredential.properties#Windows_Security_Credentials_PasswordCredential_Properties) is not implemented.

## Sample

### Storing a credential

```csharp
var vault = new Windows.Security.Credentials.PasswordVault();
vault.Add(new Windows.Security.Credentials.PasswordCredential(
    "My App", username, password));
```

### Retrieving a credential

```csharp
var vault = new Windows.Security.Credentials.PasswordVault();
var credential = vault.Retrieve("My App", userName);
credential.RetrievePassword();
var password = credential.Password;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/Pivot.md

---
uid: Uno.Controls.Pivot
---

# Pivot in Uno Platform

## Pivot WinUI Default Style

Uno provides a full support of the Pivot WinUI style.
The Pivot with the default style looks the same on all platforms, both statically and in motion.
If you need to have a custom design, you can just update the Pivot WinUI default style for your needs.

## Pivot Native Default Style

With the `NativeDefaultPivot` style on Android and iOS, the Pivot uses the native implementations of each platform.
Of course, you can still bind to its properties in XAML as you normally would.
This is another powerful option to have: for some apps it makes sense to look as 'native' as possible, for others it's desirable to have a rich, customized UI.
You may even want to mix and match different approaches for different screens in your app.

### Native Pivot Style for Android and iOS

If you want to use the native Pivot style for either Android or iOS, you'll need to specify the following `Pivot` style as well as a `NativePivotPresenter` style.

```xml
<!-- Default native Pivot styles (for both Android and iOS) -->
<not_win:Style x:Key="NativeDefaultPivot"
                TargetType="Pivot">
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="Pivot">
                <NativePivotPresenter x:Name="NativePresenter" />
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</not_win:Style>
```

#### NativePivotPresenter Android Style

Note that this one is written in C# rather than XAML because of the `SlidingTabLayout` object.

```csharp
var style = new Style(typeof(NativePivotPresenter))
{
    Setters =
    {
        new Setter<NativePivotPresenter>("Template", pb => pb
            .Template = new ControlTemplate(() =>
                new Grid
                {
                    RowDefinitions =
                    {
                        new RowDefinition(){ Height = GridLength.Auto},
                        new RowDefinition(){ Height = new GridLength(1, GridUnitType.Star)},
                    },

                    Children =
                    {
                        // Header
                        new Border
                        {
                            Child = new Uno.UI.Controls.SlidingTabLayout(ContextHelper.Current)
                            {
                                LayoutParameters = new Android.Views.ViewGroup.LayoutParams(Android.Views.ViewGroup.LayoutParams.MatchParent, Android.Views.ViewGroup.LayoutParams.WrapContent),
                            },
                            BorderThickness = new Thickness(0,0,0,1),
                        }
                        .Apply(b => b.SetBinding("Background", new Binding { Path = "Background", RelativeSource = RelativeSource.TemplatedParent }))
                        .Apply(b => b.SetBinding("BorderBrush", new Binding { Path = "BorderBrush", RelativeSource = RelativeSource.TemplatedParent })),

                        // Content
                        new ExtendedViewPager(ContextHelper.Current)
                        {
                            OffscreenPageLimit = 1,
                            PageMargin = (int)TypedValue.ApplyDimension(ComplexUnitType.Dip, 4, ContextHelper.Current.Resources.DisplayMetrics),
                            SwipeEnabled = true,
                        }
                        .Apply(v => Grid.SetRow(v, 1))
                    }
            })
        )
    }
};

Style.RegisterDefaultStyleForType(typeof(NativePivotPresenter), style);
```

#### NativePivotPresenter iOS Style

```xml
<ios:Style TargetType="NativePivotPresenter">
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="Pivot">
                <Grid>
                    <Grid.RowDefinitions>
                        <RowDefinition Height="1*" />
                        <RowDefinition Height="Auto" />
                    </Grid.RowDefinitions>
                    <Grid x:Name="PART_Content"
                            Grid.Row="0" />
                    <UITabBar Grid.Row="1" />
                </Grid>
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</ios:Style>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/Popup.md

---
uid: Uno.Controls.Popup
---

# Popup

## Customizing light-dismiss overlay

If you want to show a dimmed overlay underneath the popup, set the `Popup.LightDismissOverlayMode` property to `On`.

If you wish to customize the overlay color, add the following to your top-level `App.Resources`:

```xml
<SolidColorBrush x:Key="PopupLightDismissOverlayBackground"
                 Color="Red" />
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/RefreshContainer.md

---
uid: Uno.Controls.RefreshContainer
---

# RefreshContainer (Pull to Refresh)

## Summary

`RefreshContainer` is used to provide the pull-to-refresh UI functionality primarily for scrollable content.

The touch-based pull capability is currently available only on Android, iOS and Windows (via WinUI). However, on the other targets you can still manually call the `RequestRefresh()` method to display the refresh UI.

To handle the refresh, subscribe to the `RefreshRequested` event. You can perform any kind of work in the handler. To use `async/await`, make the method `async`, get the deferral in the beginning of the method, and complete it after all required work is finished:

```csharp
refreshContainer.RefreshRequested += OnRefreshRequested;

private async void OnRefreshRequested(
    object sender,
    RefreshRequestedEventArgs e)
{
    var deferral = e.GetDeferral();
    await Task.Delay(3000); // Do some asynchronous work
    deferral.Complete();
}
```

## Android and iOS specifics

On Android and iOS `RefreshContainer` requires a scrollable element as the child of the control. This can be either a `ScrollViewer` or a list-based control like `ListView`:

```xml
<RefreshContainer>
    <ScrollViewer>
        <!-- Your content that should support refresh -->
    </ScrollViewer>
</RefreshContainer>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.toolkit.ui/refs/heads/main/doc/controls/ResponsiveView.md

---
uid: Toolkit.Controls.ResponsiveView
---
# ResponsiveView

The `ResponsiveView` provides the ability to display different content based on screen size, making it easy to adapt to various devices.

## Remarks

The `ResponsiveView` control adapts to different screen sizes by dynamically choosing the right template. It looks at the current screen width and the defined templates. Since not all templates need a value, the control ensures a smooth user experience by picking the smallest defined template that satisfies the width requirements. If no match is found, it defaults to the largest defined template.

## Properties

| Property            | Type               | Description                                             |
| ------------------- | ------------------ | ------------------------------------------------------- |
| `NarrowestTemplate` | `DataTemplate`     | Template to be displayed on the narrowest screen size.  |
| `NarrowTemplate`    | `DataTemplate`     | Template to be displayed on a narrow screen size.       |
| `NormalTemplate`    | `DataTemplate`     | Template to be displayed on a normal screen size.       |
| `WideTemplate`      | `DataTemplate`     | Template to be displayed on a wide screen size.         |
| `WidestTemplate`    | `DataTemplate`     | Template to be displayed on the widest screen size.     |
| `ResponsiveLayout`  | `ResponsiveLayout` | Overrides the screen size threshold/breakpoints.        |

### ResponsiveLayout

Provides the ability to override the breakpoint for each screen size: `Narrowest`, `Narrow`, `Normal`, `Wide`, and `Widest`.

#### Properties

| Property     | Type     | Description            |
| ------------ | -------- | ---------------------- |
| `Narrowest`  | `double` | Default value is 150.  |
| `Narrow`     | `double` | Default value is 300.  |
| `Normal`     | `double` | Default value is 600.  |
| `Wide`       | `double` | Default value is 800.  |
| `Widest`     | `double` | Default value is 1080. |

#### Resolution Logics

The layouts whose value(ResponsiveExtension) or template(ResponsiveView) is not provided are first discarded. From the remaining layouts, we look for the first layout whose breakpoint at met by the current screen width. If none are found, the first layout is return regardless of its breakpoint.

Below are the selected layout at different screen width if all layouts are provided:

| Width          | Layout    |
|----------------|-----------|
| 149            | Narrowest |
| 150(Narrowest) | Narrowest |
| 151            | Narrowest |
| 299            | Narrowest |
| 300(Narrow)    | Narrow    |
| 301            | Narrow    |
| 599            | Narrow    |
| 600(Normal)    | Normal    |
| 601            | Normal    |
| 799            | Normal    |
| 800(Wide)      | Wide      |
| 801            | Wide      |
| 1079           | Wide      |
| 1080(Widest)   | Widest    |
| 1081           | Widest    |

Here are the selected layout at different screen width if only `Narrow` and `Wide` are provided:

| Width              | Layout |
|--------------------|--------|
| 149                | Narrow |
| 150(~~Narrowest~~) | Narrow |
| 151                | Narrow |
| 299                | Narrow |
| 300(Narrow)        | Narrow |
| 301                | Narrow |
| 599                | Narrow |
| 600(~~Normal~~)    | Narrow |
| 601                | Narrow |
| 799                | Narrow |
| 800(Wide)          | Wide   |
| 801                | Wide   |
| 1079               | Wide   |
| 1080(~~Widest~~)   | Wide   |
| 1081               | Wide   |

## Usage

If you prefer instructional videos, you can follow our tutorials on how to work with ResponsiveView using XAML or C# markup:

### [**XAML**](#tab/techbite-xaml) <!-- markdownlint-disable-line MD051 -->

> [!Video https://www.youtube-nocookie.com/embed/VgpC79ErNRI]

### [**C# Markup**](#tab/techbite-csmarkup) <!-- markdownlint-disable-line MD051 -->

> [!Video https://www.youtube-nocookie.com/embed/lQueBn6LEyU]

---

> [!TIP]
> It is not necessary to define every template or layout breakpoint: Narrowest, Narrow, Normal, Wide, Widest. You can just define the bare minimum needed.

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:ResponsiveView>
    <!-- note:  -->
    <utu:ResponsiveView.NarrowTemplate>
        <DataTemplate>
            <!-- Narrow content -->
        </DataTemplate>
    </utu:ResponsiveView.NarrowTemplate>
    <utu:ResponsiveView.WideTemplate>
        <DataTemplate>
           <!-- Wide content -->
        </DataTemplate>
    </utu:ResponsiveView.WideTemplate>
</utu:ResponsiveView>
```

Using `ResponsiveLayout` to customize the screen size breakpoints.

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...
<utu:ResponsiveView>
    <utu:ResponsiveView.ResponsiveLayout>
        <utu:ResponsiveLayout>
            <utu:ResponsiveLayout.Narrow>350</utu:ResponsiveLayout.Narrow>
            <utu:ResponsiveLayout.Wide>1200</utu:ResponsiveLayout.Wide>
        </utu:ResponsiveLayout>
    </utu:ResponsiveView.ResponsiveLayout>

    <utu:ResponsiveView.NarrowTemplate>
        <DataTemplate>
            <!-- Narrow content -->
        </DataTemplate>
    </utu:ResponsiveView.NarrowTemplate>
    <utu:ResponsiveView.WideTemplate>
        <DataTemplate>
           <!-- Wide content -->
        </DataTemplate>
    </utu:ResponsiveView.WideTemplate>
</utu:ResponsiveView>
```

> [!NOTE]
> The `ResponsiveLayout` can also be provided from different locations. In order of precedences, they are:
>
> - from the `.ResponsiveLayout` property
> - in `ResponsiveView`'s parent `.Resources` with `x:Key="DefaultResponsiveLayout"`, or its ancestor's...
> - in `Application.Resources` with `x:Key="DefaultResponsiveLayout"`
> - from the hardcoded `ResponsiveHelper.DefaultLayout` which is defined as [150/300/600/800/1080]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/SKCanvasElement.md

---
uid: Uno.Controls.SKCanvasElement
---

# SKCanvasElement

When creating an Uno Platform application, developers might want to create elaborate 2D graphics using a library such as [Skia](https://skia.org) or [Cairo](https://www.cairographics.org), rather than using, for example, a simple [Canvas](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.canvas). To support this use case, SkiaSharp comes with an [SKXamlCanvas](https://learn.microsoft.com/dotnet/api/skiasharp.views.windows.skxamlcanvas) element that allows for drawing in an area using SkiaSharp.

On Uno Platform targets with Skia rendering, we can utilize the pre-existing internal Skia canvas used to render the application window instead of creating additional Skia surfaces. Unlike `SKXamlCanvas` which doesn't support hardware acceleration on Skia targets yet, hardware acceleration comes out of the box if the Uno application is already using OpenGL to render. Moreover, `SKXamlCanvas` has to make additional buffer copying, which can be skipped with this implementation.

> [!IMPORTANT]
> . The `Uno.WinUI.Graphics2DSK` package which provides the `SKCanvasElement` class is referenced for you by Uno.Sdk automatically when the `Skia` or `SkiaRenderer` features are present, and is always referenced on the netX.0-desktop target. However, the class is only supported (i.e. `SKCanvasElement.IsSupportedOnCurrentPlatform` returns true) on the netX.0-desktop target and on other targets that use skia rendering, for example netX.0-android with the `SkiaRenderer` feature.

`SKCanvasElement` is an abstract `FrameworkElement` for 2D drawing with Skia. To use `SKCanvasElement`, create a subclass of `SKCanvasElement` and override the `RenderOverride` method, which takes the canvas that will be drawn on and the clipping area inside the canvas.

```csharp
protected abstract void RenderOverride(SKCanvas canvas, Size area);
```

When adding your drawing logic in `RenderOverride` on the provided canvas, you can assume that the origin is already translated so that `0,0` is the origin of the element, not the entire window. Drawing outside this area will be clipped.

Additionally, `SKCanvasElement` has an `Invalidate` method that invalidates the `SKCanvasElement` and triggers a redraw. The drawing of the `SKCanvasElement` is often cached and will not be updated unless `Invalidate` is called.

Since `SKCanvasElement` is just a FrameworkElement, controlling the dimensions of the drawing area is done by manipulating the layout of the element, e.g. by overriding MeasureOverride and ArrangeOverride.

Finally, since `SKCanvasElement` makes use of the Skia-based rendering infrastructure and is therefore only supported when skia rendering is used, there's a static method that provides a check at runtime for whether `SKCanvasElement` can function on the current platform.

```csharp
public static bool IsSupportedOnCurrentPlatform();
```

Attempting to create an `SKCanvasElement` instance when `IsSupportedOnCurrentPlatform` returns false throws an exception.

## Full example

For a complete example that showcases how to work with `SKCanvasElement`, see [this sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SKCanvasElementShowcase) in the Uno.Samples repository

## WinAppSDK Specifics

When using the SKCanvasElement and running on WinAppSDK, make sure to create an `x64` or `ARM64` configuration:

- In the Visual Studio configuration manager, create an `x64` or `ARM64` solution configuration
- Assign it to the Uno Platform project
- Debug your application using the configuration relevant to your current environment

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/ScrollViewer.md

---
uid: Uno.Controls.ScrollViewer
---

# ScrollViewer in Uno Platform

The `ScrollViewer` represents a scrollable area that can contain other visible elements. For more information about its usage, see [Microsoft API reference for ScrollViewer](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.scrollviewer).

## ScrollViewer visual diagram

The `ScrollViewer` is a more intricate control and it's not always easy to have a good overview/understanding of some of its properties.
So, here is a more visual diagram to better understand how some of the main ScrollViewer properties are supposed to behave.

![ScrollViewer Visual Diagram](assets/scrollviewer/scrollviewer-diagram.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.toolkit.ui/refs/heads/main/doc/controls/ShadowContainer.md

---
uid: Toolkit.Controls.ShadowContainer
---

# ShadowContainer

## Summary

The `ShadowContainer` provides the ability to layer multiple shadows to its content.

> [!Video https://www.youtube-nocookie.com/embed/mohQvifKF0Y]

## Package Reference

A reference to [Uno.Toolkit.Skia.WinUI](https://www.nuget.org/packages/Uno.Toolkit.Skia.WinUI) package must be added to your Uno app so you can access `ShadowContainer` class and its features.

## Remarks

Currently, the control simply mimics the shape of its content by size and by corner radius. Complicated shapes, such as text or pictures with alpha, are not yet supported.

> [!WARNING]
> In order for inset (inner) shadows to be painted on top of the background, the `ShadowContainer`'s child element should not have a `.Background` or `.Fill`(for `Shape`s), it should be omitted or set to transparent. And, the background/fill value should be instead set on the `ShadowContainer` itself.

```xml
<!-- DO -->
<utu:ShadowContainer Background="..." Shadows="...">
    <Grid>...</Grid>
</utu:ShadowContainer>

<!-- DON'T -->
<utu:ShadowContainer Shadows="...">
    <Grid Background="..." >...</Grid>
</utu:ShadowContainer>
```

### XAML

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:ShadowContainer>
    <utu:ShadowContainer.Shadows>
        <utu:ShadowCollection>
            <utu:Shadow ... />
            <utu:Shadow ... />
        </utu:ShadowCollection>
    </utu:ShadowContainer.Shadows>

    <SomeControl />

</utu:ShadowContainer>
```

### Inheritance

`Object` &#8594; `DependencyObject` &#8594; `UIElement` &#8594; `FrameworkElement` &#8594; `Control` &#8594; `ContentControl` &#8594; `ShadowContainer`

### Properties

| Property   | Type               | Description                                                                                                                                                                                                                                    |
|------------|--------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Shadows`  | `ShadowCollection` | The collection of shadows that will be displayed under your control. A `ShadowCollection` can be stored in a resource dictionary to have a consistent style throughout your app. The `ShadowCollection` implements `INotifyCollectionChanged`. |

## Shadow

Dependency object representing a single shadow.

### Shadow Properties

| Property     | Type     | Description                                                                                            |
|--------------|----------|--------------------------------------------------------------------------------------------------------|
| `IsInner`    | `bool`   | True if this shadow is an inner shadow (similar to `inset` of `box-shadow` in CSS).                    |
| `OffsetX`    | `double` | The X offset of the shadow.                                                                            |
| `OffsetY`    | `double` | The Y offset of the shadow.                                                                            |
| `Color`      | `Color`  | The color of the shadow. It will be multiplied by the `Opacity` property before rendering.             |
| `Opacity`    | `double` | The opacity of the shadow.                                                                             |
| `BlurRadius` | `double` | The radius of the blur that will be applied to the shadow **[0..100]**.                                |
| `Spread`     | `double` | The spread will inflate or deflate (if negative) the control shadow size **before** applying the blur. |

As mentioned `IsInner` is similar to `inset` of `box-shadow` in CSS. See the images below that illustrate its effects:

With `inset` an Inner Shadow is rendered.

![CSS box-shadow with inset](../assets/box-shadow-inset.png)

Without `inset` a Drop (outer) Shadow is rendered.

![CSS box-shadow without inset](../assets/box-shadow.png)

For more info on how `inset` works in CSS for `box-shadow`, see [`box-shadow` values](https://developer.mozilla.org/docs/Web/CSS/box-shadow#values).

> [!IMPORTANT]
> Be careful not to confuse the `Shadow` property with the `Shadows` property. The singular `Shadow` property comes from `UIElement`. To add shadows to the `ShadowContainer`, use only the `Shadows` property.

### Shadow Order

When adding shadows to the `ShadowContainer`, keep in mind that the order in which you place them matters, as shadows can overlap each other, affecting the final result. Shadows implemented last may overlap shadows added previously. See the examples below:

The following example has a red shadow and a green shadow, respectively. See that the green shadow overlaps the red shadow, since the green one was added last:

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<Page.Resources>
    <utu:ShadowCollection x:Key="InnerShadows">
        <utu:Shadow BlurRadius="30"
                    OffsetX="50"
                    OffsetY="50"
                    Opacity="1"
                    Spread="-5"
                    Color="Red"
                    IsInner="True" />
        <utu:Shadow BlurRadius="30"
                    OffsetX="-50"
                    OffsetY="-50"
                    Opacity="1"
                    Spread="-5"
                    Color="Green"
                    IsInner="True" />
    </utu:ShadowCollection>
</Page.Resources>

<StackPanel>
    <utu:ShadowContainer Background="LightGray"
                         Shadows="{StaticResource InnerShadows}">
        <Grid Height="100"
              Width="100"
              CornerRadius="50" />
    </utu:ShadowContainer>
</StackPanel>
```

Result:

![Green shadow covers red](../assets/green-shadow-cover.png)

Now, let's change the shadow order and place the red shadow at the end. Note that the red shadow now overlaps the green one:

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<Page.Resources>
    <utu:ShadowCollection x:Key="InnerShadows">
        <utu:Shadow BlurRadius="30"
                    OffsetX="-50"
                    OffsetY="-50"
                    Opacity="1"
                    Spread="-5"
                    Color="Green"
                    IsInner="True" />
        <utu:Shadow BlurRadius="30"
                    OffsetX="50"
                    OffsetY="50"
                    Opacity="1"
                    Spread="-5"
                    Color="Red"
                    IsInner="True" />
    </utu:ShadowCollection>
</Page.Resources>

<StackPanel>
    <utu:ShadowContainer  Background="LightGray"
                          Shadows="{StaticResource InnerShadows}">
        <Grid Height="100"
              Width="100"
              CornerRadius="50" />
    </utu:ShadowContainer>
</StackPanel>
```

Result:

![Red shadow covers green](../assets/red-shadow-cover.png)

## Usage

See how to add shadows to your controls with the following code and the result.

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<Page.Resources>
    <Color x:Key="UnoColor">#7a67f8</Color>
    <Color x:Key="UnoPink">#f85977</Color>

    <!-- You can define your shadows in the resource dictionary -->
    <utu:ShadowCollection x:Name="ButtonShadows">
        <utu:Shadow BlurRadius="15"
                    OffsetY="8"
                    Opacity="0.5"
                    Color="{StaticResource UnoColor}" />
    </utu:ShadowCollection>
</Page.Resources>

<utu:ShadowContainer Background="White">
    <utu:ShadowContainer.Shadows>
        <!-- You can define your shadows directly -->
        <utu:ShadowCollection x:Name="Shadows">
            <utu:Shadow BlurRadius="20"
                        OffsetX="10"
                        OffsetY="10"
                        Opacity="0.5"
                        Spread="-5"
                        Color="{StaticResource UnoColor}" />
            <utu:Shadow BlurRadius="20"
                        OffsetX="-10"
                        OffsetY="-10"
                        Opacity="0.5"
                        Spread="-5"
                        Color="{StaticResource UnoPink}" />
        </utu:ShadowCollection>
    </utu:ShadowContainer.Shadows>
    <StackPanel Width="300"
                Padding="16"
                BorderThickness="1"
                CornerRadius="20"
                Spacing="16">

        <TextBlock Style="{StaticResource TitleTextBlockStyle}" Text="Add many shadows" />
        <TextBlock Style="{StaticResource BodyTextBlockStyle}" Text="You can either declare shadows directly, or put your ShadowCollection in a resource dictionary." />

        <StackPanel Margin="0,16,0,0"
                    HorizontalAlignment="Center"
                    Orientation="Horizontal"
                    Spacing="16">

            <!-- Reference to the dictionary button shadows -->
            <utu:ShadowContainer Shadows="{StaticResource ButtonShadows}">
                <Button Background="{StaticResource UnoColor}"
                        BorderThickness="1"
                        Content="Add Shadow"
                        Foreground="White" />
            </utu:ShadowContainer>

            <!-- Reference to the dictionary button shadows -->
            <utu:ShadowContainer Shadows="{StaticResource ButtonShadows}">
                <Button Background="{StaticResource UnoColor}"
                        BorderThickness="1"
                        Content="Remove Shadow"
                        Foreground="White" />
            </utu:ShadowContainer>
        </StackPanel>
    </StackPanel>
</utu:ShadowContainer>
```

![2 colored shadows with 2 buttons with single shadows](../assets/shadows-colors.png)

## Neumorphism

[Following neumorphism rules](https://neumorphism.io), choose one background color, 2 shadow colors, and create a cool neumorphism style.

To achieve neumorphic depth effects (instead of having a raised element, it will feel as if it was hollow or bulging), set the `IsInner` property of a shadow to `True`.

- The shadow will then be displayed *inside* the element instead of behind.
- This is equivalent to the `inset` property of the CSS `box-shadow` as mentioned previously.

## Usage

See how to integrate neumorphism into your designs with the following code and the result.

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<Page.Resources>
    <Color x:Key="UnoColor">#7a67f8</Color>

    <utu:ShadowCollection x:Key="NeumorphismRaising">
        <!-- Bottom right darker violet -->
        <utu:Shadow BlurRadius="30"
                    OffsetX="10"
                    OffsetY="10"
                    Opacity="1"
                    Spread="-5"
                    Color="#6858d3" />
        <!-- Top left lighter violet -->
        <utu:Shadow BlurRadius="30"
                    OffsetX="-10"
                    OffsetY="-10"
                    Opacity="1"
                    Spread="-5"
                    Color="#8c76ff" />
    </utu:ShadowCollection>

    <utu:ShadowCollection x:Key="NeumorphismHollow">
        <!-- Inner top and left shadow -->
        <utu:Shadow BlurRadius="10"
                    IsInner="True"
                    OffsetX="5"
                    OffsetY="5"
                    Opacity="1"
                    Spread="0"
                    Color="#6858d3" />
        <!-- Inner bottom and right shadow -->
        <utu:Shadow BlurRadius="10"
                    IsInner="True"
                    OffsetX="-4"
                    OffsetY="-4"
                    Opacity="1"
                    Spread="0"
                    Color="#8c76ff" />
    </utu:ShadowCollection>

    <utu:ShadowCollection x:Key="NeumorphismBulging">
        <utu:Shadow BlurRadius="10"
                    IsInner="True"
                    OffsetX="-5"
                    OffsetY="-5"
                    Opacity="1"
                    Spread="0"
                    Color="#6858d3" />
        <utu:Shadow BlurRadius="10"
                    IsInner="True"
                    OffsetX="4"
                    OffsetY="4"
                    Opacity="1"
                    Spread="0"
                    Color="#8c76ff" />
    </utu:ShadowCollection>
</Page.Resources>

<StackPanel Width="400"
            Margin="0,32"
            Padding="32"
            Background="{StaticResource UnoColor}"
            CornerRadius="30">
    <utu:ShadowContainer Background="{StaticResource UnoColor}"
                         Shadows="{StaticResource NeumorphismRaising}">
        <Grid Width="300"
              Padding="20"
              CornerRadius="20">
            <Grid.RowDefinitions>
                <RowDefinition Height="20" />
                <RowDefinition Height="20" />
            </Grid.RowDefinitions>

            <TextBlock FontSize="15"
                       Foreground="White"
                       Text="Neumorphism" />
            <TextBlock Grid.Row="1"
                       FontSize="12"
                       Foreground="White"
                       Text="Raising element" />
        </Grid>
    </utu:ShadowContainer>

    <utu:ShadowContainer Margin="0,60,0,0"
                         Background="{StaticResource UnoColor}"
                         Shadows="{StaticResource NeumorphismHollow}">
        <TextBox Width="200"
                 Height="40"
                 Padding="15,10,15,0"
                 VerticalAlignment="Center"
                 BorderThickness="0"
                 CornerRadius="20"
                 Foreground="White"
                 PlaceholderForeground="LightGray"
                 PlaceholderText="Hollow element" />
    </utu:ShadowContainer>
    <utu:ShadowContainer Margin="0,15" Shadows="{StaticResource NeumorphismHollow}">
        <TextBox Width="200"
                 Height="40"
                 Padding="15,10,15,0"
                 VerticalContentAlignment="Center"
                 Background="{StaticResource UnoColor}"
                 BorderThickness="0"
                 CornerRadius="20"
                 Foreground="White"
                 PlaceholderForeground="LightGray"
                 PlaceholderText="Hollow element" />
    </utu:ShadowContainer>

    <utu:ShadowContainer Margin="0,30" Shadows="{StaticResource NeumorphismBulging}">
        <Button Width="200"
                Height="40"
                Background="{StaticResource UnoColor}"
                BorderBrush="{StaticResource UnoColor}"
                Content="Bulging element"
                CornerRadius="15"
                Foreground="White" />
    </utu:ShadowContainer>

    <StackPanel Margin="0,30,0,0"
                Padding="24"
                HorizontalAlignment="Center"
                Orientation="Horizontal"
                Spacing="16">

        <utu:ShadowContainer Shadows="{StaticResource NeumorphismRaising}">
            <Button Background="{StaticResource UnoColor}"
                    BorderThickness="0"
                    Content="Regular"
                    Foreground="White" />
        </utu:ShadowContainer>

        <utu:ShadowContainer Shadows="{StaticResource NeumorphismRaising}">
            <Button Width="80"
                    Height="80"
                    Background="{StaticResource UnoColor}"
                    BorderBrush="{StaticResource UnoColor}"
                    Content="Circular"
                    CornerRadius="40"
                    Foreground="White" />
        </utu:ShadowContainer>

        <utu:ShadowContainer Shadows="{StaticResource NeumorphismRaising}">
            <Button Height="60"
                    Background="{StaticResource UnoColor}"
                    BorderThickness="0"
                    Content="Bigger"
                    CornerRadius="20"
                    Foreground="White" />
        </utu:ShadowContainer>
    </StackPanel>
</StackPanel>
```

![neumorphism built with 2 shadows](../assets/shadows-neumorphism.png)

## Theme Switching support

To ensure that the Shadows feature seamlessly integrates with [Theme Switching](xref:Uno.Features.Themes), it's essential to include the shadow collection within the theme dictionary.

Here's a snippet demonstrating how to structure your theme dictionary for proper shadow support:

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<ResourceDictionary>
    <ResourceDictionary.ThemeDictionaries>
        <ResourceDictionary x:Key="Dark">
            <Color x:Key="LightShadowColor">Pink</Color>
            <Color x:Key="ShadeShadowColor">SkyBlue</Color>

            <utu:ShadowCollection x:Key="ButtonShadows">
                <utu:Shadow BlurRadius="10"
                            IsInner="True"
                            OffsetX="-5"
                            OffsetY="-5"
                            Opacity="1"
                            Spread="0"
                            Color="{StaticResource LightShadowColor}" />
                <utu:Shadow BlurRadius="10"
                            IsInner="True"
                            OffsetX="4"
                            OffsetY="4"
                            Opacity="1"
                            Spread="0"
                            Color="{StaticResource ShadeShadowColor}" />
            </utu:ShadowCollection>
        </ResourceDictionary>
        <ResourceDictionary x:Key="Light">
            <Color x:Key="LightShadowColor">Orange</Color>
            <Color x:Key="ShadeShadowColor">Green</Color>

            <utu:ShadowCollection x:Key="ButtonShadows">
                <utu:Shadow BlurRadius="10"
                            IsInner="True"
                            OffsetX="-5"
                            OffsetY="-5"
                            Opacity="1"
                            Spread="0"
                            Color="{StaticResource LightShadowColor}" />
                <utu:Shadow BlurRadius="10"
                            IsInner="True"
                            OffsetX="4"
                            OffsetY="4"
                            Opacity="1"
                            Spread="0"
                            Color="{StaticResource ShadeShadowColor}" />
            </utu:ShadowCollection>
        </ResourceDictionary>
    </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>
...

<utu:ShadowContainer Background="{StaticResource UnoColor}"
                     Shadows="{ThemeResource ButtonShadows}">
    <Button Width="200"
            Height="40"
            BorderBrush="{StaticResource UnoColor}"
            Content="Save"
            CornerRadius="15"
            Foreground="White" />
</utu:ShadowContainer>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/SpeechRecognition.md

---
uid: Uno.Features.SpeechRecognition
---

# Speech Recognition in Uno

> [!TIP]
> This article covers Uno-specific information for `Windows.Media.SpeechRecognition`. For a full description of the feature and instructions on using it, see [SpeechRecognition Namespace](https://learn.microsoft.com/uwp/api/windows.media.speechrecognition).

* The `Windows.Media.SpeechRecognition` class allows an application to recognize voice input.

Uno's implementation currently supports basic native speech recognition.

## Supported Features

The following features of `Windows.Media.SpeechRecognition.SpeechRecognizer` are currently supported:

| Feature                                    | iOS | Android | Remarks                       |
|--------------------------------------------|-----|---------|-------------------------------|
| SpeechRecognizer()                         | X   | X       |                               |
| SpeechRecognizer(Language)                 | X   | X       |                               |
| Constraints                                | -   | -       |                               |
| ContinuousRecognitionSession               | -   | -       |                               |
| CurrentLanguage                            | X   | X       |                               |
| State                                      | X   | X       |                               |
| SupportedGrammarLanguages                  | -   | -       |                               |
| SupportedTopicLanguages                    | -   | -       |                               |
| SystemSpeechLanguage                       | -   | -       |                               |
| Timeouts                                   | X   | X       |                               |
| UIOptions                                  | X   | X       | Not used                      |
| CompileConstraintsAsync()                  | X   | X       | Always return Success (implemented to meet WinUI constraint that requires `CompileConstraintsAsync()` to be called before `RecognizeAsync()`) |
| Dispose()                                  | X   | X       |                               |
| RecognizeAsync()                           | X   | X       |                               |
| RecognizeWithUIAsync()                     | -   | -       |                               |
| StopRecognitionAsync()()                   | X   | X       |                               |
| TrySetSystemSpeechLanguageAsync(Language)  | -   | -       |                               |
| HypothesisGenerated                        | X   | X       |                               |
| RecognitionQualityDegrading                | -   | -       |                               |
| StateChanged                               | X   | X       |                               |

## Requirement

### iOS

* iOS 10 or later is required.
* The following lines need to be added to your info.plist:

  ```xml
  <key>NSSpeechRecognitionUsageDescription</key>  
  <string>[SpeechRecognition usage description]</string>  
  <key>NSMicrophoneUsageDescription</key>  
  <string>[SpeechRecognition usage description]</string> 
  ```

### Android

The following lines need to be added to your AndroidManifest.xml:

```xml
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.RECORD_AUDIO" />
```

## Limitation

In `Windows.Media.SpeechRecognition.SpeechRecognitionResult`, only `Text`, `Alternates`, and `GetAlternates(uint maxAlternates)` are implemented.
In particular, `RawConfidence` and `Confidence` fields are not currently supported.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.toolkit.ui/refs/heads/main/doc/controls/TabBarAndTabBarItem.md

---
uid: Toolkit.Controls.TabBar
---
# TabBar & TabBarItem

> [!TIP]
> This guide covers details for `TabBar` and `TabBarItem` specifically. If you are just getting started with the Uno Toolkit Library, please see our [general getting started](../getting-started.md) page to make sure you have the correct setup in place.
>
> [!Video https://www.youtube-nocookie.com/embed?listType=playlist&list=PLl_OlDcUya9qONoKVz4uGGsEeDbGuaIo_]
For more information and detailed walkthroughs on using TabBar and TabBarItem, please refer to the rest of the [video playlist](https://www.youtube.com/playlist?list=PLl_OlDcUya9qONoKVz4uGGsEeDbGuaIo_).

## Summary

Represents a control that provides a list of `TabItem`s to select from. The `TabBar` selection can be used to trigger frame navigation or to toggle the visibility of views.

## TabBarItem

`TabBarItem` is a specialized `SelectorItem` that includes functionality such as triggering an `ICommand` on click/tap or displaying a flyout.

### C\#

```csharp
public partial class TabBarItem : SelectorItem
```

### XAML

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBarItem Content="..." />
-or-
<utu:TabBarItem ...>
    content
</utu:TabBarItem>
```

### Inheritance

`Object` &#8594; `DependencyObject` &#8594; `UIElement` &#8594; `FrameworkElement` &#8594; `Control` &#8594; `ContentControl` &#8594; `SelectorItem` &#8594; `TabBarItem`

### Constructors

| Constructor    | Description                                           |
|----------------|-------------------------------------------------------|
| `TabBarItem()` | Initializes a new instance of the `TabBarItem` class. |

### Properties

| Property           | Type          | Description                                                                                                                                                                                                                                                                                    |
|--------------------|---------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `BadgeValue`       | `string`      | Gets or sets the value to be displayed in the badge of the `TabBarItem`. If a value is set the large badge will be displayed otherwise it will be the small badge. (Currently only supported by the Material Theme Toolkit Library with `BottomTabBarItemStyle` and `VerticalTabBarItemStyle`) |
| `BadgeVisibility`  | `Visibility`  | Gets or sets the badge visibility of the `TabBarItem`. (Currently only supported by the Material Theme Toolkit Library with `BottomTabBarItemStyle` and `VerticalTabBarItemStyle`)                                                                                                             |
| `Command`          | `ICommand`    | Gets or sets the command to invoke when the `TabBarItem` is pressed.                                                                                                                                                                                                                           |
| `CommandParameter` | `object`      | Gets or sets the parameter to pass to the `Command` property.                                                                                                                                                                                                                                  |
| `Flyout`           | `double`      | Gets or sets the flyout associated with this `TabBarItem`.                                                                                                                                                                                                                                     |
| `Icon`             | `IconElement` | Gets or sets the icon of the `TabBarItem`.                                                                                                                                                                                                                                                     |
| `IsSelectable`     | `bool`        | Gets or sets whether the `TabBarItem` can be selected.                                                                                                                                                                                                                                         |

### Events

| Event   | Type                 | Description                              |
|---------|----------------------|------------------------------------------|
| `Click` | `RoutedEventHandler` | Occurs when the `TabBarItem` is pressed. |

## TabBar

`TabBar` is a specialized `ItemsControl` used to present a collection of `TabBarItem`s.

### C\#

```csharp
public partial class TabBar : ItemsControl
```

### XAML

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBar .../>
-or-
<utu:TabBar ...>
    oneOrMoreItems
</utu:TabBar>
-or-
<utu:TabBar ...>
    <utu:TabBar.Items>
          oneOrMoreItems
      </utu:TabBar.Items>
</utu:TabBar>
```

### Inheritance

`Object` &#8594; `DependencyObject` &#8594; `UIElement` &#8594; `FrameworkElement` &#8594; `Control` &#8594; `ItemsControl` &#8594; `TabBar`

### Constructors

| Constructor | Description                                       |
|-------------|---------------------------------------------------|
| `TabBar()`  | Initializes a new instance of the `TabBar` class. |

### Properties

| Property                            | Type                      | Description                                                                                                                                                 |
|-------------------------------------|---------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `SelectedIndex`                     | `int`                     | Gets or sets the index of the selected item.                                                                                                                |
| `SelectedItem`                      | `object`                  | Gets or sets the selected item.                                                                                                                             |
| `Orientation`                       | `Orientation`             | Gets or sets the dimension by which the items are stacked                                                                                                   |
| `SelectionIndicatorContent`         | `object`                  | Gets or sets the content to be displayed as the selection indicator                                                                                         |
| `SelectionIndicatorContentTemplate` | `DataTemplate`            | Gets or sets the data template that is used to display the content of the selection indicator                                                               |
| `SelectionIndicatorPresenterStyle`  | `Style`                   | Gets or sets the style to be applied for the content of the `TabBarSelectionIndicatorPresenter`                                                             |
| `SelectionIndicatorTransitionMode`  | `IndicatorTransitionMode` | Gets or sets the behavior of the selection indicator. The indicator can either slide or snap to the newly selected item. Defaults to `Snap`                 |
| `SelectionIndicatorPlacement`       | `IndicatorPlacement`      | Gets or sets the placement of the selection indicator. The indicator can either be displayed `Above` or `Below` the TabBarItem Content. Defaults to `Above` |

> [!NOTE]
> `TabBar` only supports the single selection mode.

### Events

All events below are forwarded from the nested `TabBarItem`s:

| Event              | Type                                                         | Description                                               |
|--------------------|--------------------------------------------------------------|-----------------------------------------------------------|
| `SelectionChanged` | `TypedEventHandler<TabBar, TabBarSelectionChangedEventArgs>` | Occurs when a `TabBarItem`'s selection state has changed. |

```csharp
class TabBarSelectionChangedEventArgs : EventArgs
{
    // Gets the newly selected TabBarItem
    object? NewItem { get; }

    // Gets the previously selected TabBarItem
    object? OldItem { get; }
}
```

## Selection Indicator

By default, the `TabBar` does not display an indicator for the currently selected item. If a selection indicator is needed, it can be defined by setting the `SelectionIndicatorContent` and/or `SelectionIndicatorContentTemplate` properties on `TabBar`. If the content for the indicator is defined, the `TabBar` will automatically display and position the indicator based on the `SelectionIndicatorTransitionMode`.

As an example, given the following `TabBar`:

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBar Style="{StaticResource MyCustomTabBarStyle}"
            SelectedIndex="0">
    <utu:TabBar.SelectionIndicatorContent>
        <Border Height="2"
                VerticalAlignment="Bottom"
                Background="Red" />
    </utu:TabBar.SelectionIndicatorContent>
    <utu:TabBar.Items>
        <utu:TabBarItem Content="HOME">
            <utu:TabBarItem.Icon>
                <SymbolIcon Symbol="Home" />
            </utu:TabBarItem.Icon>
        </utu:TabBarItem>
        <utu:TabBarItem Content="SUPPORT">
            <utu:TabBarItem.Icon>
                <FontIcon Glyph="&#xE8F2;" />
            </utu:TabBarItem.Icon>
        </utu:TabBarItem>
        <utu:TabBarItem Content="ABOUT">
            <utu:TabBarItem.Icon>
                <FontIcon Glyph="&#xE946;" />
            </utu:TabBarItem.Icon>
        </utu:TabBarItem>
    </utu:TabBar.Items>
</utu:TabBar>
```

The result would be:

![TabBar selection](../assets/tabbar-selection-red.png)

### IndicatorTransitionMode

The selection indicator has two different transition modes:

- `IndicatorTransitionMode.Snap` (default mode):

  ![TabBar with snap selection](../assets/tabbar-selection-snap.gif)

- `IndicatorTransitionMode.Slide`:

  ![TabBar with slide selection](../assets/tabbar-selection-slide.gif)

### IndicatorPlacement

By default, the selection indicator is rendered above, on "on top" of, the actual content in the TabBar. For example, the following XAML will result in the screenshot below:

```xml
<utu:TabBar Margin="50"
            Width="300"
            SelectedIndex="1"
            Background="Green"
            VerticalAlignment="Center">
    <utu:TabBar.Items>
        <utu:TabBarItem Content="Tab 1" />
        <utu:TabBarItem Content="Tab 2" />
        <utu:TabBarItem Content="Tab 3" />
    </utu:TabBar.Items>
    <utu:TabBar.SelectionIndicatorContentTemplate>
        <DataTemplate>
            <Border Background="Red" />
        </DataTemplate>
    </utu:TabBar.SelectionIndicatorContentTemplate>
</utu:TabBar>
```

![TabBar with indication placement above](../assets/tabbar-indicator-placement-above.png)

The `SelectionIndicatorPlacement` property can be used to render the selection indicator "below" the content so it does not obscure the `TabBarItem`:

```xml
<utu:TabBar Margin="50"
            Width="300"
            SelectedIndex="1"
            Background="Green"
            SelectionIndicatorPlacement="Below"
            VerticalAlignment="Center">
    <utu:TabBar.Items>
        <utu:TabBarItem Content="Tab 1" />
        <utu:TabBarItem Content="Tab 2" />
        <utu:TabBarItem Content="Tab 3" />
    </utu:TabBar.Items>
    <utu:TabBar.SelectionIndicatorContentTemplate>
        <DataTemplate>
            <Border Background="Red" />
        </DataTemplate>
    </utu:TabBar.SelectionIndicatorContentTemplate>
</utu:TabBar>
```

![TabBar with indication placement below](../assets/tabbar-indicator-placement-below.png)

### Further Customization

If further customization is required, such as custom animations when sliding the indicator, there is a `SelectionIndicatorPresenterStyle` property on `TabBar` that can be set to customize the style of the internal `ContentPresenter` that is used to display the selection indicator.

## Styling `TabBar` & `TabBarItem`

Toolkit provides a barebones default style for `TabBar` and `TabBarItem`. It is recommended to use either:

- [One of the pre-built styles](../controls-styles.md#control-styles) that come packaged within the `Uno.Toolkit.UI.Material` or `Uno.Toolkit.UI.Cupertino` libraries
- A custom-built style that is defined within the consuming application

The styles that exist within the Toolkit Theming Libraries are built for the most common scenarios in which a `TabBar` could be used.

### "Top" `TabBar` Style

A common use for a `TabBar` would be to use it as a means of navigation between two or more views/pages that are all at the same level of hierarchy (Lateral Navigation). If the goal is to provide lateral navigation for destinations that are at **any** level of the hierarchy, a `TabBar` styled as a `TopTabBar` is most appropriate.

Currently, the Material Theme Toolkit Library contains two styles for this purpose: `ColoredTopTabBarStyle` and `TopTabBarStyle`.

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBar SelectedIndex="1"
            Style="{StaticResource ColoredTopTabBarStyle}">
    <utu:TabBar.Items>
        <utu:TabBarItem Content="Home" />
        <utu:TabBarItem Content="Search" />
        <utu:TabBarItem Content="Support" />
        <utu:TabBarItem Content="About" />
    </utu:TabBar.Items>
</utu:TabBar>
```

![TabBar on Android using the ColoredTopTabBarStyle](../assets/tabbar-android-top.png)

### "Bottom" `TabBar` Style

Following the explanation of Lateral Navigation and the use case for "Top" `TabBar` styles, another common scenario is to use `TabBar` as an application's primary navigation component. In this case, we want a component that would provide lateral navigation to all **top-level** destinations. In this case, a `TabBar` styled as a `BottomTabBar` is most appropriate.

Currently, both the Material and Cupertino Theme Toolkit Libraries contain a `BottomTabBarStyle`.

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBar SelectedIndex="1"
            Style="{StaticResource BottomTabBarStyle}">
    <utu:TabBarItem>
        <utu:TabBarItem.Icon>
            <SymbolIcon Symbol="Home" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
    <utu:TabBarItem>
        <utu:TabBarItem.Icon>
            <SymbolIcon Symbol="Find" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
    <utu:TabBarItem>
        <utu:TabBarItem.Icon>
            <SymbolIcon Symbol="Help" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
    <utu:TabBarItem>
        <utu:TabBarItem.Icon>
            <SymbolIcon Symbol="Flag" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
</utu:TabBar>
```

#### Material

![TabBar on Android using the Material Bottom Style](../assets/tabbar-android-material-bottom.png)

#### Cupertino

![TabBar on iOS using the Cupertino Bottom Style](../assets/tabbar-ios-cupertino-bottom.png)

### "Vertical" `TabBar` Style

Along with using the "Bottom" `TabBar`, Toolkit also provides a "Vertical" `TabBar` to use as an application's primary navigation component.  In this case, we want a component that would provide lateral navigation to all **top-level** destinations.

Currently, only the Material Theme Toolkit Library contains a `VerticalTabBarStyle`.

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBar SelectedIndex="1"
            Style="{StaticResource VerticalTabBarStyle}">
    <utu:TabBarItem>
        <utu:TabBarItem.Icon>
            <SymbolIcon Symbol="Home" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
    <utu:TabBarItem>
        <utu:TabBarItem.Icon>
            <SymbolIcon Symbol="Find" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
    <utu:TabBarItem>
        <utu:TabBarItem.Icon>
            <SymbolIcon Symbol="Help" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
    <utu:TabBarItem>
        <utu:TabBarItem.Icon>
            <SymbolIcon Symbol="Flag" />
        </utu:TabBarItem.Icon>
    </utu:TabBarItem>
</utu:TabBar>
```

#### Material

![TabBar on Android using the Material Vertical Style](../assets/tabbar-android-material-vertical.png)

There are some styles that are built specifically for the Cupertino theme. These styles are used to emulate a [`UISegmentedControl`](https://developer.apple.com/documentation/uikit/uisegmentedcontrol)

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBar Style="{StaticResource SegmentedStyle}">
    <utu:TabBar.Items>
        <utu:TabBarItem Content="ORANGE" />
        <utu:TabBarItem Content="PURPLE" />
        <utu:TabBarItem Content="BLUE" />
    </utu:TabBar.Items>
</utu:TabBar>

<utu:TabBar Style="{StaticResource SlidingSegmentedStyle}">
    <utu:TabBar.Items>
        <utu:TabBarItem Content="ORANGE" />
        <utu:TabBarItem Content="PURPLE" />
        <utu:TabBarItem Content="BLUE" />
    </utu:TabBar.Items>
</utu:TabBar>
```

![TabBar on Android using the SegmentedStyle](../assets/tabbar-android-segmented.png)
![TabBar on Android using the SlidingSegmentedStyle](../assets/tabbar-android-sliding-segmented.png)

### `TabBarItem` Style

The Uno Toolkit provides several styles of `TabBarItem` for both Material and Cupertino themes.

| Style Key                   | Material | Cupertino |
|-----------------------------|----------|-----------|
| `BottomFabTabBarItemStyle`  | &check;  |           |
| `BottomTabBarItemStyle`     | &check;  | &check;   |
| `ColoredTopTabBarItemStyle` | &check;  |           |
| `SegmentedItemStyle`        |          | &check;   |
| `SlidingSegmentedItemStyle` | &check;  |           |
| `TopTabBarItemStyle`        | &check;  |           |
| `VerticalTabBarItemStyle`   | &check;  |           |

These pre-built styles can be used for more complex `TabBar` scenarios. For example, using the BottomFabTabBarItemStyle, we can embed Floating Action Buttons into the `TabBar`.

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBar SelectedIndex="1"
            Style="{StaticResource BottomTabBarStyle}">
    <utu:TabBar.Items>
        <utu:TabBarItem Content="Home">
            <utu:TabBarItem.Icon>
                <FontIcon Glyph="&#xE80F;" />
            </utu:TabBarItem.Icon>
        </utu:TabBarItem>
        <utu:TabBarItem Content="Search">
            <utu:TabBarItem.Icon>
                <FontIcon Glyph="&#xe721;" />
            </utu:TabBarItem.Icon>
        </utu:TabBarItem>
        <utu:TabBarItem Style="{StaticResource BottomFabTabBarItemStyle}">
            <utu:TabBarItem.Flyout>
                <MenuFlyout MenuFlyoutPresenterStyle="{StaticResource MenuFlyoutPresenterStyle}"
                            Placement="Top">

                    <MenuFlyoutItem Style="{StaticResource MenuFlyoutItemStyle}"
                                    Text="Like">
                        <MenuFlyoutItem.Icon>
                            <SymbolIcon Symbol="Like" />
                        </MenuFlyoutItem.Icon>
                    </MenuFlyoutItem>

                    <MenuFlyoutItem Style="{StaticResource MenuFlyoutItemStyle}"
                                    Text="Dislike">
                        <MenuFlyoutItem.Icon>
                            <SymbolIcon Symbol="Dislike" />
                        </MenuFlyoutItem.Icon>
                    </MenuFlyoutItem>
                </MenuFlyout>
            </utu:TabBarItem.Flyout>
            <utu:TabBarItem.Icon>
                <SymbolIcon Symbol="Add" />
            </utu:TabBarItem.Icon>
        </utu:TabBarItem>
        <utu:TabBarItem Content="Support">
            <utu:TabBarItem.Icon>
                <FontIcon Glyph="&#xE8F2;" />
            </utu:TabBarItem.Icon>
        </utu:TabBarItem>
        <utu:TabBarItem Content="About">
            <utu:TabBarItem.Icon>
                <FontIcon Glyph="&#xE946;" />
            </utu:TabBarItem.Icon>
        </utu:TabBarItem>
    </utu:TabBar.Items>
</utu:TabBar>
```

![TabBar on Android using the BottomFabTabBarItemStyle](../assets/tabbar-android-material-bottom-fab.png)
![TabBar on Android using the BottomFabTabBarItemStyle with flyout opened](../assets/tabbar-android-material-bottom-fab-flyout.png)

#### Badge usage for the Material `TabBar` styles

Icons in `TabBar` items can display badges in their upper right corners.

Badges can contain dynamic information, such as the number of new messages.

Currently, only the Material Theme Toolkit Library contains a `BottomTabBarItemStyle` or `VerticalTabBarItemStyle` that you can use to display a badge (which is optional).

![TabBar with Badge usage](../assets/tabbaritem-winui-material-badges.png)

##### Small Badge

A small badge uses only shape to indicate a status change or new notification.

![TabBar with small Badge](../assets/tabbaritem-winui-material-smallbadge.png)

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBarItem Content="Favorites"
                BadgeVisibility="Visible"
                Style="{StaticResource BottomTabBarItemStyle}">
    <utu:TabBarItem.Icon>
        <FontIcon Glyph="&#xE113;" />
    </utu:TabBarItem.Icon>
</utu:TabBarItem>
```

##### Large Badge

A large badge displays a number within a container to indicate a quantifiable status change related to a destination.

![TabBar with large Badge](../assets/tabbaritem-winui-material-largebadge.png)

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<utu:TabBarItem Content="Mail"
                BadgeValue="8"
                BadgeVisibility="Visible"
                Style="{StaticResource BottomTabBarItemStyle}">
    <utu:TabBarItem.Icon>
        <FontIcon Glyph="&#xE119;" />
    </utu:TabBarItem.Icon>
</utu:TabBarItem>
```

## Lightweight Styling

| Key                                                                  | Type            | Value                                        |
|----------------------------------------------------------------------|-----------------|----------------------------------------------|
| `NavigationTabBarWidthOrHeight`                                    | `Double`          | 80                                           |
| `NavigationTabBarTintOpacity`                                      | `Double`          | 0.8                                          |
| `NavigationTabBarItemIconHeight`                                   | `Double`          | 18                                           |
| `NavigationTabBarItemActiveIndicatorWidth`                         | `Double`          | 64                                           |
| `NavigationTabBarItemActiveIndicatorHeight`                        | `Double`          | 32                                           |
| `NavigationTabBarItemPadding`                                      | `Thickness`       | 0,12,0,16                                    |
| `NavigationTabBarItemActiveIndicatorCornerRadius`                  | `CornerRadius`    | 16                                           |
| `TopTabBarHeight`                                                  | `Double`          | 48                                           |
| `TopTabBarItemIconHeight`                                          | `Double`          | 20                                           |
| `TopTabBarItemContentMargin`                                       | `Thickness`       | 0                                            |
| `FabTabBarItemOffset`                                              | `Double`          | -32                                          |
| `FabTabBarItemContentWidthOrHeight`                                | `Double`          | 16                                           |
| `FabTabBarItemIconTextPadding`                                     | `Double`          | 12                                           |
| `FabTabBarItemCornerRadius`                                        | `CornerRadius`    | 16                                           |
| `FabTabBarItemPadding`                                             | `Thickness`       | 20                                           |
| `NavigationTabBarItemSmallBadgeHeight`                             | `Double`          | 6                                            |
| `NavigationTabBarItemSmallBadgeWidth`                              | `Double`          | 6                                            |
| `NavigationTabBarItemSmallBadgeMargin`                             | `Thickness`       | 0,4,20,0                                     |
| `NavigationTabBarItemLargeBadgeHeight`                             | `Double`          | 16                                           |
| `NavigationTabBarItemLargeBadgeMinWidth`                           | `Double`          | 16                                           |
| `NavigationTabBarItemLargeBadgeMargin`                             | `Thickness`       | 32,2,0,0                                     |
| `NavigationTabBarItemLargeBadgePadding`                            | `Thickness`       | 4,0                                          |
| `NavigationTabBarItemLargeBadgeCornerRadius`                       | `CornerRadius`    | 8                                            |
| `VerticalTabBarBackground`                                         | `SolidColorBrush` | SurfaceBrush                                 |
| `BottomTabBarBackground`                                           | `SolidColorBrush` | SurfaceBrush                                 |
| `TopTabBarBackground`                                              | `SolidColorBrush` | BackgroundBrush                              |
| `TopTabBarBottomBorderBrush`                                       | `SolidColorBrush` | PrimaryBrush                                 |
| `ColoredTopTabBarBackground`                                       | `SolidColorBrush` | PrimaryBrush                                 |
| `ColoredTopTabBarBottomBorderBrush`                                | `SolidColorBrush` | OnPrimaryBrush                               |
| `ColoredTopTabBarItemBackground`                                   | `SolidColorBrush` | SystemControlTransparentBrush                |
| `ColoredTopTabBarItemBackgroundPointerOver`                        | `SolidColorBrush` | OnPrimaryHoverBrush                          |
| `ColoredTopTabBarItemBackgroundFocused`                            | `SolidColorBrush` | OnPrimaryLowBrush                            |
| `ColoredTopTabBarItemBackgroundPressed`                            | `SolidColorBrush` | OnPrimaryPressedBrush                        |
| `ColoredTopTabBarItemBackgroundDisabled`                           | `SolidColorBrush` | SystemControlTransparentBrush                |
| `ColoredTopTabBarItemBackgroundSelected`                           | `SolidColorBrush` | SystemControlTransparentBrush                |
| `ColoredTopTabBarItemBackgroundSelectedPointerOver`                | `SolidColorBrush` | OnPrimaryHoverBrush                          |
| `ColoredTopTabBarItemBackgroundSelectedPressed`                    | `SolidColorBrush` | OnPrimaryPressedBrush                        |
| `ColoredTopTabBarItemForeground`                                   | `SolidColorBrush` | OnPrimaryMediumBrush                         |
| `ColoredTopTabBarItemForegroundPointerOver`                        | `SolidColorBrush` | OnPrimaryMediumBrush                         |
| `ColoredTopTabBarItemForegroundFocused`                            | `SolidColorBrush` | OnPrimaryMediumBrush                         |
| `ColoredTopTabBarItemForegroundPressed`                            | `SolidColorBrush` | OnPrimaryMediumBrush                         |
| `ColoredTopTabBarItemForegroundDisabled`                           | `SolidColorBrush` | SystemControlDisabledBaseMediumLowBrush      |
| `ColoredTopTabBarItemForegroundSelected`                           | `SolidColorBrush` | OnPrimaryBrush                               |
| `ColoredTopTabBarItemForegroundSelectedPointerOver`                | `SolidColorBrush` | OnPrimaryBrush                               |
| `ColoredTopTabBarItemForegroundSelectedPressed`                    | `SolidColorBrush` | OnPrimaryBrush                               |
| `ColoredTopTabBarItemIconForeground`                               | `SolidColorBrush` | SystemControlTransparentBrush                |
| `ColoredTopTabBarItemIconForegroundPointerOver`                    | `SolidColorBrush` | OnPrimaryMediumBrush                         |
| `ColoredTopTabBarItemIconForegroundFocused`                        | `SolidColorBrush` | SystemControlTransparentBrush                |
| `ColoredTopTabBarItemIconForegroundPressed`                        | `SolidColorBrush` | OnPrimaryMediumBrush                         |
| `ColoredTopTabBarItemIconForegroundDisabled`                       | `SolidColorBrush` | SystemControlDisabledBaseMediumLowBrush      |
| `ColoredTopTabBarItemIconForegroundSelected`                       | `SolidColorBrush` | OnPrimaryBrush                               |
| `ColoredTopTabBarItemIconForegroundSelectedPointerOver`            | `SolidColorBrush` | OnPrimaryBrush                               |
| `ColoredTopTabBarItemIconForegroundSelectedPressed`                | `SolidColorBrush` | OnPrimaryBrush                               |
| `ColoredTopTabBarItemPointerFillBrush`                             | `SolidColorBrush` | SystemControlTransparentBrush                |
| `ColoredTopTabBarItemPointerFillBrushPointerOver`                  | `SolidColorBrush` | OnPrimaryHoverBrush                          |
| `ColoredTopTabBarItemPointerFillBrushFocused`                      | `SolidColorBrush` | OnPrimaryLowBrush                            |
| `ColoredTopTabBarItemPointerFillBrushPressed`                      | `SolidColorBrush` | OnPrimaryPressedBrush                        |
| `ColoredTopTabBarItemPointerFillBrushDisabled`                     | `SolidColorBrush` | SystemControlTransparentBrush                |
| `ColoredTopTabBarItemPointerFillBrushSelected`                     | `SolidColorBrush` | SystemControlTransparentBrush                |
| `ColoredTopTabBarItemPointerFillBrushSelectedPointerOver`          | `SolidColorBrush` | OnPrimaryHoverBrush                          |
| `ColoredTopTabBarItemPointerFillBrushSelectedPressed`              | `SolidColorBrush` | OnPrimaryPressedBrush                        |
| `ColoredTopTabBarItemRippleFeedback`                               | `SolidColorBrush` | PrimaryBrush                                 |
| `FabTabBarItemBackground`                                          | `SolidColorBrush` | PrimaryContainerBrush                        |
| `FabTabBarItemBackgroundPointerOver`                               | `SolidColorBrush` | OnPrimaryContainerHoverBrush                 |
| `FabTabBarItemBackgroundFocused`                                   | `SolidColorBrush` | OnPrimaryContainerFocusedBrush               |
| `FabTabBarItemBackgroundPressed`                                   | `SolidColorBrush` | OnPrimaryContainerPressedBrush               |
| `FabTabBarItemBackgroundDisabled`                                  | `SolidColorBrush` | OnSurfaceDisabledBrush                    |
| `FabTabBarItemBackgroundSelected`                                  | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemBackgroundSelectedPointerOver`                       | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemBackgroundSelectedPressed`                           | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemForeground`                                          | `SolidColorBrush` | OnPrimaryContainerBrush                      |
| `FabTabBarItemForegroundPointerOver`                               | `SolidColorBrush` | OnPrimaryContainerBrush                      |
| `FabTabBarItemForegroundFocused`                                   | `SolidColorBrush` | OnPrimaryContainerBrush                      |
| `FabTabBarItemForegroundPressed`                                   | `SolidColorBrush` | OnPrimaryContainerBrush                      |
| `FabTabBarItemForegroundDisabled`                                  | `SolidColorBrush` | OnSurfaceDisabledBrush                       |
| `FabTabBarItemForegroundSelected`                                  | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemForegroundSelectedPointerOver`                       | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemForegroundSelectedPressed`                           | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemIconForeground`                                      | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemIconForegroundPointerOver`                           | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemIconForegroundFocused`                               | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemIconForegroundPressed`                               | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemIconForegroundDisabled`                              | `SolidColorBrush` | OnSurfaceDisabledBrush                       |
| `FabTabBarItemIconForegroundSelected`                              | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemIconForegroundSelectedPointerOver`                   | `SolidColorBrush` | SystemControlTransparentBrush                |
| `FabTabBarItemIconForegroundSelectedPressed`                       | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarItemActiveIndicatorBackground`                    | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarItemActiveIndicatorBackgroundPointerOver`         | `SolidColorBrush` | OnSurfaceVariantHoverBrush                   |
| `NavigationTabBarItemActiveIndicatorBackgroundPressed`             | `SolidColorBrush` | OnSurfaceVariantPressedBrush                 |
| `NavigationTabBarItemActiveIndicatorBackgroundDisabled`            | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarItemActiveIndicatorBackgroundSelected`            | `SolidColorBrush` | SecondaryContainerBrush                      |
| `NavigationTabBarItemActiveIndicatorBackgroundSelectedPointerOver` | `SolidColorBrush` | OnSurfaceHoverBrush                          |
| `NavigationTabBarItemActiveIndicatorBackgroundSelectedPressed`     | `SolidColorBrush` | OnSurfacePressedBrush                        |
| `NavigationTabBarItemIconForeground`                               | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarItemIconForegroundPointerOver`                    | `SolidColorBrush` | OnSurfaceVariantBrush                        |
| `NavigationTabBarItemIconForegroundPressed`                        | `SolidColorBrush` | OnSurfaceVariantBrush                        |
| `NavigationTabBarItemIconForegroundDisabled`                       | `SolidColorBrush` | SystemControlDisabledBaseMediumLowBrush      |
| `NavigationTabBarItemIconForegroundSelected`                       | `SolidColorBrush` | OnSecondaryContainerBrush                    |
| `NavigationTabBarItemIconForegroundSelectedPointerOver`            | `SolidColorBrush` | OnSecondaryContainerBrush                    |
| `NavigationTabBarItemIconForegroundSelectedPressed`                | `SolidColorBrush` | OnSecondaryContainerBrush                    |
| `NavigationTabBarItemErrorBrush`                                   | `SolidColorBrush` | ErrorBrush                                   |
| `NavigationTabBarItemOnErrorBrush`                                 | `SolidColorBrush` | OnErrorBrush                                 |
| `NavigationTabBarItemPointerFillBrush`                             | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarItemRippleFeedback`                               | `SolidColorBrush` | OnSurfaceBrush                               |
| `TopTabBarItemBackground`                                          | `SolidColorBrush` | SystemControlTransparentBrush                |
| `TopTabBarItemBackgroundPointerOver`                               | `SolidColorBrush` | PrimaryHoverBrush                            |
| `TopTabBarItemBackgroundFocused`                                   | `SolidColorBrush` | PrimaryLowBrush                              |
| `TopTabBarItemBackgroundPressed`                                   | `SolidColorBrush` | PrimaryPressedBrush                          |
| `TopTabBarItemBackgroundDisabled`                                  | `SolidColorBrush` | SystemControlTransparentBrush                |
| `TopTabBarItemBackgroundSelected`                                  | `SolidColorBrush` | SystemControlTransparentBrush                |
| `TopTabBarItemBackgroundSelectedPointerOver`                       | `SolidColorBrush` | PrimaryHoverBrush                            |
| `TopTabBarItemBackgroundSelectedPressed`                           | `SolidColorBrush` | PrimaryPressedBrush                          |
| `TopTabBarItemForeground`                                          | `SolidColorBrush` | OnSurfaceMediumBrush                         |
| `TopTabBarItemForegroundPointerOver`                               | `SolidColorBrush` | OnSurfaceMediumBrush                         |
| `TopTabBarItemForegroundFocused`                                   | `SolidColorBrush` | OnSurfaceMediumBrush                         |
| `TopTabBarItemForegroundPressed`                                   | `SolidColorBrush` | OnSurfaceMediumBrush                         |
| `TopTabBarItemForegroundDisabled`                                  | `SolidColorBrush` | SystemControlDisabledBaseMediumLowBrush      |
| `TopTabBarItemForegroundSelected`                                  | `SolidColorBrush` | PrimaryBrush                                 |
| `TopTabBarItemForegroundSelectedPointerOver`                       | `SolidColorBrush` | PrimaryBrush                                 |
| `TopTabBarItemForegroundSelectedPressed`                           | `SolidColorBrush` | PrimaryBrush                                 |
| `TopTabBarItemBorderBrush`                                         | `SolidColorBrush` | SystemControlTransparentBrush                |
| `TopTabBarItemIconForeground`                                      | `SolidColorBrush` | SystemControlTransparentBrush                |
| `TopTabBarItemIconForegroundPointerOver`                           | `SolidColorBrush` | OnSurfaceMediumBrush                         |
| `TopTabBarItemIconForegroundFocused`                               | `SolidColorBrush` | SystemControlTransparentBrush                |
| `TopTabBarItemIconForegroundPressed`                               | `SolidColorBrush` | OnSurfaceMediumBrush                         |
| `TopTabBarItemIconForegroundDisabled`                              | `SolidColorBrush` | SystemControlDisabledBaseMediumLowBrush      |
| `TopTabBarItemIconForegroundSelected`                              | `SolidColorBrush` | PrimaryBrush                                 |
| `TopTabBarItemIconForegroundSelectedPointerOver`                   | `SolidColorBrush` | PrimaryBrush                                 |
| `TopTabBarItemIconForegroundSelectedPressed`                       | `SolidColorBrush` | PrimaryBrush                                 |
| `TopTabBarItemPointerFillBrush`                                    | `SolidColorBrush` | SystemControlTransparentBrush                |
| `TopTabBarItemPointerFillBrushPointerOver`                         | `SolidColorBrush` | PrimaryHoverBrush                            |
| `TopTabBarItemPointerFillBrushFocused`                             | `SolidColorBrush` | PrimaryLowBrush                              |
| `TopTabBarItemPointerFillBrushPressed`                             | `SolidColorBrush` | PrimaryPressedBrush                          |
| `TopTabBarItemPointerFillBrushDisabled`                            | `SolidColorBrush` | SystemControlTransparentBrush                |
| `TopTabBarItemPointerFillBrushSelected`                            | `SolidColorBrush` | SystemControlTransparentBrush                |
| `TopTabBarItemPointerFillBrushSelectedPointerOver`                 | `SolidColorBrush` | PrimaryHoverBrush                            |
| `TopTabBarItemPointerFillBrushSelectedPressed`                     | `SolidColorBrush` | PrimaryPressedBrush                          |
| `TopTabBarItemRippleFeedback`                                      | `SolidColorBrush` | PrimaryBrush                                 |
| `NavigationTabBarBackground`                                       | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarBackgroundPointerOver`                            | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarBackgroundFocused`                                | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarBackgroundPressed`                                | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarBackgroundSelected`                               | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarBackgroundSelectedPointerOver`                    | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarBackgroundSelectedPressed`                        | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarForeground`                                       | `SolidColorBrush` | OnSurfaceVariantBrush                        |
| `NavigationTabBarForegroundPointerOver`                            | `SolidColorBrush` | OnSurfaceVariantBrush                        |
| `NavigationTabBarForegroundPressed`                                | `SolidColorBrush` | OnSurfaceVariantBrush                        |
| `NavigationTabBarForegroundDisabled`                               | `SolidColorBrush` | SystemControlDisabledBaseMediumLowBrush      |
| `NavigationTabBarForegroundSelected`                               | `SolidColorBrush` | OnSurfaceBrush                               |
| `NavigationTabBarForegroundSelectedPointerOver`                    | `SolidColorBrush` | OnSurfaceBrush                               |
| `NavigationTabBarForegroundSelectedPressed`                        | `SolidColorBrush` | OnSurfaceBrush                               |
| `NavigationTabBarBorderBrush`                                      | `SolidColorBrush` | SystemControlTransparentBrush                |
| `NavigationTabBarTintBrush`                                        | `SolidColorBrush` | SurfaceTintColor@NavigationTabBarTintOpacity |

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/TextBox.md

---
uid: Uno.Controls.TextBox
---

# TextBox

## InputScopes Mapping Table

| Value                   | Description                                                                                                                               |                           Android                            |                 iOS                  |
|-------------------------|-------------------------------------------------------------------------------------------------------------------------------------------|:------------------------------------------------------------:|:------------------------------------:|
| AlphanumericFullWidth   | Input scope is intended for alphanumeric full-width characters.                                                                           |                                                              |                                      |
| AlphanumericHalfWidth   | Input scope is intended for alphanumeric half-width characters.                                                                           |                                                              |                                      |
| AlphanumericPin         | Expected input is an alphanumeric PIN.                                                                                                    |                                                              |                                      |
| Chat                    | Input scope is intended for chat strings.                                                                                                 |                                                              |                                      |
| ChatWithoutEmoji        | Expected input does not include emoji. Advises input processors to not show the emoji key.                                                |                                                              |                                      |
| ChineseFullWidth        | Input scope is intended for Chinese full-width characters.                                                                                |                                                              |                                      |
| ChineseHalfWidth        | Input scope is intended for Chinese half-width characters.                                                                                |                                                              |                                      |
| CurrencyAmount          | Input scope is intended for working with a currency amount (no currency symbol).                                                          |    InputTypes.ClassNumber OR InputTypes.NumberFlagDecimal    |      UIKeyboardType.DecimalPad       |
| CurrencyAmountAndSymbol | Input scope is intended for working with amount and symbol of currency.                                                                   |                                                              |                                      |
| DateDayNumber           | Input scope is intended for working with a numeric day of the month.                                                                      |                                                              |                                      |
| DateMonthNumber         | Input scope is intended for working with a numeric month of the year.                                                                     |                                                              |                                      |
| DateYear                | Input scope is intended for working with a numeric year.                                                                                  |                                                              |                                      |
| Default                 | No input scope is applied.                                                                                                                |                     InputTypes.ClassText                     |        UIKeyboardType.Default        |
| Digits                  | Input scope is intended for working with a collection of numbers.                                                                         |                                                              |                                      |
| EmailNameOrAddress      | Input scope is intended for working with an email name or full email address.                                                             | InputTypes.ClassText OR InputTypes.TextVariationEmailAddress |     UIKeyboardType.EmailAddress      |
| EmailSmtpAddress        | Input scope is intended for working with a Simple Mail Transport Protocol (SMTP) form e-mail address (accountname@host).                  | InputTypes.ClassText OR InputTypes.TextVariationEmailAddress |     UIKeyboardType.EmailAddress      |
| Formula                 | Input scope is intended for spreadsheet formula strings.                                                                                  |                                                              |                                      |
| FormulaNumber           | Expected input is a mathematical formula. Advises input processors to show the number page.                                               |                                                              |                                      |
| HangulFullWidth         | Input scope is intended for Hangul full-width characters.                                                                                 |                                                              |                                      |
| HangulHalfWidth         | Input scope is intended for Hangul half-width characters.                                                                                 |                                                              |                                      |
| Hanja                   | Input scope is intended for Hanja characters.                                                                                             |                                                              |                                      |
| Hiragana                | Input scope is intended for Hiragana characters.                                                                                          |                                                              |                                      |
| KatakanaFullWidth       | Input scope is intended for Katakana full-width characters.                                                                               |                                                              |                                      |
| KatakanaHalfWidth       | Input scope is intended for Katakana half-width characters.                                                                               |                                                              |                                      |
| Maps                    | Input scope is intended for working with a map location.                                                                                  |                                                              |                                      |
| NameOrPhoneNumber       | Input scope is intended for working with a name or telephone number.                                                                      |                                                              |                                      |
| NativeScript            | Input scope is intended for native script.                                                                                                |                                                              |                                      |
| Number                  | Input scope is intended for working with digits 0-9.                                                                                      |                    InputTypes.ClassNumber                    |       UIKeyboardType.NumberPad       |
| NumberFullWidth         | Input scope is intended for full-width number characters.                                                                                 |                   InputTypes.ClassPhone(*)                   | UIKeyboardType.NumbersAndPunctuation |
| NumericPassword         | Expected input is a numeric password, or PIN.                                                                                             |                                                              |                                      |
| NumericPin              | Expected input is a numeric PIN.                                                                                                          |                    InputTypes.ClassNumber                    | UIKeyboardType.NumbersAndPunctuation |
| Password                | Input scope is intended for working with an alphanumeric password, including other symbols, such as punctuation and mathematical symbols. |                                                              |                                      |
| PersonalFullName        | Input scope is intended for working with a complete personal name.                                                                        |                                                              |                                      |
| Search                  | Input scope is intended for search strings.                                                                                               |                     InputTypes.ClassText                     |        UIKeyboardType.Default        |
| SearchIncremental       | Input scope is intended for search boxes where incremental results are displayed as the user types.                                       |                                                              |                                      |
| TelephoneAreaCode       | Input scope is intended for working with a numeric telephone area code.                                                                   |                                                              |                                      |
| TelephoneCountryCode    | Input scope is intended for working with a numeric telephone country code.                                                                |                                                              |                                      |
| TelephoneLocalNumber    | Input scope is intended for working with a local telephone number.                                                                        |                                                              |                                      |
| TelephoneNumber         | Input scope is intended for working with telephone numbers.                                                                               |                    InputTypes.ClassPhone                     |       UIKeyboardType.PhonePad        |
| Text                    | Input scope is intended for working with text.                                                                                            |                                                              |                                      |
| TimeHour                | Input scope is intended for working with a numeric hour of the day.                                                                       |                                                              |                                      |
| TimeMinutesOrSeconds    | Input scope is intended for working with a numeric minute of the hour, or second of the minute.                                           |                                                              |                                      |
| Url                     | Indicates a Uniform Resource Identifier (URI). This can include URL, File, or File Transfer Protocol (FTP) formats.                       |     InputTypes.ClassText OR InputTypes.TextVariationUri      |          UIKeyboardType.Url          |

\[\*: Workaround]

## Controlling the Keyboard on iOS

If a view needs to keep the keyboard opened when tapping on it, use the `Uno.UI.Controls.Window.SetNeedsKeyboard` attached property.

## Paste event

Support for capturing and handling the `Paste` event is implemented on all targets except for macOS.

In the case of Android, it is currently limited to the pastes that are triggered by the native context menu (e.g. after long-pressing the `TextBox`). It cannot detect paste triggered by the virtual keyboard or via a hardware keyboard shortcut.

## Pointer capture on WebAssembly

In addition to focus, `TextBox` control also captures pointers, so that manipulations like scrolling through contents are possible. However, on WASM setting the programmatic capture will prevent the native scrolling behavior of the underlying `<input>`. For that reason, we avoid performing the pointer capture in this case. If you still want to capture the pointer, you can do so by setting the `IsPointerCaptureRequired` attached property to `true`:

In C#:

```csharp
#if __WASM__
myTextBox.IsPointerCaptureRequired = true;
#endif
```

Or in XAML:

```xml
<TextBox wasm:IsPointerCaptureRequired="True" />
```

> Follow [Platform-specific XAML guide](xref:Uno.Development.PlatformSpecificXaml) to add the `wasm` namespace.

The value only affects WebAssembly, all other targets capture by default.

## Customizing the Enter key appearance

On mobile targets you can customize the visual appearance of the Enter key on the virtual keyboard. This can be done using the `TextBoxExtensions.InputReturnType` attached property:

```csharp
Uno.UI.Xaml.Controls.TextBoxExtensions.SetInputReturnType(myTextBox, Uno.UI.Xaml.Controls.InputReturnType.Search);
```

These are the supported input return type values:

- **Enter**: Typically indicating inserting a new line.
- **Done**: There is nothing more to input, and the input method editor (IME) will be closed.
- **Go**: Typically meaning to take the user to the target of the text they typed.
- **Next**: Typically taking the user to the next field that will accept text.
- **Previous**: Typically taking the user to the previous field that will accept text.
- **Search**: Typically taking the user to the results of searching for the text they have typed.
- **Send**: Typically delivering the text to its target.
- **Default**: System default.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Maui/ThirdParty-DevExpress.md

---
uid: Uno.Extensions.Maui.ThirdParty.DevExpress
---

# .NET MAUI Embedding - DevExpress .NET MAUI Controls

The controls from [DevExpress .NET MAUI Controls](https://www.devexpress.com/maui/) can be used in an Uno Platform application via .NET MAUI Embedding.

## Sample App

An existing sample app that showcases the controls is available [here](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/DevExpressApp).

> [!NOTE]
> DevExpress .NET MAUI Controls are currently only compatible with Android and iOS with Uno Platform at the moment.

## Installation

The DevExpress .NET MAUI Controls are currently available [free of charge](https://www.devexpress.com/maui/). However, in order to access the NuGet packages you do need to create an account at [DevExpress website](https://www.devexpress.com/MyAccount/Register/?returnUrl=https%3a%2f%2fnuget.devexpress.com%2f%23feed-url).

Once you have an account with DevExpress, you need to visit the [Your DevExpress NuGet Feed URL](https://nuget.devexpress.com/#feed-url) page to retrieve a NuGet feed that's associated with your account. You can either add this as a NuGet feed in Visual Studio or use a nuget.config file.

```xml
<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="DevExpress Private Feed" value="[your NuGet feed goes here]" />
  </packageSources>
</configuration>
```

## Getting Started

### [Visual Studio](#tab/vs)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Visual Studio** installed, follow [these instructions](xref:Uno.GetStarted.vs2022).

- Launch **Visual Studio** and click on **Create new project** on the Start Window. Alternatively, if you're already in Visual Studio, click **New, Project** from the **File** menu.

- Type `Uno Platform` in the search box

- Click **Uno Platform App**, then **Next**

- Name the project `DevExpressApp` and click **Create**

At this point you'll enter the **Uno Platform Template Wizard**, giving you options to customize the generated application.

- Select **Blank** in **Presets** selection

- Select the **Platforms** tab and unselect **WebAssembly**, **macOS (Catalyst)**, **Windows**, and **Desktop** platforms

- Select the **Features** tab and click on **.NET MAUI Embedding** and **Toolkit**

- Click **Create** to complete the wizard

The template will create a solution with a single cross-platform project, named `DevExpressApp`, ready to run.

For more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

### [Command Line](#tab/cli)

> [!NOTE]
> If you don't have the **Uno Platform dotnet new templates** installed, follow [dotnet new templates for Uno Platform](xref:Uno.GetStarted.dotnet-new).

Create a new application using the `unoapp` template, enabling .NET MAUI Embedding. In this case, we're going to use the Blank template (`-preset blank`) and include .NET MAUI Embedding support (`-maui`).

```bash
dotnet new unoapp -preset blank -maui -toolkit -platforms "android" -platforms "ios" -o DevExpressApp
```

This will create a new folder called **DevExpressApp** containing the new application.

---

## NuGet Packages

Add a reference to `DevExpress.Maui.DataGrid` to the DevExpressApp.MauiControls project.

## Updating AppBuilderExtensions

In the `AppBuilderExtensions` class, on `DevExpressApp.MauiControls` project, update the `UseMauiControls` extension method to call the `UseDevExpress` method.

```csharp
using DevExpress.Maui;

namespace DevExpressApp;

public static class AppBuilderExtensions
{
    public static MauiAppBuilder UseMauiControls(this MauiAppBuilder builder)
        => builder
            .UseDevExpress()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("Assets/Fonts/OpenSansRegular.ttf", "OpenSansRegular");
                fonts.AddFont("Assets/Fonts/OpenSansSemibold.ttf", "OpenSansSemibold");
            });
}
```

## Adding DataGridView Control

1. Update the `EmbeddedControl.xaml` in the `DevExpressApp.MauiControls` project with the following XAML that includes the `DataGridView` control:

    ```xml
    <?xml version="1.0" encoding="utf-8" ?>
    <ContentView
        x:Class="DevExpressApp.MauiControls.EmbeddedControl"
        xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
        xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
        xmlns:dxg="clr-namespace:DevExpress.Maui.DataGrid;assembly=DevExpress.Maui.DataGrid">
        <dxg:DataGridView ItemsSource="{Binding Employees}">
            <dxg:DataGridView.Columns>
                <dxg:TextColumn FieldName="Name" Caption="Name" />
                <dxg:TextColumn FieldName="Position" Caption="Job"/>
            </dxg:DataGridView.Columns>
        </dxg:DataGridView>
    </ContentView>
    ```

    > [!NOTE]
    > You may notice that the `Binding` markup extension is used on some properties. The `MauiEmbedding` can handle bindings between MAUI Controls and Uno Platform, just make sure the property in the `Binding` expression matches the property on your ViewModel.

1. Update the `EmbeddedControl.xaml.cs` with the following code:

    ```csharp
    namespace DevExpressApp.MauiControls;

    public partial class EmbeddedControl : ContentView
    {
        public EmbeddedControl()
        {
            InitializeComponent();
        }
    }
    ```

1. It's time to create the ViewModel that will hold the properties that will be data bound to the `DataGridViewControl` control. In the `DevExpressApp` project, create a new folder called `ViewModels` and add a new class called `MainViewModel`. This class will have the following code:

    ```csharp
    namespace DevExpressApp.ViewModels;

    public class MainViewModel
    {
        public IReadOnlyList<Employee> Employees { get; }= new EmployeeData().Employees;
    }
    ```

1. And let's create the `Employee` model and mock it.

    ```csharp
    public enum AccessLevel
    {
        Admin,
        User
    }

    public class Employee
    {
        public Employee(string name)
        {
            this.Name = name;
        }

        public string Name { get; }
        public DateTime BirthDate { get; set; }
        public DateTime HireDate { get; set; }
        public string? Position { get; set; }
        public string? Address { get; set; }
        public string? Phone { get; set; }
        public AccessLevel Access { get; set; }
        public bool OnVacation { get; set; }
    }

    public class EmployeeData {
        void GenerateEmployees() {
            ObservableCollection<Employee> result = new ObservableCollection<Employee>();
            result.Add(
                new Employee("Nancy Davolio") {
                    BirthDate = new DateTime(1978, 12, 8),
                    HireDate = new DateTime(2005, 5, 1),
                    Position = "Sales Representative",
                    Address = "98122, 507 - 20th Ave. E. Apt. 2A, Seattle WA, USA",
                    Phone = "(206) 555-9857",
                    Access = AccessLevel.User,
                    OnVacation = false
                }
            );
            result.Add(
                new Employee("Andrew Fuller") {
                    BirthDate = new DateTime(1965, 2, 19),
                    HireDate = new DateTime(1992, 8, 14),
                    Position = "Vice President, Sales",
                    Address = "98401, 908 W. Capital Way, Tacoma WA, USA",
                    Phone = "(206) 555-9482",
                    Access = AccessLevel.Admin,
                    OnVacation = false
                }
            );
            result.Add(
                new Employee("Janet Leverling") {
                    BirthDate = new DateTime(1985, 8, 30),
                    HireDate = new DateTime(2002, 4, 1),
                    Position = "Sales Representative",
                    Address = "98033, 722 Moss Bay Blvd., Kirkland WA, USA",
                    Phone = "(206) 555-3412",
                    Access = AccessLevel.User,
                    OnVacation = false
                }
            );
            result.Add(
                new Employee("Margaret Peacock") {
                    BirthDate = new DateTime(1973, 9, 19),
                    HireDate = new DateTime(1993, 5, 3),
                    Position = "Sales Representative",
                    Address = "98052, 4110 Old Redmond Rd., Redmond WA, USA",
                    Phone = "(206) 555-8122",
                    Access = AccessLevel.User,
                    OnVacation = false
                }
            );
            result.Add(
                new Employee("Steven Buchanan") {
                    BirthDate = new DateTime(1955, 3, 4),
                    HireDate = new DateTime(1993, 10, 17),
                    Position = "Sales Manager",
                    Address = "SW1 8JR, 14 Garrett Hill, London, UK",
                    Phone = "(71) 555-4848",
                    Access = AccessLevel.User,
                    OnVacation = true
                }
            );
            result.Add(
                new Employee("Michael Suyama") {
                    BirthDate = new DateTime(1981, 7, 2),
                    HireDate = new DateTime(1999, 10, 17),
                    Position = "Sales Representative",
                    Address = "EC2 7JR, Coventry House Miner Rd., London, UK",
                    Phone = "(71) 555-7773",
                    Access = AccessLevel.User,
                    OnVacation = false
                }
            );
            result.Add(
                new Employee("Robert King") {
                    BirthDate = new DateTime(1960, 5, 29),
                    HireDate = new DateTime(1994, 1, 2),
                    Position = "Sales Representative",
                    Address = "RG1 9SP, Edgeham Hollow Winchester Way, London, UK",
                    Phone = "(71) 555-5598",
                    Access = AccessLevel.User,
                    OnVacation = false
                }
            );
            result.Add(
                new Employee("Laura Callahan") {
                    BirthDate = new DateTime(1985, 1, 9),
                    HireDate = new DateTime(2004, 3, 5),
                    Position = "Inside Sales Coordinator",
                    Address = "98105, 4726 - 11th Ave. N.E., Seattle WA, USA",
                    Phone = "(206) 555-1189",
                    Access = AccessLevel.User,
                    OnVacation = true
                }
            );
            result.Add(
                new Employee("Anne Dodsworth") {
                    BirthDate = new DateTime(1980, 1, 27),
                    HireDate = new DateTime(2004, 11, 15),
                    Position = "Sales Representative",
                    Address = "WG2 7LT, 7 Houndstooth Rd., London, UK",
                    Phone = "(71) 555-4444",
                    Access = AccessLevel.User,
                    OnVacation = false
                }
            );
            Employees = result;
        }

        public ObservableCollection<Employee> Employees { get; private set; }

        public EmployeeData() {
            GenerateEmployees();
        }
    }
    ```

1. The final step is to add the `MainViewModel` as the `DataContext` of the `MainPage.xaml` file. The final `MainPage.xaml` file will look like this:

    ```xml
    <Page x:Class="DevExpressApp.MainPage"
          xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
          xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
          xmlns:local="using:DevExpressApp.ViewModels"
          xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
          xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
          xmlns:utu="using:Uno.Toolkit.UI"
          utu:SafeArea.Insets="VisibleBounds"
          mc:Ignorable="d"
          Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <Page.DataContext>
            <local:MainViewModel />
        </Page.DataContext>
        <Border>
            <embed:MauiHost xmlns:controls="using:DevExpressApp.MauiControls"
                            xmlns:embed="using:Uno.Extensions.Maui"
                            Source="controls:EmbeddedControl" />
        </Border>
    </Page>
    ```

1. Now the project is good to go! Press F5 and you should see the `DataGridView` control working as expected.
   For more detailed instructions specific to each platform, refer to the [Debug the App](xref:Uno.GettingStarted.CreateAnApp.VS2022#debug-the-app) documentation.

## App Render Output

- **Android:**

    ![Android DevExpress](Assets/Screenshots/Android/DevExpress.png)

- **iOS:**

    ![iOS DevExpress](Assets/Screenshots/iOS/DevExpress.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Maui/ThirdParty-EsriMaps.md

---
uid: Uno.Extensions.Maui.ThirdParty.EsriMaps
---
# .NET MAUI Embedding - Esri ArcGIS Maps SDK for .NET

The MapView control, that's part of the ArcGIS Maps SDK for .NET, can be used in an Uno Platform application via .NET MAUI Embedding.

## Sample App

An existing sample app that showcases the controls is available [here](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/ArcGisApp).

> [!NOTE]
> For this sample you don't need to have a license, because it's just a demo and for development purposes.
>
> Esri ArcGIS Maps SDK for .NET is currently only compatible with Windows, Android, iOS, and Mac Catalyst when used with Uno Platform at the moment.

## Installation

In order to use the MapView control, you first need to create an account via the [ArcGIS Developers portal](https://developers.arcgis.com/sign-up/), and depending on the use of location services, you may also need an API key. This walkthrough does not require a license or an API key to run.

## Getting Started

### [Visual Studio](#tab/vs)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Visual Studio** installed, follow [these instructions](xref:Uno.GetStarted.vs2022).

- Launch **Visual Studio** and click on **Create new project** on the Start Window. Alternatively, if you're already in Visual Studio, click **New, Project** from the **File** menu.

- Type `Uno Platform` in the search box

- Click **Uno Platform App**, then **Next**

- Name the project `ArcGisApp` and click **Create**

At this point you'll enter the **Uno Platform Template Wizard**, giving you options to customize the generated application.

- Select **Blank** in **Presets** selection

- Select the **Platforms** tab and unselect **Desktop** and **Web Assembly** platforms

- Select the **Features** tab and click on **.NET MAUI Embedding**

- Click **Create** to complete the wizard

The template will create a solution with a single cross-platform project, named `ArcGisApp`, ready to run.

For more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

### [Command Line](#tab/cli)

> [!NOTE]
> If you don't have the **Uno Platform dotnet new templates** installed, follow [dotnet new templates for Uno Platform](xref:Uno.GetStarted.dotnet-new).

Create a new application using the `unoapp` template, enabling .NET MAUI Embedding. In this case, we're going to use the Blank template (`-preset blank`) and include .NET MAUI Embedding support (`-maui`).

```bash
dotnet new unoapp -preset blank -maui -platforms "android" -platforms "ios" -platforms "maccatalyst" -platforms "windows" -o ArcGisApp
```

This will create a new folder called **ArcGisApp** containing the new application.

---

## Nuget Packages

Add a reference to the [Esri.ArcGISRuntime.Maui NuGet package](https://www.nuget.org/packages/Esri.ArcGISRuntime.Maui) to the `ArcGisApp.MauiControls` project.

## Updating AppBuilderExtensions

In the `AppBuilderExtensions` class, on `ArcGisApp.MauiControls` project, update the `UseMauiControls` extension method to call the `UseArcGISRuntime` method.

```cs
using Esri.ArcGISRuntime;
using Esri.ArcGISRuntime.Maui;
using Esri.ArcGISRuntime.Security;

namespace ArcGisApp;

public static class AppBuilderExtensions
{
    public static MauiAppBuilder UseMauiControls(this MauiAppBuilder builder) 
        => builder
            .UseArcGISRuntime(
            //config => config
            //    .UseLicense("[Your ArcGIS Maps SDK License key]")
            //    .UseApiKey("[Your ArcGIS location services API Key]")
            //    .ConfigureAuthentication(auth => auth
            //        .UseDefaultChallengeHandler() // Use the default authentication dialog
            //    )
            )
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("Assets/Fonts/OpenSansRegular.ttf", "OpenSansRegular");
                fonts.AddFont("Assets/Fonts/OpenSansSemibold.ttf", "OpenSansSemibold");
            });
}
```

> [!NOTE]
> If you have a license key and/or a location service API key, uncomment the `delegate` provided on `UseArcGISRuntime` method. This isn't required to run this sample.

## Adding MapView

1. Update the EmbeddedControl.xaml in the `MauiEmbedding.MauiControls` project with the following XAML that includes the `MapView` control.

    ```xml
    <?xml version="1.0" encoding="utf-8" ?>
    <ContentView 
        xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
        xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
        xmlns:esriUI="clr-namespace:Esri.ArcGISRuntime.Maui;assembly=Esri.ArcGISRuntime.Maui"
        x:Class="ArcGisApp.MauiControls.EmbeddedControl">
        <Grid>
            <esriUI:MapView x:Name="mapView"
                            HeightRequest="300"
                            WidthRequest="300" />
        </Grid>
    </ContentView>
    ```

1. Update the EmbeddedControl.xaml.cs with the following code

    ```cs
    using Esri.ArcGISRuntime.Geometry;
    using Esri.ArcGISRuntime.Mapping;
    using Map = Esri.ArcGISRuntime.Mapping.Map;

    namespace ArcGisApp.MauiControls;

    public partial class EmbeddedControl : ContentView
    {
        public EmbeddedControl()
        {
            InitializeComponent();

            var myMap = new Map()
            {
                InitialViewpoint = new Viewpoint(new Envelope(-180, -85, 180, 85, SpatialReferences.Wgs84)),
                Basemap = new Basemap(new Uri("https://arcgis.com/home/item.html?id=86265e5a4bbb4187a59719cf134e0018"))
            };

            // Assign the map to the MapView.
            mapView.Map = myMap;
        }
    }
    ```

1. Now the project is good to go! Press F5 and should see the MapView control running on your application.
   For more detailed instructions specific to each platform, refer to the [Debug the App](xref:Uno.GettingStarted.CreateAnApp.VS2022#debug-the-app) documentation.

## App Render Output

- **Android:**

    ![Android EsriMaps](Assets/Screenshots/Android/EsriMaps.png)

- **iOS:**

    ![iOS EsriMaps](Assets/Screenshots/iOS/EsriMaps.png)

- **Mac Catalyst:**

    ![Mac Catalyst EsriMaps](Assets/Screenshots/MacCatalyst/EsriMaps.png)

- **Windows:**

    ![Windows EsriMaps](Assets/Screenshots/Windows/EsriMaps.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Maui/ThirdParty-GrapeCity.md

---
uid: Uno.Extensions.Maui.ThirdParty.GrapeCity
---
# .NET MAUI Embedding - GrapeCity ComponentOne .NET MAUI Controls

The FlexGrid and Calendar in the ComponentOne .NET MAUI Controls can be used in an Uno Platform application via .NET MAUI Embedding.

## Sample App

An existing sample app that showcases the controls is available [here](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/GrapeCityApp).

## Installation

In order to use the ComponentOne controls, you first need to install the ComponentOne ControlPanel following [these instructions](https://www.grapecity.com/componentone/docs/maui/online-maui/get-started.html).

## Getting Started

1. Create a new application using the `unoapp` template, enabling .NET MAUI Embedding. In this case, we're going to use the Blank template (`-preset blank`) and include .NET MAUI Embedding support (`-maui`).

    ```dotnetcli
    dotnet new unoapp -preset blank -maui -o MauiEmbeddingApp
    ```

1. Remove the `net8.0` target framework from both the MauiEmbeddingApp and MauiEmbeddingApp.MauiControls projects.  GrapeCity doesn't provide reference assemblies for `net8.0`, so the `net8.0` target framework needs to be removed to avoid build errors.

1. Next, add a reference to the C1 .NET MAUI NuGet packages to the MauiEmbeddingApp.MauiControls project. If you want to use the FlexGrid control, add a reference to [`C1.Maui.Grid`](https://www.nuget.org/packages/C1.Maui.Grid). If you want to use the Calendar control, add a reference to [`C1.Maui.Calendar`](https://www.nuget.org/packages/C1.Maui.Calendar).

1. In the `AppBuilderExtensions` class, update the `UseMauiControls` extension method to call either, or both, the `RegisterFlexGridControls` or `RegisterCalendarControls` methods.

    ```cs
    using C1.Maui.Grid;
    using C1.Maui.Calendar;

    namespace MauiEmbeddingApp;

    public static class AppBuilderExtensions
    {
      public static MauiAppBuilder UseMauiControls(this MauiAppBuilder builder)
        => builder
                .RegisterFlexGridControls()
                .RegisterCalendarControls()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansRegular.ttf", "OpenSansRegular");
                    fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansSemibold.ttf", "OpenSansSemibold");
                });
    }
    ```

## Adding FlexGrid

1. Follow the [FlexGrid Quick Start](https://www.grapecity.com/componentone/docs/maui/online-maui/flexgrid-quickstart.html) to apply XAML to the EmbeddedControl.xaml and C# code to the EmbeddedControl.xaml.cs (in the constructor).

1. Add Customer class (see https://www.grapecity.com/componentone/docs/maui/online-maui/customerclass.html).

1. Wrap content in `ScrollViewer` on the `MainPage` of the Uno Platform application to make sure the full `FlexGrid` and other controls can be scrolled into the view.

### App Render Output

- **Android:**
  - ![Android FlexGrid](Assets/Screenshots/Android/C1_FlexGrid.png)

- **Windows:**
  - ![Windows FlexGrid](Assets/Screenshots/Windows/C1_FlexGrid.png)

## Adding Calendar

1. Follow the [Calendar Quick Start](https://www.grapecity.com/componentone/docs/maui/online-maui/calendarquickstart.html) to apply XAML to the EmbeddedControl.xaml.

1. In order for the Calendar control to render correctly on all platforms you should set both `HeightRequest` and `WidthRequest` attributes on the Calendar control.

### App Render Output

- **Android:**
  - ![Android Calendar](Assets/Screenshots/Android/C1_Calendar.png)

- **Windows:**
  - ![Windows Calendar](Assets/Screenshots/Windows/C1_Calendar.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Maui/ThirdParty-GrialKit.md

---
uid: Uno.Extensions.Maui.ThirdParty.GrialKit
---
# .NET MAUI Embedding - Grial UI Kit

The controls from Grial UI Kit can be used in an Uno Platform application via .NET MAUI Embedding.

## Sample App

An existing sample app that showcases the controls is available [here](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/GrialKitApp).

## Installation

In order to use the Grial UI Kit controls, you first need to [sign up](https://admin.grialkit.com/secure/grial/front/signup).

After signing up, when you log in to the [admin portal](https://admin.grialkit.com), you'll be prompted to create a Grial app by entering the name of the application. Once you've created the Grial app, go to the Download tab and select `Download Kickoff Solution` - at this point, you'll be prompted to purchase a license, which you'll need in order to proceed with using Grial.

Extract the downloaded zip file and locate the GrialLicense file. We'll add this file to the Uno application. Also in the zip file, open the csproj file and retrieve the ApplicationTitle and ApplicationId property values.

```xml
<!-- Display name -->
<ApplicationTitle>[ApplicationTitle]</ApplicationTitle>
<!-- App Identifier -->
<ApplicationId>[ApplicationId]</ApplicationId>
```

The last thing we'll need from the zip file is the nuget.config file. This file will also be added to the Uno application.

## Getting Started

1. Create a new application using the `unoapp` template, enabling .NET MAUI Embedding. In this case, we're going to use the Blank template (`-preset blank`) and include .NET MAUI Embedding support (`-maui`).

    ```dotnetcli
    dotnet new unoapp -preset blank -maui -o MauiEmbeddingApp
    ```

1. Remove the `net8.0`, `net8.0-maccatalyst`, and `net8.0-windows10.0.19041.0` target frameworks from both the MauiEmbeddingApp and MauiEmbeddingApp.MauiControls projects.  

1. Remove the `net8.0-maccatalyst` target framework from the MauiEmbeddingApp.Mobile project.  

1. Remove the `MauiEmbeddingApp.Windows` project from the solution.  

1. Add the `GrailLicense` file to the MauiEmbeddingApp.MauiControls project as an `EmbeddedResource`

1. Add the nuget.config file to the solution folder and make sure that the `packageSourceCredentials` section includes username and password. If you're missing credentials, go to the [profile page](https://admin.grialkit.com/secure/grial/front/profile) in the admin portal and click on the Nuget tab where you can create credentials for your account.

    ```xml
    <?xml version="1.0" encoding="utf-8"?>
    <configuration>
      <packageSourceCredentials>
        <UXDivers>
          <add key="Username" value="[username]" />
          <add key="ClearTextPassword" value="[password]" />
        </UXDivers>
      </packageSourceCredentials>
      <packageSources>
        <clear />
        <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
        <add key="UXDivers" value="https://nuget.uxdivers.com/grial" />
      </packageSources>
    </configuration>
    ```

1. In the project file (csproj) for MauiEmbeddingApp.Mobile update the `ApplicationTitle` and `ApplicationId` properties with those retrieved earlier from the zip file.

1. Expand out the MauiEmbeddingApp.Mobile project and locate the Main.Android.cs file. Change the Label property of the ApplicationAttribute from `@string/ApplicationName` to the ApplicationTitle retrieved earlier from the zip file.

    ```cs
    [global::Android.App.ApplicationAttribute(
        Label = "ApplicationTitle",
        Icon = "@mipmap/iconapp",
        LargeHeap = true,
        HardwareAccelerated = true,
        Theme = "@style/AppTheme"
    )]
    public class Application : Microsoft.UI.Xaml.NativeApplication
    ```

1. Add a reference to the UXDivers.GrialMaui NuGet packages to the MauiEmbeddingApp.MauiControls project.  

1. In the `AppBuilderExtensions` class, update the `UseMauiControls` extension method to call the `GrialKit.Init` and `UseGrial` methods.  

    ```cs
    using UXDivers.Grial;

    namespace MauiEmbeddingApp;

    public static class AppBuilderExtensions
    {
        public static MauiAppBuilder UseMauiControls(this MauiAppBuilder builder)
        {
    #if __IOS__
            var theme = new ThemeColorsBase(new Dictionary<string, Color>
            {
                    { "AccentColor", Color.FromArgb("#FF3F75FF") }
            });

            GrialKit.Init(theme, "MauiEmbeddingApp.MauiControls.GrialLicense");
    #else
            GrialKit.Init("MauiEmbeddingApp.MauiControls.GrialLicense");
    #endif
            return builder
                .UseGrial()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansRegular.ttf", "OpenSansRegular");
                    fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansSemibold.ttf", "OpenSansSemibold");
                });
        }
    }
    ```

## Adding a PieChart

The PieChart is one of many controls that's available in the Grial UI Kit. More information about the PieChart and other controls is available in the [Grial UI Kit Documentation](https://docs.grialkit.com/charts/pie-chart)

1. Update the EmbeddedControl.xaml in the `MauiEmbedding.MauiControls` project with the following XAML that includes the PieChart

    ```xml
    <?xml version="1.0" encoding="utf-8" ?>
    <ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
                xmlns:grial="http://uxdivers.com/grial"
                x:Class="MauiEmbeddingApp.MauiControls.EmbeddedControl"
                HorizontalOptions="Fill"
                VerticalOptions="Fill">
      <ContentPage.Resources>
        <grial:ChartTheme x:Key="PieTheme">
          <SolidColorBrush Color="#F9B300" />
          <SolidColorBrush Color="#FF602E" />
          <SolidColorBrush Color="#B146C2" />
          <SolidColorBrush Color="#5AC8FA" />
          <SolidColorBrush Color="#46C771" />
          <SolidColorBrush Color="#3F75FF" />
        </grial:ChartTheme>
      </ContentPage.Resources>

      <VerticalStackLayout Padding="30">
        <grial:PieChart x:Name="chart"
                        HeightRequest="400"
                        BackgroundColor="Transparent"
                        IsAnimated="False"
                        LabelFontColor="DimGray"
                        LabelFontSize="12"
                        StrokeSize="0"
                        Theme="{ StaticResource PieTheme }">
          <grial:PieSeries InnerRadius="{ Binding Value, Source={x:Reference radius} }"
                          ItemsSource="{ Binding . }"
                          Radius="120"
                          ValuePath="Value" />
          </grial:PieChart>

        <Label Text="{Binding Value, Source={x:Reference radius}, StringFormat='InnerRadius: {0:F2}'}" />

        <Slider Maximum=".9"
                Minimum="0"
                Value="0.8"
                x:Name="radius" />
      </VerticalStackLayout>
    </ContentView>
    ```

1. Update the EmbeddedControl.xaml.cs with the following code that sets the `BindingContext` for the chart (the PieChart) to be a basic set of data.

    ```cs
    namespace MauiEmbeddingApp.MauiControls;

    public partial class EmbeddedControl : ContentView
    {
        public EmbeddedControl()
        {
            InitializeComponent();

            chart.BindingContext = new[]
            {
              new {
                Value = 521.02,
              },
              new {
                Value = 62.56,
              },
              new {
                Value = 245.52,
              },
              new {
                Value = 33.26,
              },
              new {
                Value = 33.26,
              },
              new {
                Value = 78.95,
              }
          };
        }
    }
    ```

## App Render Output

- **Android:**
  - ![Android GrialKit](Assets/Screenshots/Android/GrialKit.png)

- **iOS:**
  - ![iOS GrialKit](Assets/Screenshots/iOS/GrialKit.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Maui/ThirdParty-MauiCommunityToolkit.md

---
uid: Uno.Extensions.Maui.ThirdParty.MauiCommunityToolkit
---
# .NET MAUI Embedding - MauiCommunityToolkit

The controls from MauiCommunityToolkit can be used in an Uno Platform application via .NET MAUI Embedding.

## Sample App

An existing sample app that showcases the controls is available [here](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/MauiCommunityToolkitApp).

## Getting Started

1. Create a new application using the `unoapp` template, enabling .NET MAUI Embedding. In this case, we're going to use the Blank template (`-preset blank`) and include .NET MAUI Embedding support (`-maui`).

    ```dotnetcli
    dotnet new unoapp -preset blank -maui -o MauiEmbeddingApp
    ```

1. Add a reference to the [CommunityToolkit.Maui NuGet package](https://www.nuget.org/packages/CommunityToolkit.Maui) to the MauiEmbeddingApp.MauiControls project.

1. In the `AppBuilderExtensions` class, on `MauiEmbeddingApp.MauiControls` project, update the `UseMauiControls` extension method to call the `UseMauiCommunityToolkit` method.

    ```cs
    using CommunityToolkit.Maui;

    namespace MauiEmbeddingApp;

    public static class AppBuilderExtensions
    {
        public static MauiAppBuilder UseMauiControls(this MauiAppBuilder builder)
            => builder
                .UseMauiCommunityToolkit()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansRegular.ttf", "OpenSansRegular");
                    fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansSemibold.ttf", "OpenSansSemibold");
                });
    }
    ```

## Adding DrawingView

1. Update the EmbeddedControl.xaml in the `MauiEmbedding.MauiControls` project with the following XAML that includes the `DrawingView` control

    ```xml
    <?xml version="1.0" encoding="utf-8" ?>
    <ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
                x:Class="MauiEmbeddingApp.MauiControls.EmbeddedControl"
                HorizontalOptions="Fill"
                VerticalOptions="Fill">
        <toolkit:DrawingView IsMultiLineModeEnabled="{Binding IsMultiLineModeEnabled}"
                            LineColor="Fuchsia"
                            LineWidth="5"
                            ShouldClearOnFinish="{Binding ShouldCleanOnFinish}" />
    </ContentView>
    ```

    > [!NOTE]
    > You may notice that the `Binding` markup extension is used on some properties. The `MauiEmbedding` can handle bindings between Maui Controls and UnoPlatform, just make sure the property in the `Binding` expression matches the property on your ViewModel.

1. Update the EmbeddedControl.xaml.cs with the following code.

    ```cs
    namespace MauiEmbeddingApp.MauiControls;

    public partial class EmbeddedControl : ContentView
    {
        public EmbeddedControl()
        {
            this.InitializeComponent();
        }
    }
    ```

1. Now let's create the controls that will control the `DrawingView.IsMultiLineModeEnabled` and `DrawingView.ShouldClearOnFinish` properties. Update the MainPage.xaml in the `MauiEmbeddingApp` project with the following xaml:

    ```xml
    <Page x:Class="MauiEmbeddingApp.MainPage"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        mc:Ignorable="d"
        Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <Grid>
            <Grid.RowDefinitions>
                <RowDefinition Height="Auto" />
                <RowDefinition Height="*" />
            </Grid.RowDefinitions>
            <StackPanel>
                <TextBlock Text="Clean on Finish:" />
                <ToggleSwitch IsOn="{Binding ShouldCleanOnFinish, Mode=TwoWay}" />

                <TextBlock Text="MultiLineMode:" />
                <ToggleSwitch x:Name="MultiLineMode"
                            IsOn="{Binding IsMultiLineModeEnabled, Mode=TwoWay}" />
            </StackPanel>

            <embed:MauiHost xmlns:controls="using:MauiEmbeddingApp.MauiControls"
                            xmlns:embed="using:Uno.Extensions.Maui"
                            Grid.Row="1"
                            Source="controls:EmbeddedControl" />
        </Grid>
    </Page>
    ```

1. It's time to create the ViewModel that will hold the properties that will be data bound to the `DrawingView` control. On `MauiEmbeddingApp` project, create a new folder called `ViewModels` and add a new class called `MainViewModel`. This class will have the following code:

    ```cs
    namespace MauiEmbeddingApp.ViewModels;

    partial class MainViewModel : ObservableObject
    {
        [ObservableProperty]
        bool isMultiLineModeEnabled;

        [ObservableProperty]
        bool shouldCleanOnFinish;
    }
    ```

1. The `MainViewModel` uses the `ObservableObject` base class that comes from the `CommunityToolkit.MVVM` NuGet package. This significantly reduces the amount of boilerplate code required. Add a reference to the [CommunityToolkit.Mvvm NuGet package](https://www.nuget.org/packages/CommunityToolkit.Mvvm) to the MauiEmbeddingApp project.

1. The final step is to add the `MainViewModel` as the `DataContext` of the `Page` in the `MainPage.xaml` file. Here's how the final xaml should look.

    ```xml
    <Page x:Class="MauiEmbeddingApp.MainPage"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:MauiEmbeddingApp.ViewModels"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        mc:Ignorable="d"
        Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
        <Page.DataContext>
            <local:MainViewModel />
        </Page.DataContext>
        <Grid>
            <Grid.RowDefinitions>
                <RowDefinition Height="Auto" />
                <RowDefinition Height="*" />
            </Grid.RowDefinitions>
            <StackPanel>
                <TextBlock Text="Clean on Finish:" />
                <ToggleSwitch IsOn="{Binding ShouldCleanOnFinish, Mode=TwoWay}" />

                <TextBlock Text="MultiLineMode:" />
                <ToggleSwitch x:Name="MultiLineMode"
                            IsOn="{Binding IsMultiLineModeEnabled, Mode=TwoWay}" />
            </StackPanel>

            <embed:MauiHost xmlns:controls="using:MauiEmbeddingApp.MauiControls"
                            xmlns:embed="using:Uno.Extensions.Maui"
                            Grid.Row="1"
                            Source="controls:EmbeddedControl" />
        </Grid>
    </Page>
    ```

1. Now the project is good to go! Press F5 and you should see the `DrawingView` control working as expected. And tweaking the `ToggleSwitch` controls should change the `DrawingView` behavior.

## App Render Output

- **Android:**
  - ![Android CommunityToolkit](Assets/Screenshots/Android/CommunityToolkit.png)

- **Windows:**
  - ![Windows CommunityToolkit](Assets/Screenshots/Windows/CommunityToolkit.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Maui/ThirdParty-Synfusion.md

---
uid: Uno.Extensions.Maui.ThirdParty.Syncfusion
---
# .NET MAUI Embedding - Syncfusion .NET MAUI Controls

The controls from Syncfusion .NET MAUI Controls can be used in an Uno Platform application via .NET MAUI Embedding.

## Sample App

An existing sample app that showcases the controls is available [here](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/SyncfusionApp).

## Installation

In order to use the Syncfusion controls, you will need to create an account and purchase a Syncfusion license [here](https://help.syncfusion.com/maui/licensing/overview). This sample can be run in development without a license key.

## Getting Started

1. Create a new application using the `unoapp` template, enabling .NET MAUI Embedding. In this case, we're going to use the Blank template (`-preset blank`) and include .NET MAUI Embedding support (`-maui`).

    ```dotnetcli
    dotnet new unoapp -preset blank -maui -o MauiEmbeddingApp
    ```

1. Next, add a reference to the [Syncfusion.Maui.Charts package](https://www.nuget.org/packages/Syncfusion.Maui.Charts) to the `MauiEmbeddingApp.MauiControls` project.

1. In the `AppBuilderExtensions` class, on `MauiEmbeddingApp.MauiControls` project, update the `UseMauiControls` extension method to call the `ConfigureSyncfusionCore` method.

    ```cs
    using Syncfusion.Maui.Core.Hosting;

        namespace MauiEmbeddingApp;

        public static class AppBuilderExtensions
        {
            public static MauiAppBuilder UseMauiControls(this MauiAppBuilder builder)
                => builder
                    .ConfigureSyncfusionCore()
                    .ConfigureFonts(fonts =>
                    {
                        fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansRegular.ttf", "OpenSansRegular");
                        fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansSemibold.ttf", "OpenSansSemibold");
                    });
        }
    ```

## Adding SfCircularChart

1. Update the EmbeddedControl.xaml in the  `MauiEmbeddingApp.MauiControls` project with the following XAML that includes the `SfCircularChart` control, which will be used to display a doughnut shaped chart.

    ```xml
    <?xml version="1.0" encoding="utf-8" ?>
    <ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                xmlns:toolkit="http://schemas.microsoft.com/dotnet/2022/maui/toolkit"
                x:Class="MauiEmbeddingApp.MauiControls.EmbeddedControl"
                xmlns:chart="http://schemas.syncfusion.com/maui"
                xmlns:local="clr-namespace:MauiEmbeddingApp.MauiControls.ViewModels"
                HorizontalOptions="Fill"
                VerticalOptions="Fill">
        <chart:SfCircularChart x:Name="chart"
                            HorizontalOptions="Fill"
                            VerticalOptions="Fill">
            <chart:SfCircularChart.Title>
                <Label Text="Project Cost Breakdown"
                    Margin="0"
                    HorizontalOptions="Fill"
                    HorizontalTextAlignment="Center"
                    VerticalOptions="Center"
                    FontSize="16"
                    TextColor="Black" />
            </chart:SfCircularChart.Title>
            <chart:SfCircularChart.Legend>
                <chart:ChartLegend />
            </chart:SfCircularChart.Legend>
            <chart:SfCircularChart.Series>
                <chart:DoughnutSeries x:Name="series"
                                    ExplodeIndex="{Binding SelectedIndex}"
                                    ExplodeOnTouch="True"
                                    ShowDataLabels="True"
                                    Radius="0.9"
                                    PaletteBrushes="{Binding PaletteBrushes}"
                                    ItemsSource="{Binding DoughnutSeriesData}"
                                    XBindingPath="Name"
                                    YBindingPath="Value"
                                    EnableAnimation="False"
                                    StrokeWidth="1"
                                    Stroke="White"
                                    LegendIcon="SeriesType">
                    <chart:DoughnutSeries.CenterView>
                        <StackLayout x:Name="layout"
                                    HeightRequest="{Binding CenterHoleSize}"
                                    WidthRequest="{Binding CenterHoleSize}">
                            <Label Text="{Binding Name,Source={x:Reference embeddedViewModel}}"
                                FontSize="13"
                                HorizontalOptions="Center"
                                VerticalOptions="EndAndExpand"
                                Margin="5" />
                            <Label Text="{Binding Value,Source={x:Reference embeddedViewModel},StringFormat='{0}%'}"
                                FontSize="12"
                                HorizontalOptions="Center"
                                VerticalOptions="StartAndExpand"
                                Margin="5" />
                        </StackLayout>
                    </chart:DoughnutSeries.CenterView>
                    <chart:DoughnutSeries.DataLabelSettings>
                        <chart:CircularDataLabelSettings>
                            <chart:CircularDataLabelSettings.LabelStyle>
                                <chart:ChartDataLabelStyle LabelFormat="0'M" />
                            </chart:CircularDataLabelSettings.LabelStyle>
                        </chart:CircularDataLabelSettings>
                    </chart:DoughnutSeries.DataLabelSettings>
                </chart:DoughnutSeries>
            </chart:SfCircularChart.Series>
        </chart:SfCircularChart>
    </ContentView>
    ```

1. Update the EmbeddedControl.xaml.cs with the following code.

    ```cs
    namespace MauiEmbeddingApp.MauiControls;

    public partial class EmbeddedControl : ContentView
    {
        public EmbeddedControl()
        {
            InitializeComponent();
        }
    }
    ```

1. It's time to create the ViewModel that will hold the properties that will be data bound to the `SfCircularChart` control. In `MauiEmbeddingApp.MauiControls` project, create a new folder called `ViewModels` and add a new class called `EmbeddedViewModel`. This class will have the following code:

    ```cs
    using MauiEmbeddingApp.MauiControls.Models;
    using Syncfusion.Maui.Charts;
    using System.Collections.ObjectModel;
    using System.ComponentModel;
    using System.Windows.Input;

    namespace MauiEmbeddingApp.MauiControls.ViewModels;

    public class EmbeddedViewModel : INotifyPropertyChanged
    {
        public event PropertyChangedEventHandler? PropertyChanged;

        public ObservableCollection<Brush> PaletteBrushes { get; set; }
        public ObservableCollection<Brush> SelectionBrushes { get; set; }
        public ObservableCollection<Brush> CustomColor1 { get; set; }

        public ObservableCollection<Brush> CustomColor2 { get; set; }
        public ObservableCollection<Brush> AlterColor1 { get; set; }
        public ICommand TapCommand => new Command<string>(async (url) => await Launcher.OpenAsync(url));

        public Array PieGroupMode
        {
            get { return Enum.GetValues(typeof(PieGroupMode)); }
        }

        private bool enableAnimation = true;
        public bool EnableAnimation
        {
            get { return enableAnimation; }
            set
            {
                enableAnimation = value;
                OnPropertyChanged("EnableAnimation");
            }
        }

        public void OnPropertyChanged(string name)
        {
            PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
        }


        public ObservableCollection<ChartDataModel> DoughnutSeriesData { get; set; }
        public ObservableCollection<ChartDataModel> SemiCircularData { get; set; }
        public ObservableCollection<ChartDataModel> CenterElevationData { get; set; }
        public ObservableCollection<ChartDataModel> GroupToData { get; set; }

        private int selectedIndex = 1;
        public int SelectedIndex
        {
            get { return selectedIndex; }
            set
            {
                selectedIndex = value;
                UpdateIndex(value);
                OnPropertyChanged("SelectedIndex");
            }
        }
        private string name = "";
        public string Name
        {
            get { return name; }
            set
            {
                name = value;
                OnPropertyChanged("Name");
            }
        }
        private int value1;
        public int Value
        {
            get { return value1; }
            set
            {
                value1 = value;
                OnPropertyChanged("Value");
            }
        }

        private int total = 357580;
        public int Total
        {
            get { return total; }
            set
            {
                total = value;
            }
        }

        private void UpdateIndex(int value)
        {
            if (value >= 0 && value < DoughnutSeriesData.Count)
            {
                var model = DoughnutSeriesData[value];
                if (model != null && model.Name != null)
                {
                    Name = model.Name;
                    double sum = DoughnutSeriesData.Sum(item => item.Value);
                    double SelectedItemsPercentage = model.Value / sum * 100;
                    SelectedItemsPercentage = Math.Floor(SelectedItemsPercentage * 100) / 100;
                    Value = (int)SelectedItemsPercentage;
                }
            }
        }

        public EmbeddedViewModel()
        {
            DoughnutSeriesData = new ObservableCollection<ChartDataModel>
                {
                    new ChartDataModel("Labor", 10),
                    new ChartDataModel("Legal", 8),
                    new ChartDataModel("Production", 7),
                    new ChartDataModel("License", 5),
                    new ChartDataModel("Facilities", 10),
                    new ChartDataModel("Taxes", 6),
                    new ChartDataModel("Insurance", 18)
            };

            SemiCircularData = new ObservableCollection<ChartDataModel>
                {
                    new ChartDataModel("Product A", 750),
                    new ChartDataModel("Product B", 463),
                    new ChartDataModel("Product C", 389),
                    new ChartDataModel("Product D", 697),
                    new ChartDataModel("Product E", 251)
                };

            CenterElevationData = new ObservableCollection<ChartDataModel>
                {
                    new ChartDataModel("Agriculture",51),
                    new ChartDataModel("Forest",30),
                    new ChartDataModel("Water",5.2),
                    new ChartDataModel("Others",14),
                };

            GroupToData = new ObservableCollection<ChartDataModel>
                {
                    new ChartDataModel("US",51.30,0.39),
                    new ChartDataModel("China",20.90,0.16),
                    new ChartDataModel("Japan",11.00,0.08),
                    new ChartDataModel("France",4.40,0.03),
                    new ChartDataModel("UK",4.30,0.03),
                    new ChartDataModel ("Canada",4.00,0.03),
                    new ChartDataModel("Germany",3.70,0.03),
                    new ChartDataModel("Italy",2.90,0.02),
                    new ChartDataModel("KY",2.70,0.02),
                    new ChartDataModel("Brazil",2.40,0.02),
                    new ChartDataModel("South Korea",2.20,0.02),
                    new ChartDataModel("Australia",2.20,0.02),
                    new ChartDataModel("Netherlands",1.90,0.01),
                    new ChartDataModel("Spain",1.90,0.01),
                    new ChartDataModel("India",1.30,0.01),
                    new ChartDataModel("Ireland",1.00,0.01),
                    new ChartDataModel("Mexico",1.00,0.01),
                    new ChartDataModel("Luxembourg",0.90,0.01),
                };

            PaletteBrushes = new ObservableCollection<Brush>()
                {
                new SolidColorBrush(Color.FromArgb("#314A6E")),
                    new SolidColorBrush(Color.FromArgb("#48988B")),
                    new SolidColorBrush(Color.FromArgb("#5E498C")),
                    new SolidColorBrush(Color.FromArgb("#74BD6F")),
                    new SolidColorBrush(Color.FromArgb("#597FCA"))
                };

            SelectionBrushes = new ObservableCollection<Brush>()
                {
                    new SolidColorBrush(Color.FromArgb("#40314A6E")),
                    new SolidColorBrush(Color.FromArgb("#4048988B")),
                    new SolidColorBrush(Color.FromArgb("#405E498C")),
                    new SolidColorBrush(Color.FromArgb("#4074BD6F")),
                    new SolidColorBrush(Color.FromArgb("#40597FCA"))
                };

            CustomColor2 = new ObservableCollection<Brush>()
                {
                    new SolidColorBrush(Color.FromArgb("#519085")),
                    new SolidColorBrush(Color.FromArgb("#F06C64")),
                    new SolidColorBrush(Color.FromArgb("#FDD056")),
                    new SolidColorBrush(Color.FromArgb("#81B589")),
                    new SolidColorBrush(Color.FromArgb("#88CED2"))
                };

            CustomColor1 = new ObservableCollection<Brush>()
                {
                    new SolidColorBrush(Color.FromArgb("#95DB9C")),
                    new SolidColorBrush(Color.FromArgb("#B95375")),
                    new SolidColorBrush(Color.FromArgb("#56BBAF")),
                    new SolidColorBrush(Color.FromArgb("#606D7F")),
                    new SolidColorBrush(Color.FromArgb("#E99941")),
                    new SolidColorBrush(Color.FromArgb("#327DBE")),
                    new SolidColorBrush(Color.FromArgb("#E7695A")),
                };

            AlterColor1 = new ObservableCollection<Brush>()
                {
                    new SolidColorBrush(Color.FromArgb("#346bf5")),
                    new SolidColorBrush(Color.FromArgb("#ff9d00")),
                };
        }
    }
    ```

1. The `EmbeddedViewModel` class is dependent on a `ChartDataModel` class which needs to be created. In `MauiEmbeddingApp.MauiControls` project, create a new folder called `Models` and add a new class called `ChartDataModel`. This class will have the following code:

    ```cs
    namespace MauiEmbeddingApp.MauiControls.Models;

    public class ChartDataModel
    {
        public string? Name { get; set; }
        public double Data { get; set; }
        public string? Label { get; set; }
        public DateTime Date { get; set; }
        public double Value { get; set; }
        public double Value1 { get; set; }
        public double Size { get; set; }
        public double High { get; set; }
        public double Low { get; set; }
        public bool IsSummary { get; set; }
        public string? Department { get; set; }
        public string? Image { get; set; }
        public List<double>? EmployeeAges { get; set; }
        public Brush? Color { get; set; }
        public double Percentage { get; set; }

        public ChartDataModel(string department, List<double> employeeAges)
        {
            Department = department;
            EmployeeAges = employeeAges;
        }

        public ChartDataModel(string name, double value)
        {
            Name = name;
            Value = value;
        }

        public ChartDataModel(string name, double value, Brush color, double percentage)
        {
            Name = name;
            Value = value;
            Color = color;
            Percentage = percentage;
        }

        public ChartDataModel(string name, double value, string image)
        {
            Name = name;
            Value = value;
            Image = image;
        }

        public ChartDataModel(string name, double value, double horizontalErrorValue, double verticalErrorValue)
        {
            Name = name;
            Value = value;
            High = horizontalErrorValue;
            Low = verticalErrorValue;
        }

        public ChartDataModel(string name, double value, double size)
        {
            Name = name;
            Value = value;
            Size = size;
        }

        public ChartDataModel()
        {

        }
        public ChartDataModel(DateTime date, double value, double size)
        {
            Date = date;
            Value = value;
            Size = size;
        }

        public ChartDataModel(double value, double value1, double size)
        {
            Value1 = value;
            Value = value1;
            Size = size;
        }

        public ChartDataModel(double value1, double value, double size, string label)
        {
            Value1 = value1;
            Value = value;
            Size = size;
            Label = label;
        }

        public ChartDataModel(string name, double high, double low, double open, double close)
        {
            Name = name;
            High = high;
            Low = low;
            Value = open;
            Size = close;
        }

        public ChartDataModel(double name, double high, double low, double open, double close)
        {
            Data = name;
            High = high;
            Low = low;
            Value = open;
            Size = close;
        }

        public ChartDataModel(DateTime date, double high, double low, double open, double close)
        {
            Date = date;
            High = high;
            Low = low;
            Value = open;
            Size = close;
        }
        public ChartDataModel(double value, double size)
        {
            Value = value;
            Size = size;
        }
        public ChartDataModel(DateTime dateTime, double value)
        {
            Date = dateTime;
            Value = value;
        }

        public ChartDataModel(string name, double value, bool isSummary)
        {
            Name = name;
            Value = value;
            IsSummary = isSummary;
        }
    }
    ```

1. The next step is to add the `EmbeddedViewModel` as the `DataContext` of the `SfCircularChart` in the `EmbeddedControl.xaml`:

    ```xml
    <?xml version="1.0" encoding="utf-8" ?>
    <ContentView x:Class="MauiEmbeddingApp.MauiControls.EmbeddedControl"
                ...
                >
        <chart:SfCircularChart x:Name="chart"
                            HorizontalOptions="Fill"
                            VerticalOptions="Fill">
            <chart:SfCircularChart.BindingContext>
                <local:EmbeddedViewModel x:Name="embeddedViewModel" />
            </chart:SfCircularChart.BindingContext>
            ...
    ```

1. Now the project is good to go! Press F5 and you should see the `SfCircularChart` control. Without specifying a license key, you'll see a prompt informing you that you're running the application using a trial version.

    > [!NOTE]
    > There is a known issue with the trial version prompt that can cause the application to crash on startup. If this is encountered running this sample, the `MainPage.xaml` can be updated to remove the `Source` property on the `MauiHost`. The `Source` property can then be set in the code behind file in an event handler for the `Loaded` event of the `Page`.

    ```cs
    namespace MauiEmbeddingApp;

    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.InitializeComponent();

            Loaded += MainPage_Loaded;
        }

        private void MainPage_Loaded(object sender, RoutedEventArgs e)
        {
            MauiHostElement.Source = typeof(EmbeddedControl);
        }
    }
    ```

## App Render Output

- **Android:**
  - ![Android Syncfusion](Assets/Screenshots/Android/Syncfusion.png)

- **Windows:**
  - ![Windows Syncfusion](Assets/Screenshots/Windows/Syncfusion.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.extensions/refs/heads/main/doc/Learn/Maui/ThirdParty-Telerik.md

---
uid: Uno.Extensions.Maui.ThirdParty.Telerik
---
# .NET MAUI Embedding - Telerik UI for .NET MAUI

The controls in the Telerik UI for .NET MAUI can be used in an Uno Platform application via .NET MAUI Embedding.

## Sample App

An existing sample app that showcases the controls is available [here](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/TelerikApp).

## Installation

In order to use the Telerik controls, you first need to create an account and order a license to use the controls. You can find more instructions [here](https://www.telerik.com/). Then follow the instructions to have access to the private NuGet feed.

## Getting Started

1. Create a new application using the `unoapp` template, enabling .NET MAUI Embedding. In this case, we're going to use the Blank template (`-preset blank`) and include .NET MAUI Embedding support (`-maui`).

    ```dotnetcli
    dotnet new unoapp -preset blank -maui -o MauiEmbeddingApp
    ```

1. Next, add a reference to the `Telerik.UI.for.Maui` NuGet package to the `MauiEmbeddingApp.MauiControls` project.

1. In the `AppBuilderExtensions` class, on `MauiEmbeddingApp.MauiControls` project, update the `UseMauiControls` extension method to call the `UseTelerik` method.

    ```cs
    using Telerik.Maui.Controls;
    using Telerik.Maui.Controls.Compatibility;

    namespace MauiEmbeddingApp;

    public static class AppBuilderExtensions
    {
        public static MauiAppBuilder UseMauiControls(this MauiAppBuilder builder)
            => builder
                .UseTelerik()
                .ConfigureFonts(fonts =>
                {
                    fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansRegular.ttf", "OpenSansRegular");
                    fonts.AddFont("MauiEmbeddingApp/Assets/Fonts/OpenSansSemibold.ttf", "OpenSansSemibold");
                });
    }
    ```

## Adding RadSignaturePad Control

1. Update the EmbeddedControl.xaml in the  `MauiEmbeddingApp.MauiControls` project with the following XAML that includes the `RadSignaturePad` control.

    ```xml
    <?xml version="1.0" encoding="utf-8" ?>
    <ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
                xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
                xmlns:telerik="http://schemas.telerik.com/2022/xaml/maui"
                x:Class="MauiEmbeddingApp.MauiControls.EmbeddedControl"
                HorizontalOptions="Fill"
                VerticalOptions="Fill">
            <telerik:RadSignaturePad x:Name="SignaturePad"
                                    HeightRequest="300"
                                    WidthRequest="300"
                                    BorderThickness="1"
                                    BorderColor="LightGray" />
    </ContentView>
    ```

1. Update the EmbeddedControl.xaml.cs with the following code.

    ```cs
    namespace MauiEmbeddingApp.MauiControls;

    public partial class EmbeddedControl : ContentView
    {
        public EmbeddedControl()
        {
            InitializeComponent();
        }
    }
    ```

1. Now the project is good to go! Press F5 and you should see the `RadSignaturePad` control working as expected.

## App Render Output

- **Android:**
  - ![Android Telerik](Assets/Screenshots/Android/Telerik.png)

- **Windows:**
  - ![Windows Telerik](Assets/Screenshots/Windows/Telerik.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/TimePicker.md

---
uid: Uno.Controls.TimePicker
---

# TimePicker

## Summary

`TimePicker` is used to select a specific time of the day in hour and minute (AM/PM).

Button showing time open the time picker popup.
Bind to the `Time` property of the control to set initial time.
days, seconds and milliseconds of input timespan are ignored
By default minute increment is set to 1
if you assign a negative value or 0, it will use 1 minute increment
if you assign a value over 30, it will use 30 minute increment
While all increments under 30 minutes are valid, we recommend using 1,2,5,10,15,20,25,30 minute increment.
If bound time is 2h03 and time increment is 5 than time picker initial pickable time will be 2h05
If bound time is 2h08 and time increment is 15 than time picker initial pickable time will be 2h15
Cancel button cancel the new time selection. You can also click outside the time picker to do the same.
Done/OK button save the new selected time.

## Managed vs. native implementation

On iOS and Android the `TimePicker` by default displays using the native time picker UI. If you prefer consistent UI across all targets, you can switch to the managed implementation by setting the `UseNativeStyle` property:

```xml
<TimePicker not_win:UseNativeStyle="False" ... />
```

To include the `not_win` XAML namespace on your page follow the instructions for [Platform-specific XAML](../platform-specific-xaml.md).

### Styles

Time button style: `TimePickerFlyoutButtonStyle`
Time picker flyout popup style: default generic `TimePickerFlyoutPresenterStyle`
`TimePickerSelector` is a platform specific wrapper for IOS/Android time pickers

### Device-specific implementation quirks

There might be differences in the time picker on different platform since it wraps platform specific ios/android time picker

#### Android

- Native time picker is wrapped in the flyout.
- `TimePicker` flyout appear centered to screen.
- You can change the flyout button by copying and modifying TimePickerFlyoutButtonStyle.
- You can change the flyout button by copying and modifying TimePickerFlyoutPresenterStyle.
- If 'MinuteIncrement` is more than 1, `TimePicker` will show in "spinner mode"
- In case clock mode still appear for some reason picked value will be rounded to minute increment intervals..

#### iOS

- Native time picker is wrapped in the flyout.
- Set 'ios:FlyoutPlacement' property to change flyout docking placement
- Default 'ios:FlyoutPlacement' is 'Full' and will dock of the flyout at the bottom of the screen
- You can change the flyout button by copying and modifying TimePickerFlyoutButtonStyle.
- You can change the flyout button by copying and modifying TimePickerFlyoutPresenterStyle.

Some `ColorBrushes` are specific to **iOS** and could be changed by copying and redoing the new style so they use your own color brushes:

```resources
IOSTimePickerAcceptButtonForegroundBrush  Color="#055bb7"
IOSTimePickerDismissButtonForegroundBrush  Color="#055bb7"
IOSTimePickerHeaderBackgroundBrush  Color="{ThemeResource SystemListLowColor}"
```

If you want to show a dimmed overlay underneath the picker, set the `TimePicker.LightDismissOverlayMode` property to `On`.

If you wish to customize the overlay color, add the following to your top-level `App.Resources`:

```xml
<SolidColorBrush x:Key="TimePickerLightDismissOverlayBackground"
                 Color="Pink" />
```

Since **iOS14** the native `TimePicker` changed the way it's presented. By default iOS14 devices will display this new style.  You can still force the previous style (the one found in iOS13 or earlier) by adding the following at your `App.cs` or `App.xaml.cs` class:

```csharp
Uno.UI.FeatureConfiguration.TimePicker.UseLegacyStyle = true;
```

> [!IMPORTANT]
> This feature flag is required and will only affect iOS 14 devices. As of **iOS 15**, the preferred style for the DatePicker is again the one found in iOS13 and earlier.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/ToggleSwitch.md

---
uid: Uno.Controls.ToggleSwitch
---

# ToggleSwitch in Uno Platform

`ToggleSwitch` represents a switch that can be toggled between two states.

## ToggleSwitch WinUI Default Style

Uno provides a full support of the ToggleSwitch WinUI style.
The ToggleSwitch with the default style looks the same on all platforms, both statically and in motion.
If you need to have a custom design, you can just update the ToggleSwitch WinUI default style for your needs.

## ToggleSwitch Native Default Style

With the `NativeDefaultToggleSwitch` style on Android and iOS, the ToggleSwitch uses the native toggle control of each platform.
Of course, you can still bind to its properties in XAML as you normally would.
This is another powerful option to have: for some apps it makes sense to look as 'native' as possible, for others its desirable to have a rich, customized UI.
You may even want to mix and match different approaches for different screens in your app.

### Native Android ToggleSwitch

The Native Style for ToggleSwitch on Android is based on `SwitchCompat`, a Material Design version of the Switch widget supported by API 7 and above.
It does not make any attempt to use the platform provided widget on those devices which it is available normally.
This ensures the same behavior on all system versions.

#### Platform support

| Property             | `BindableSwitchCompat` |
|----------------------|:----------------------:|
| Checked              |           X            |
| Enabled              |           X            |
| Text                 |           X            |
| TextColor            |           X            |
| TextOff              |                        |
| TextOn               |                        |
| ShowText             |                        |
| SplitTrack           |                        |
| SwitchMinWidth       |                        |
| SwitchPadding        |                        |
| SwitchTextAppearance |                        |
| Thumb                |                        |
| ThumbTextPadding     |                        |
| ThumbTint            |           X            |
| ThumbTintMode        |                        |
| Track                |                        |
| TrackTint            |           X            |
| TrackTintMode        |                        |

#### Native Android ToggleSwitch Style

If you need the simple native style :

```xml
    <android:Style x:Key="NativeDefaultToggleSwitch"
                   TargetType="ToggleSwitch">
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="ToggleSwitch">
                    <BindableSwitchCompat Checked="{TemplateBinding IsOn, Mode=TwoWay}"
                                          Enabled="{TemplateBinding IsEnabled}"
                                          Text="{TemplateBinding Header}" />
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </android:Style>
```

If you need the native style but you want to change the Text, ThumbTint and TrackTint colors:

```xml
    <android:Style x:Key="NativeDefaultToggleSwitch"
                   TargetType="ToggleSwitch">
        <Setter Property="Template">
            <Setter.Value>
                <ControlTemplate TargetType="ToggleSwitch">
                    <BindableSwitchCompat Checked="{TemplateBinding IsOn, Mode=TwoWay}"
                                          Enabled="{TemplateBinding IsEnabled}"
                                          Text="{TemplateBinding Header}"
                                          TextColor="{TemplateBinding Foreground}"
                                          ThumbTint="{TemplateBinding BorderBrush}"
                                          TrackTint="{TemplateBinding Background}" />
                </ControlTemplate>
            </Setter.Value>
        </Setter>
    </android:Style>
```

### Native iOS ToggleSwitch

Based on the UISwitch.

#### Platform support

| Property                                   | BindableUISwitch |
| ------------------------------------------ |:----------------:|
| IsOn                                       |         X        |
| Enabled                                    |         X        |
| OnTintColorBrush                           |         X        |
| TintColorBrush                             |         X        |
| ThumbTintColorBrush                        |         X        |
| OnImage                                    |                  |
| OffImage                                   |                  |

#### Native iOS ToggleSwitch Style

If you need the simple native style:

```xml
<ios:Style x:Key="NativeDefaultToggleSwitch"
           TargetType="ToggleSwitch">
    <!-- Ensures the UISwitch's shadow doesn't get clipped. -->
    <Setter Property="ClipsToBounds"
            Value="False" />
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="ToggleSwitch">
                <BindableUISwitch IsOn="{TemplateBinding IsOn, Mode=TwoWay}"
                                  Enabled="{TemplateBinding IsEnabled}" />
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</ios:Style>
```

If you need the native style but you want to change the Tint, OnTinT and ThumbTint colors:

```xml
<ios:Style x:Key="NativeDefaultToggleSwitch"
            TargetType="ToggleSwitch">
    <!-- Ensures the UISwitch's shadow doesn't get clipped. -->
    <Setter Property="ClipsToBounds"
            Value="False" />
    <Setter Property="Template">
        <Setter.Value>
            <ControlTemplate TargetType="ToggleSwitch">
                <BindableUISwitch IsOn="{TemplateBinding IsOn, Mode=TwoWay}"
                                  Enabled="{TemplateBinding IsEnabled}"
                                  TintColorBrush="{TemplateBinding BorderBrush}"
                                  OnTintColorBrush="{TemplateBinding Background}"
                                  ThumbTintColorBrush="{TemplateBinding Foreground}" />
            </ControlTemplate>
        </Setter.Value>
    </Setter>
</ios:Style>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/Uno-UI-Debugging-Android-Studio.md

---
uid: Uno.Contributing.AndroidStudio
---

# Debugging Uno.UI Java code with Android studio

Not all of Uno.UI is written in C#. On Android, certain low-level parts of the code is written in Java, including the UnoViewGroup class, from which UIElement (and hence most other views) inherit. The motivation for this is performance: the communication or 'interop' between C# and Java layers at runtime can, in very specific cases, have a measurable performance impact.

The vast majority of the time, development in Uno.UI should be done in C#. However, for debugging existing Java code, or when performance testing demonstrates a need to write new Java code, this document explains how to debug the code using Android Studio, similar to using Visual Studio to debug .NET code.

## Getting started

* Install the latest version of [Android Studio](https://developer.android.com/studio/index.html).
* Launch Android Studio and create a blank Android project.
* Open the build.gradle file located in the 'app' folder. (Note there are two build.gradle files.)
* Add the following lines to the build file:

  ```gradle
  sourceSets {
          main.java.srcDirs += 'C:/<Your Uno repository>/Uno.UI.BindingHelper.Android/Uno/UI'
      }
  ```

  ![gradle](assets/debugging-android-studio/Gradle-changes.png)

* Press 'Sync Now' to update the project.
* You should now see Uno.UI files in the Project tab. (Don't worry about red squiggles.)

  ![Project-files](assets/debugging-android-studio/Project-files.png)

## Debugging

* Run the app you wish to debug, which should be using a local debug build of Uno.UI.
* In Android Studio, select Run->Attach debugger to Android process. Select your app. (Toggle on 'Show all processes' if it's not visible.)

  ![Attach-to-process](assets/debugging-android-studio/Attach-to-process.png)

* You should now be able to debug and place breakpoints in Uno.UI code.
* Android Studio supports a similar feature set to Visual Studio. Here are some of the basics:
  * Breakpoints: Ctrl-F8 places a breakpoint. You can step over (F8) and step into (F7) code.
  * Inspect values of local variables and fields.
  * Add 'watch' values.
  * Add conditions and logging to breakpoints.

  ![Debugging](assets/debugging-android-studio/Debugging.png)

* One powerful feature of debugging Android code is the level of integration with framework code. You should be able to see not only the native stack trace, but even local variable values in framework methods (e.g. ViewGroup.dispatchTouchEvent().)
  * Note that Android Studio may prompt you to download source code and debug symbols: this will fail unless you started Android Studio with Administrator privileges (right-click in Start menu + 'Run as Administrator').

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/Uno-UI-Layouting-Android.md

---
uid: Uno.Contributing.LayoutingAndroid
---

# Layouting in Android

The layouting cycle (measure and arrange) in Uno on Android involves a complex interaction between Android UI framework methods and Uno
methods. These interactions are summarized in the diagram below. This information is primarily intended to help when debugging Uno, but
may be interesting to anyone curious as to how native Android methods are connected to the WinUI contract exposed by Uno.

```mermaid
flowchart TD
    %% Android layout flow

    subgraph Measure Invalidation
        uielement.invalidatearrange["UIElement.InvalidateArrange()"]
        uielement.invalidatemeasure["UIElement.InvalidateMeasure()"]
        base.requestlayout{{"View.RequestLayout()"}}
        root.requestlayout{{"ViewRootImpl.RequestLayout()"}}
        root.scheduletraversal{{"ViewRootImpl.ScheduleTraversals()"}}

        uielement.invalidatearrange -. "actually calls" .-> uielement.invalidatemeasure
        uielement.invalidatemeasure == set IS_DIRTY ==> base.requestlayout
        uielement.invalidatemeasure -. parent: set IS_DIRTY_PATH .-> uielement.invalidatemeasure

        base.requestlayout -. internally on parent .-> base.requestlayout
        base.requestlayout ==> root.requestlayout
        root.requestlayout ==> root.scheduletraversal
    end

    root.scheduletraversal -. on next animation loop .-> loop

    subgraph loop["UI Loop Scheduling"]
        root.performtraversal{{"ViewRootImpl.PerformTraversal()"}}

        root.performtraversal ==> root.performmeasure
        root.performtraversal ==> root.performlayout

        subgraph Measure Phase
            root.performmeasure{{"ViewRootImpl.PerformMeasure()"}}
            view.measure{{"View.Measure()"}}
            view.onmeasure{{"View.OnMeasure()"}}

            onmeasure["(override) FrameworkElement.OnMeasure()"]
            layouter.domeasure["ILayouterElement.DoMeasure()"]
            layouter.measureoverride["Layouter.MeasureOverride()"]
            measureoverride[["(override) Element.MeasureOverride()"]]

            measureelement["FrameworkElement.MeasureElement()"]
            layouter.measurechild["Layouter.MeasureChild()"]
            layouter.measurechildoverride["Layouter.MeasureChildOverride()"]
            view.setmeasureddimension{{"View.SetMeasuredDimension()"}}
            view.layout{{"View.Layout()"}}

            root.performmeasure == top-level element ==> view.measure
            view.measure ==> view.onmeasure

            view.onmeasure ==> onmeasure
            onmeasure ==> layouter.domeasure
            layouter.domeasure == IS_DIRTY set ==> layouter.measureoverride
            layouter.domeasure == "IS_DIRTY_PATH set:<br>call for children<br>with previous availableSize" ==> layouter.measurechild

            layouter.measureoverride ==> measureoverride
            measureoverride == "for children (generally)" ==> measureelement
            measureelement ==> layouter.measurechild

            layouter.measurechild ==> layouter.measurechildoverride
            layouter.measurechildoverride ==> view.layout
            layouter.measurechildoverride -. "(return value will set)" .-> view.setmeasureddimension
            view.layout ==> view.measure
        end

        view.layout -..-> arrange

        subgraph arrange ["Arrange Phase"]
            root.performlayout{{"View.PerformLayout()"}}
            view.onlayout{{"View.OnLayout()"}}
            unoviewgroup.onlayoutcore["UnoViewGroup.OnLayoutCore() - abstract"]
            onlayoutcore["(override) FrameworkElement.OnLayoutCore()"]
            layouter.arrange["Layouter.Arrange()"]
            layouter.arrangeoverride["Layouter.ArrangeOverride()"]
            arrangeoverride[["Element.ArrangeOverride()"]]
            arrangeelement["FrameworkElement.ArrangeElement(child)"]
            layouter.arrangechild["Layouter.ArrangeChild()"]
            layouter.arrangechildoverride["Layouter.ArrangeChildOverride()"]

            root.performlayout == x ==> view.onlayout
            view.onlayout == "through OnLayout() override" ==> unoviewgroup.onlayoutcore
            unoviewgroup.onlayoutcore ==> onlayoutcore
            onlayoutcore ==> layouter.arrange
            layouter.arrange ==> layouter.arrangeoverride
            layouter.arrangeoverride ==> arrangeoverride
            arrangeoverride == " for children (generally) " ==> arrangeelement
            arrangeelement ==> layouter.arrangechild
            layouter.arrangechild ==> layouter.arrangechildoverride
            layouter.arrangechildoverride -..-> view.onlayout
        end
    end

    subgraph legend
    direction LR
    uno-legend["Uno methods"]
    native-legend{{"Native (Android) methods"}}
    application-legend[["Application/Framework implementation"]]
    end
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/Uno-UI-Layouting-iOS.md

---
uid: Uno.Contributing.LayoutingiOS
---

# Layouting in iOS

The layouting cycle (measure and arrange) in Uno on iOS is a mingling of native layouting logic and logic in managed code. These interactions are summarized in the diagram below. This information is primarily intended to help when debugging Uno, but may also be useful when attempting to incorporate non-Uno views into the visual tree.

```mermaid
flowchart TD
  %% ios layout flow

  basesetneedslayout{{"base.SetNeedsLayout()"}}
  layoutsublayers{{"CALayer.LayoutSublayers"}}
  layoutsubviews["(override) FrameworkElement.LayoutSubviews()"]

  subgraph Measure Invalidation
    invalidate-arrange["UIElement.InvalidateArrange()"]
    invalidate-measure["IFrameworkElementHelper.InvalidateMeasure()"]
    setneedslayout["(override) FrameworkElement.SetNeedsLayout()"]
    setsuperviewneedslayout["FrameworkElement.SetSuperviewNeedsLayout()"]

    native.sizethatfits{{".SizeThatFits() called from parent element"}}

    invalidate-arrange ==> invalidate-measure
    invalidate-measure ==> setneedslayout

    setneedslayout --> setsuperviewneedslayout
    setsuperviewneedslayout -. on parent element.-> setneedslayout

    setneedslayout ==> basesetneedslayout
  end

  subgraph Measure Phase
    sizethatfits["(override) FrameworkElement.SizeThatFits(availableSize)"]
    xamlmeasure["FrameworkElement.XamlMeasure(availableSize)"]
    layouter.measure["Layouter.Measure(availableSize)"]
    layouter.measureoverride["Layouter.MeasureOverride(availableSize)"]
    measureoverride["FrameworkELement.MeasureOverride(availableSize)<br><em>overridden by element</em>"]
    appmeasureoverrride[["local implementation of MeasureOverride(availableSize)<br>"]]

    subgraph Subelement measuring
      measureelement["FrameworkElement.MeasureElement(child)"]
      layouter.measureelement["Layouter.MeasureElement(child)"]
      measurechildoverride["Layouter.MeasureChildOverride"]

      measureelement ==> layouter.measureelement
      layouter.measureelement ==> measurechildoverride
    end

    sizethatfits ==> xamlmeasure
    xamlmeasure ==> layouter.measure
    layouter.measure ==> layouter.measureoverride
    layoutsubviews ==> xamlmeasure
    layouter.measureoverride ==> measureoverride
    measureoverride ==> appmeasureoverrride
    appmeasureoverrride -- for child elements --> measureelement
  end

  basesetneedslayout -. "schedule for next loop (native)" .-> layoutsublayers
  layoutsublayers ==> layoutsubviews
  native.sizethatfits ==> sizethatfits
  measurechildoverride ==> sizethatfits

  frame -. "internal scheduling for next loop (native)" .-> layoutsublayers

  subgraph Arrange Phase
    layouter.arrange["Layouter.Arrange(finalRect)"]
    arrangeoverride["FrameworkElement.ArrangeOverride(finalSize)"]
    frame{{".Frame property set"}}

    subgraph for child elements
      arrangeelement["Framework.ArrangeElement(child)"]
      layouter.arrangeelement
      app.arrangeoverride[["(override) ArrangeOverride(finalSize)"]]

      layouter.arrangechild
      layouter.arrangechildoverride
    end

    layouter.arrange ==> arrangeoverride
    arrangeoverride ==> app.arrangeoverride
    app.arrangeoverride ==> arrangeelement

    arrangeelement ==> layouter.arrangeelement
    layouter.arrangeelement ==> layouter.arrangechild
    layouter.arrangechild ==> layouter.arrangechildoverride

    layouter.arrangechildoverride ==> frame

    layoutsubviews ==> layouter.arrange
  end

  subgraph legend
    direction LR
    uno-legend["Uno methods"]
    native-legend{{"Native (iOS) methods"}}
    application-legend[["Application/Framework implementation"]]
  end
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/Uno-UI-Performance.md

---
uid: Uno.Development.Performance
---

# Uno.UI - Performance

This article lists various performance tips to optimize your Uno Platform application.

Here's what to look for:

- Make sure to choose the right renderer ([Skia](xref:uno.features.renderer.skia) or [Native](xref:uno.features.renderer.native)) for your application, depending on the feature set you'll be using.
- Make sure to always have the simplest visual tree. There's nothing faster than something you don't draw.
- Reduce panels in panels depth. Use Grids and relative panels where possible.
- Force the size of images anywhere possible, using explicit `Width` and `Height` properties.
- `Collapsed` elements are not considered when measuring and arranging the visual tree, which makes them almost costless. Consider `x:Load` below for further optimizations.
- When binding or animating (via `VisualState.Setters`) the `Visibility` property, make sure to enable lazy loading:
 `x:Load="False"`.
- Use `x:Load={x:Bind MyVisibility}` where appropriate as toggling from `true` to `false` effectively removes a part of the visual tree from memory. Note that setting back to true re-creates the visual tree.
- `ListView` and `GridView`
  - Don't use template selectors inside the ItemTemplate, prefer using the `ItemTemplateSelector` on `ListView`/`GridView`.
  - The default [`ListViewItem` and `GridViewItem` styles](https://github.com/unoplatform/uno/blob/74b7d5d0e953fcdd94223f32f51665af7ce15c60/src/Uno.UI/UI/Xaml/Style/Generic/Generic.xaml#L951) are very feature-rich, yet that makes them quite slow. For instance, if you know that you're not likely to use selection features for a specific ListView, create a simpler ListViewItem style that some visual states, or the elements that are only used for selection.
  - If items content frequently change (e.g. live data in TextBlock) on iOS and Android, ListView items rendering can require the use of the `not_win:AreDimensionsConstrained="True"` [uno-specific property](https://github.com/unoplatform/uno/blob/7355d66f77777b57c660133d5ec011caaa810e29/src/Uno.UI/UI/Xaml/FrameworkElement.cs#L86).
  
    This attribute prevents items in a list from requesting their parent to be re-measured when their properties change. It's safe to use the `AreDimensionsConstrained` property when items always have the same size regardless of bound data, and the items and list are stretched in the non-scrolling direction. If item sizes can change when the bound data changes (eg, if they contain bound text that can wrap over multiple lines, images of undetermined size, etc), or if the list is wrapped to the items, then you shouldn't set `AreDimensionsConstrained` because the list does need to remeasure itself when item data changes in that case.

    You'll need to set the property on the top-level element of your item templates, as follows:

      ```xml
      <ResourceDictionary xmlns:xamarin="http://uno.ui/xamarin" mc:Ignorable="d xamarin" ...>
      <DataTemplate x:Key="MyTemplate">
        <Grid Height="44" not_win:AreDimensionsConstrained="True">
        ...
        </Grid>
      </DataTemplate>
      ```

    Note that WinUI does not need this, and the issue is [tracked in Uno here](https://github.com/unoplatform/uno/issues/6910).
  - Avoid controls that contain inline popups, menus, or flyouts. Doing so will create as many popups as there are items visible on the screen. As in general, there is only one popup visible at a time, it is generally best to move the popup to a separate static resource.

- Updating items in `ItemsControl` can be quite expensive, using `ItemsRepeater` is generally faster at rendering similar content.
- Animations
  - Prefer `Opacity` animations to `Visibility` animations (this avoids some measuring performance issues).
    - Unless the visual tree of the element is very big, where in this case `Visibility` is better suited.
  - Prefer Storyboard setters to `ObjectAnimationUsingKeyFrames` if there is only one key frame.
  - Prefer changing the properties of a visual element instead of switching opacity or visibility of an element.
    - Manually created `Storyboard` instances do not stop automatically. Make sure that if you invoke `Storyboard.Begin()`, invoke `Storyboard.Stop()` when the animated content is unloaded, otherwise resources may be spent animating invisible content.
    - `ProgressRing` and `ProgressBar` controls indeterminate mode generally consume rendering time. Make sure to set those to determinate modes when not visible.
    - Troubleshooting of animations can be done by enabling the following logger:

      ```csharp
      builder.AddFilter("Windows.UI.Xaml.Media.Animation", LogLevel.Debug);
      builder.AddFilter("Microsoft.UI.Xaml.Media.Animation", LogLevel.Debug);
      ```

      The logger will provide all the changes done to animated properties, with element names.

- Image Assets
  - Try using an image that is appropriate for the DPI and screen size.
  - Whenever possible, specify and explicit Width and Height on `Image`.
  - The pixel size of an image will impact the loading time of the image. If the image is intentionally blurry, prefer reducing the physical size of the image over
   the compressed disk size of the image.
- Paths
  - Prefer reusing paths, duplication costs Main and GPU memory.
  - Prefer using custom fonts over paths where possible. Fonts are rendered extremely fast and have a very low initialization time.
- Bindings
  - Using `x:Bind` is generally faster as it involves less or no reflection.
  - Prefer bindings with short paths.
  - To shorten paths, use the `DataContext` property on containers, such as `StackPanel` or `Grid`.
  - Adding a control to loaded `Panel` or `ContentControl` does propagate the parent's DataContext immediately. If the new control has its `DataContext` immediately overridden to something else, ensure to set the DataContext before adding the control to its parent. This will avoid having bindings be refreshed twice needlessly.
  - Add the `Windows.UI.Xaml.BindableAttribute` or `System.ComponentModel.BindableAttribute` on non-DependencyObject classes.
    - When data binding to classes not inheriting from `DependencyObject`, in Debug configuration only, the following message may appear:

      ```console
      The Bindable attribute is missing and the type [XXXX] is not known by the MetadataProvider.
      Reflection was used instead of the binding engine and generated static metadata. Add the Bindable  attribute to prevent this message and performance issues.
      ```

      This message indicates that the binding engine will fall back on reflection based code, which is generally slow. To compensate for this, Uno use the `BindableTypeProvidersSourceGenerator`, which generates static non-generic code to avoid reflection operations during binding operations.
      This attribute is inherited and is generally used on ViewModel based classes.
- [`x:Phase`](https://learn.microsoft.com/windows/uwp/xaml-platform/x-phase-attribute)
  - For `ListView` instances with large templates, consider the use of x:Phase to reduce the number of bindings processed during item materialization.
  - It is only supported for items inside `ListViewItem` templates, it will be ignored for others.
  - It is also supported as `not_win:Phase` on controls that do not have bindings. This feature is not supported by WinUI.
  - It is only supported for elements under the `DataTemplate` of a `ListViewItem`. The
 attribute is ignored for templates of `ContentControl` instances, or any other control.
  - When binding to Brushes with a solid color, prefer binding to the `Color` property like this if the brush type does not change:

      ```xml
      <TextBlock Text="My Text">
          <TextBlock.Foreground>
              <SolidColorBrush Color="{x:Bind Color, Mode=OneWay, FallbackValue=Red}" />
          </TextBlock.Foreground>
      </TextBlock>
      ```

- Resources
  - Avoid using `x:Name` in `ResourceDictionary` as those force early instantiation of the resource
  - Use [`Uno.XamlMerge.Task`](https://github.com/unoplatform/uno.xamlmerge.task) to merge all top-level `App.xaml` resource dictionaries

## WebAssembly specifics

- Building your application in **Release** configuration is critical to get the best performance.
- Make sure to use the latest stable release of [Uno.Wasm.Bootstrap packages](https://www.nuget.org/packages/Uno.Wasm.Bootstrap)
- Enable [AOT or PG-AOT](xref:Uno.Wasm.Bootstrap.Runtime.Execution) to get the best performance.
- Consider enabling the [`Jiterpreter`](xref:Uno.Wasm.Bootstrap.Runtime.Execution#jiterpreter-mode) mode for faster performance.
- When [recording a PG-AOT profile](xref:Uno.Wasm.Bootstrap.Runtime.Execution#profile-guided-aot), make sure to run through most of your application before saving the profile.
- Adjusting the GC configuration may be useful to limit the collection runs on large allocations. Add the following to your `csproj` file:

    ```xml
    <ItemGroup>
      <WasmShellMonoEnvironment Include="MONO_GC_PARAMS" Value="soft-heap-limit=512m,nursery-size=64m,evacuation-threshold=66,major=marksweep" />
    </ItemGroup>
    ```

  You can adjust the `nursery-size` and `soft-heap-limit` based on your application's memory consumption characteristics. See the [.NET GC configuration](https://learn.microsoft.com/xamarin/android/internals/garbage-collection#configuration) for more details.

- The size of the application can be reduced by:

  - Enabling the [IL Linker](features/using-il-linker-webassembly.md)
  - Enabling [XAML Resources Trimming](features/resources-trimming.md)

## Android specifics

- Adjust the [GC configuration](https://learn.microsoft.com/xamarin/android/internals/garbage-collection#configuration) by modifying the `environment.conf` file with parameters matching your application
- Enable `LLVM` in `Release` with `-p:EnableLLVM=true` for better runtime performance at the expense of package size and longer compilation times
- Enable `Marshal Methods` in `Release` with `-p:AndroidEnableMarshalMethods=true` to improve startup performance (.NET 8 +)
- [Enable Startup Tracing](https://devblogs.microsoft.com/dotnet/performance-improvements-in-dotnet-maui/#record-a-custom-aot-profile) by running the following:

    ```bash
    dotnet add package Mono.AotProfiler.Android
    dotnet build -t:BuildAndStartAotProfiling
    # Wait until the app launches, then navigate around the most common screens
    dotnet build -t:FinishAotProfiling
    ```

  This will produce a `custom.aprof` in your project directory. Move the file to the `Android` folder and add the following to your `csproj`:

    ```xml
    <ItemGroup>
      <AndroidAotProfile Include="Android/custom.aprof" />
    </ItemGroup>
    ```

- Enable `Full AOT` instead of `Startup Tracing` in `Release` with `-p:AndroidEnableProfiledAot=false` to get the best runtime performance

  This will make your package size **significantly** larger and your compilation times longer.

  You may combine this with `-p:EnableLLVM=true` and `-p:AndroidEnableMarshalMethods=true` to get even better performance.

- Use [String Resource Trimming](xref:Uno.Features.StringResourceTrimming) to improve package size and startup time

## iOS Native Renderer Specifics

On iOS with the native renderer enabled, memory leaks can happen very frequently when using cross-references on UIElement instances. Some high level analysis can be done using [this C# analyzer](https://github.com/jonathanpeppers/memory-analyzers), to determine obvious patterns that cause memory leaks.

You'll find below other known memory leak patterns on iOS Native:

- `VisualStateManager` must be set on the root element of a XAML file. Placing it on any other control will cause a native controls leak.

## Skia Targets Specifics

- On Desktop targets, it's possible to change the composition refresh rate using `FeatureConfiguration.CompositionTarget.FrameRate`. The default value is 60 (frames per second).
- On all targets:
  - It's possible to set `DebugSettings.EnableFrameRateCounter` in `App.OnLaunched` in order to view a top-left indicator. It indicates the current frames per second, as well as the time spent rendering a composition frame, in milliseconds.
  - If the indicator does not change, this means that the UI is not refreshing.
  - If it is, but nothing is changing visually, it could be that a XAML or Composition animation is still running, see the `ProgressRing` section in this document.
- Avoid the use of SkiaSharp's `SKXamlCanvas`, instead use [`SKCanvasElement`](xref:Uno.Controls.SKCanvasElement) which is hardware accelerated.

## Advanced performance Tracing

### Profiling applications

A profiling guide for Uno Platform apps is [available here](xref:Uno.Tutorials.ProfilingApplications).

### FrameworkTemplatePool

The framework template pool manages the pooling of ControlTemplates and DataTemplates, and in most cases, the recycling of controls should be high.

- `CreateTemplate` is raised when a new instance of a template is created. This is an expensive operation that should be performed as rarely as possible.
- `RecycleTemplate` is raised when an active instance of a template is placed into the pool. This should happen often.
- `ReuseTemplate` is raised when a pooled template is provided to a control asking for a specific data template.
- `ReleaseTemplate` is raised when a pooled template instance has not been used for a while.

If the `ReuseTemplate` occurrences is low, this usually means that there is a memory leak to investigate.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/Uno-UI-XAML-ResourceTrimming.md

---
uid: Uno.Contributing.XamlResourceTrimming
---

# XAML Resource Trimming

This document provides technical details about the [XAML Resource trimming phase](../features/resources-trimming.md).

## Technical Details

In Uno, XAML is generating C# code in order to speed up the creation of the UI. This allows for compile-time optimizations, such as type conversions or `x:Bind` integration.

The drawback of this approach is that code may be bundled with an app even if it's not used. In common use cases, the IL Linker is able to remove code not referenced, but in the case of XAML resources, this code is conditionally referenced through string cases only. This makes it impossible for the linker to remove that code through out-of-the-box means.

In order to determine what is actually used by the application, the Uno Platform tooling runs a sequence of IL Linker passes and substitutions.

In order to prepare the linking pass:

- The tooling determines the presence of the `UnoXamlResourcesTrimming` msbuild property
- During the source generation, the tooling generates a `__LinkerHints` class, which contains a set of properties for all `DependencyObject` inheriting classes.
- The source generation creates XAML Resources and Bindable Metadata code that conditionally uses those classes behind `LinkerHints` properties.
- The tooling also embeds an ILLinker substitution file allowing the linker to unconditionally remove the code that conditionally references those properties. For instance, for `LinkerHints.Is_Windows_UI_Xaml_Controls_Border_Available`, any block of `if (LinkerHints.Is_Windows_UI_Xaml_Controls_Border_Available)` will be removed when the `--feature Is_Windows_UI_Xaml_Controls_Border_Available false` parameter is provided to the linker.

Then the multiple passes of IL Linker are done:

- The first pass runs the IL Linker with all XAML resources and Binding Metadata disabled by setting all `__LinkerHints` properties to false. This removes all code directly associated to those Bindable Metadata and XAML Resources. This has the effect of only keeping framework code which is directly referenced from user code.
- The tooling then reads the result of the linker to determine which types in the `LinkerHints` are still available in the assemblies.
- The subsequent passes run the IL Linker with `__LinkerHints` enabled only for types detected to be used during the first pass. This will enable types indirectly referenced by XAML Resources (e.g. a ScrollBar inside a ScrollViewer style) to be kept by the linker.
- The tooling then reads again the result of the linker to determine which types in the `__LinkerHints` are still available in the assemblies.
- The tooling re-runs this last pass until the available types list stops changing.

The resulting `__LinkerHints` types are now passed as features to the final linker pass (the one bundled with the .NET tooling) to generate the final binary, containing only the used types.

As of Uno 3.9, the Uno.UI WebAssembly assembly is 7.5MB, trimmed down to 3.1MB for a `dotnet new unoapp` template.

## Using the `AdditionalLinkerHintAttribute` attribute

In some scenarios (e.g. ExpandoObject), it may be needed to generate linker hints for non-DependencyObject types.

To get a `__LinkerHints` property for an additional type, add the following in AssemblyInfo.cs:

```csharp
[assembly: AdditionalLinkerHint("System.Dynamic.ExpandoObject")]
```

Then make the code using `ExpandoObject` conditional:

```csharp
if (__LinkerHints.Is_System_Dynamic_ExpandoObject_Available
 && type == typeof(System.Dynamic.ExpandoObject))
{
    ...
}
```

The linker will automatically remove the rest of the conditional block if the linker hint is considered false, based on the use of `ExpandoObject` in the rest of the app (except the current assembly).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/Uno-UI-xBind-architecture.md

---
uid: Uno.Contributing.xBind
---

# x:Bind in Uno Platform

## Overview of the x:Bind feature in WinUI

> Note that this section is based on observations of the behavior of `x:Bind`

`x:Bind` markup extensions have originally been developed by Microsoft to provide enhanced Data Binding performance, where no reflection is needed to do so. Code is generated along with XAML files that contain controls and DataTemplates, in `.g.cs` and `.g.i.cs` files.

Those bindings differ in multiple ways with standard `Binding` markup:

- The default binding mode is `OneTime` (`OneWay` for `Binding`)
- For top level controls the data context is the control itself
- For `DataTemplate`, the data context is the `DataContext` of the root element
- They can reference static fields and properties
- They can accept member and static functions with multiple parameters
- Function parameters can be string or number literals, as well as `x:True`, `x:False` and `x:Null`
- Function parameters can be the update source of the whole function binding

The creation of that generated code is performed in two passes:

- The first pass where x:Bind markup is removed from an intermediate file, creating unique "connections"
- The second pass creates a set of classes and interfaces within the top level class, or a hidden class for Data Templates.

The generated code is accessible through a private member called `Bindings`, which offers the following interface:

```csharp
private interface IXBindUserControl_Bindings
{
    void Initialize();
    void Update();
    void StopTracking();
}
```

The most commonly used member is `Update` which allows to refresh a `OneTime` binding to a newer value.

## Implementation in Uno Platform

Uno is interpreting the XAML in a very different way, when compared to WinUI. Uno generates code at compile for most of the document, not just for the bindings, where WinUI generates code for `x:Bind` and XBF for the rest of the XAML.

In order to obtain a sufficiently close implementation of `x:Bind` the first iteration in Uno was only relying on the `Binding` engine to perform bindings. The only difference was in the default DataContext used by the resulting `Binding` object (`this` for `x:Bind`, the `DataContext` property for `DataTemplate`).

However, in order to implement the functions portions of `x:Bind`, more code needed to be generated. To the ability to observe changes on multiple source paths, in both `INotifyPropertyChanged` types, as well as `DependencyProperty` instances, runtime reflection or `TypeMetadataProvider` based path observation is used.

When encountering an `x:Bind` markup, the Uno generator parses the expression to generate a C# compatible expression, then extracts the "update sources". At this point, code is generated to invoke Uno specific APIs `Uno.UI.Xaml.BindingHelper.SetBindingXBindProvider` that add more information to the `Binding` class with properties paths, the binding source, and the function to execute when the target property needs to be updated.

For a typical OneTime `x:Bind` implementation:

```xml
<TextBlock Text="{x:Bind TypeProperty.Value, FallbackValue=42}" />
```

The code is similar to this:

```csharp
c18.SetBinding(
    global::Windows.UI.Xaml.Controls.TextBlock.TextProperty, 
    new Windows.UI.Xaml.Data.Binding{ 
        Mode = global::Windows.UI.Xaml.Data.BindingMode.OneWay,
    }
    .Apply(___b => 
        global::Uno.UI.Xaml.BindingHelper.SetBindingXBindProvider(
            ___b, // The binding to update
            this, // The DataContext
            ___ctx => Add(InstanceDP, MyxBindClassInstance.MyIntProperty), // the code to execute
            new [] {"InstanceDP", "MyxBindClassInstance.MyIntProperty"} // The properties to observe
        )
    )
);
```

At this point of the implementation, the executed expression is not yet decomposed to provide finer support for `FallbackValue`, where any member of an observed path may be null, and generate a NullReferenceException. A more advanced implementation will do so and stop the evaluation when a path member is null. In any case, the fallback value is applied if an exception occurs when executing the binding function.

The binding engine can still detect an invalid path, and stop the execution when the path has more than two indirections.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/Uno.UI.Toolkit.md

---
uid: Uno.Development.AdditionalFeatures
---

# Other Uno.UI Features

Uno.UI.Toolkit is a set of extension methods or behaviors used to enhance WinUI and activate device/OS specific features.

Those methods are built to have no effect on a platform that does not support the enhanced feature: no need to wrap them into conditional code.

## MenuFlyoutItem - Destructive style

iOS can display `MenuFlyoutItem` to warn user the action will be "destructive". In that case, the button text is displayed in red.

To set a `MenuFlyoutItem` as destructive, add the toolkit namespace to your XAML

```xml
xmlns:toolkit="using:Uno.UI.Toolkit"
```

And declare your `MenuFlyoutItem` as follow

```xml
<MenuFlyoutItem Text="Destructive action"
                toolkit:MenuFlyoutItemExtensions.IsDestructive="True" />
```

## UICommand - Destructive style

iOS can display `UICommand` to warn user the action will be "destructive". In that case, the button text is displayed in red.

To set a `UICommand` as destructive, add the toolkit namespace to your code

```csharp
using Uno.UI.Toolkit;
```

And declare your `UICommand` as follow

```csharp
var uic = new UICommand("Destructive action");
uic.SetDestructive(true);
```

## FromJson markup extension

`FromJson` lets you keep structured sample data in XAML without creating temporary view models. The extension takes a JSON payload, converts it to a dynamic object graph (`ExpandoObject` and nested dictionaries/lists), and assigns it to the consuming property.

The conversion follows simple rules so you always know what type a binding receives:

- JSON objects → `ExpandoObject` (access through `IDictionary<string, object?>`)
- JSON arrays → `List<object?>`
- JSON numbers → `int` (`Int32`) when the value fits, otherwise `double`
- JSON booleans → `bool`
- JSON strings → `string`
- JSON null → `null`

1. Store the JSON in an `x:String` resource so you can keep it formatted with `xml:space="preserve"`.
2. Use the markup extension to deserialize the resource and set the `DataContext`, `ItemsSource`, or any other property that accepts an arbitrary object.

```xml
<Grid xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:uum="using:Uno.UI.Markup"
      xmlns:xml="http://www.w3.org/XML/1998/namespace">
    <Grid.Resources>
        <x:String x:Key="SampleData" xml:space="preserve">
{
    "Title": "Runtime Test",
    "Owner": { "Name": "Uno Platform" },
    "Numbers": [ 1, 2, 3 ]
}
        </x:String>
    </Grid.Resources>

    <TextBlock DataContext="{uum:FromJson Source={StaticResource SampleData}}"
               Text="{Binding Owner.Name}" />
</Grid>
```

You can also apply `FromJson` directly inside `Page.DataContext`, either by referencing an `x:String` resource or by using its content property to inline JSON:

```xml
<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:uum="using:Uno.UI.Markup"
      xmlns:xml="http://www.w3.org/XML/1998/namespace">
    <Page.Resources>
        <x:String x:Key="SamplePerson" xml:space="preserve">
            {
                "Name": "Inline"
            }
        </x:String>
    </Page.Resources>

    <Page.DataContext>
        <uum:FromJson Source="{StaticResource SamplePerson}" />
    </Page.DataContext>

    <TextBlock Text="{Binding Name}" />
</Page>
```

```xml
<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:uum="using:Uno.UI.Markup">
    <Page.DataContext>
        <uum:FromJson>
            <uum:FromJson.Source>
            {
                "Name": "Inline"
            }
            </uum:FromJson.Source>
        </uum:FromJson>
    </Page.DataContext>

    <TextBlock Text="{Binding Name}" />
</Page>
```

If the JSON string is empty or invalid, the extension throws a `XamlParseException`, allowing issues to surface early during page initialization.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/VisibleBoundsPadding.md

---
uid: Uno.Features.VisibleBoundsPadding
---

# VisibleBoundsPadding behavior

> [!IMPORTANT]
> The [`SafeArea`](xref:Toolkit.Controls.SafeArea) control is now preferred to `VisibleBoundsPadding`.

The `Uno.UI.Toolkit.VisibleBoundsPadding` is a behavior that overrides the `Padding` property of a control to ensure that its inner content is always inside the `ApplicationView.VisibleBounds` rectangle.

The `ApplicationView.VisibleBounds` is the rectangular area of the screen which is completely unobscured by any window decoration, such as the status bar, rounded screen corners or some screen notch (e.g. the iPhone X or Essential Phone top sensors notch).

In some cases it's acceptable for visible content to be partially obscured (a page background for example) and it should extend to fill the entire window. Other types of content should be restricted to the visible bounds (for instance readable text, or interactive controls). VisibleBoundsPadding enables this kind of fine-grained control over responsiveness to the visible bounds.

## Using the behavior

The behavior can be placed on any control that provides a Padding property (e.g. Grid, StackPanel, ListView, ScrollViewer, Control, ContentPresenter or Border), and will be automatically adjusted based on the control's absolute position inside the `ApplicationView.VisibleBounds` rectangle.

```xml
<UserControl x:Class="Uno.UI.Samples.Controls.SampleChooserControl"
            xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
            xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
            xmlns:toolkit="using:Uno.UI.Toolkit">
    <Grid toolkit:VisibleBoundsPadding.PaddingMask="All">
    </Grid>
</UserControl>
```

This grid will automatically be assigned a padding, and will be refreshed every time its size or the size of the `ApplicationView.VisibleBounds` changes.

### Specifying a target

The `Uno.UI.Toolkit.VisibleBoundsPadding` behavior defines a `PaddingMask` property that specifies if you want to set the padding to a specific bound of the UI. The values are:

- `None` (*default value*)
- `All`
- `Top`
- `Bottom`
- `Left`
- `Right`

Usage is as follows:

```xml
<UserControl x:Class="Uno.UI.Samples.Controls.SampleChooserControl"
            xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
            xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
            xmlns:toolkit="using:Uno.UI.Toolkit">
    <Grid toolkit:VisibleBoundsPadding.PaddingMask="Bottom" />
</UserControl>
```

#### Notes

- This behavior applies the greater of the existing padding or the calculated padding set on the element it is attached to.
- `VisibleBoundsPadding` on WinAppSDK/Desktop does not have any effect. It is present to allow for same-XAML across platforms.

## See it in action

![image](https://user-images.githubusercontent.com/36631443/68304897-b6205500-0074-11ea-8ec9-b4f02dddd5e6.png)

### Before

![image](https://user-images.githubusercontent.com/36631443/68239478-06e27000-ffd9-11e9-956a-c4d954341a5f.png)

### After

![image](https://user-images.githubusercontent.com/36631443/68239503-1366c880-ffd9-11e9-9d67-f95050b2e1a7.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/accelerometer.md

---
uid: Uno.Features.Accelerometer
---

# Accelerometer

> [!TIP]
> This article covers Uno-specific information for Accelerometer. For a full description of the feature and instructions on using it, see [Use the accelerometer](https://learn.microsoft.com/windows/uwp/devices-sensors/use-the-accelerometer).

* The `Windows.Devices.Sensors.Accelerometer` class allows measuring the linear acceleration of the device along three X, Y, and Z-axis.

## Supported features

| Feature          | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `GetDefault`     | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `ReadingChanged` | ✔       | ✔       | ✔   | ✔          | ✖     | ✖            | ✖            |
| `Shaken`         | ✔       | ✔       | ✔   | ✔          | ✖     | ✖            | ✖            |
| `ReportInterval` | ✔       | ✔       | ✔   | ✔          | ✖     | ✖            | ✖            |

## Using Accelerometer with Uno

* The `GetDefault` method is available on all targets and will return `null` on those that do not support `Accelerometer` or devices that do not have such a sensor.
* Ensure to unsubscribe from the `ReadingChanged` and `Shaken` events when you no longer need the readings, so that the sensor is no longer active to avoid unnecessary battery consumption.
* While iOS features a built-in shake gesture recognition, this is not available on Android and WASM. We use a commonly used implementation that tries to approximate the shake motion to detect it for these platforms. Both Android and WASM use the same implementation. If this is not sufficient for your use case, you can implement Shake detection utilizing the `ReadingChanged` event readings.
* On Android, when both `ReadingChanged` and `Shaken` events are attached and the user sets the `ReportInterval` to a high value, the `ReadingChanged` event may be raised more often than requested. This is because for multiple subscribers to the same sensor, the system may raise the sensor events with the frequency of the one with the lowest requested report delay. This is, however, in line with the behavior of the WinUI Accelerometer, and you can filter the events as necessary for your use case.
* `ReportInterval` property on WASM is not supported directly, and we use an approximation in the form of raising the `ReadingChanged` event only when enough time has passed since the last report. The event is actually raised a bit more often to make sure the gap caused by the filter is not too large, but this is in line with the behavior of the WinUI Accelerometer.

## Examples

### Capturing sensor readings

```csharp
var accelerometer = Accelerometer.GetDefault();
accelerometer.ReadingChanged += Accelerometer_ReadingChanged;

private async void Accelerometer_ReadingChanged(Accelerometer sender, AccelerometerReadingChangedEventArgs args)
{
    // If you want to update the UI in some way, ensure the Dispatcher is used,
    // as the ReadingChanged event handler does not run on the UI thread.
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        OutputTextBlock.Text = $"Sensor reading is " +
            $"x = {args.Reading.AccelerationX}, y = {args.Reading.AccelerationY}, z = {args.Reading.AccelerationZ}, " + 
            $"timestamp = {args.Reading.Timestamp}";
    });
}
```

### Detecting shake

```csharp
var accelerometer = Accelerometer.GetDefault();
accelerometer.Shaken += Accelerometer_ReadingChanged;

private async void Accelerometer_Shaken(Accelerometer sender, AccelerometerShakenEventArgs args)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () => ShakenTimestamp = args.Timestamp.ToString("R"));
}
```

### Unsubscribing from the readings

```csharp
accelerometer.ReadingChanged -= Accelerometer_ReadingChanged;
accelerometer.Shaken -= Accelerometer_ReadingChanged;
```

## See Accelerometer in action

* To see this API in action, visit the [example application for non-UI APIs](https://aka.platform.uno/demo-unexpected-apis).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/additional-vscode-topics.md

---
uid: Uno.vscode.additional
---
# Visual Studio Code Extension

To get started on using VS Code, [head over to our guides](xref:Uno.GetStarted.vscode).

In this page, you'll find other topics about VS Code support, such as code snippets or how to upgrade an existing app to use VS Code.

## Explore other features

The Uno Platform extension provides additional features to help you develop your application.

You can explore them by pressing `F1` or `Ctrl-Shift-P` and typing `Uno Platform` to see the list of available commands.

![vs-code-explore-other-features](Assets/quick-start/vs-code-explore-other-features.png)

## Using code snippets

### Adding a new Page

1. In the MyApp folder, create a new file named `Page2.xaml`
2. Type `page` then press the `tab` key to add the page markup
3. Adjust the name and namespaces as needed
4. In the MyApp folder, create a new file named `Page2.xaml.cs`
5. Type `page` then press the `tab` key to add the page code behind C#
6. Adjust the name and namespaces as needed

### Adding a new UserControl

1. In the MyApp folder, create a new file named `UserControl1.xaml`
2. Type `usercontrol` then press the `tab` key to add the page markup
3. Adjust the name and namespaces as needed
4. In the MyApp folder, create a new file named `UserControl1.xaml.cs`
5. Type `usercontrol` then press the `tab` key to add the page code behind C#
6. Adjust the name and namespaces as needed

### Adding a new ResourceDictionary

1. In the MyApp folder, create a new file named `ResourceDictionary1.xaml`
2. Type `resourcedict` then press the `tab` key to add the page markup

### Other snippets

- `rd` creates a new `RowDefinition`
- `cd` creates a new `ColumnDefinition`
- `tag` creates a new XAML tag
- `set` creates a new `Style` setter
- `ctag` creates a new `TextBlock` close XAML tag

## Updating an existing application to work with VS Code

An existing application needs additional changes to be debugged properly.

1. At the root of the workspace, create a folder named `.vscode`
2. Inside this folder, create a file named `launch.json` and copy the [contents of this file](https://github.com/unoplatform/uno.templates/blob/main/src/Uno.Templates/content/unoapp/.vscode/launch.json).
3. Replace all instances of `MyExtensionsApp._1` with your application's name in `launch.json`.
4. Inside this folder, create a file named `tasks.json` and copy the [contents of this file](https://github.com/unoplatform/uno.templates/blob/main/src/Uno.Templates/content/unoapp/.vscode/tasks.json).

## Advanced debugging

You can find [advanced Code debugging topic here](xref:uno.vscode.mobile.advanced.debugging).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.toolkit.ui/refs/heads/main/doc/helpers/ancestor-itemscontrol-binding.md

---
uid: Toolkit.Helpers.Bindings
---

# AncestorBinding & ItemsControlBinding

These markup extensions provide relative binding based on ancestor type. If you are familiar with WPF, they are very similar to `{RelativeSource Mode=FindAncestor}`.
They are typically used from inside a `DataTemplate` to access elements outside of said data-template which is not normally accessible (eg: through `ElementName` binding). The common usage is to access the parent data-context from inside the `ItemsControl.ItemTemplate`.

## Remarks

Both of the markup extensions are available for all **non-Windows** UWP platforms as well as all WinUI 3 platforms.

## ItemsControlBinding

This markup extension provides a binding to the closest parent ItemsControl. This markup can be used to access the parent ItemsControl from inside of the ItemTemplate.

> [!TIP]
> This is a shortcut for `{utu:AncestorBinding AncestorType=ItemsControl}`.

### Properties

> see the Properties section in AncestorBinding.

### Usage

```csharp
public class ExampleModel
{
    public int[] Items { get; } = new[] { 1, 2, 3 };
    public string SomeText { get; } = "Lorem Ipsum";
}
```

```xml
<!-- Include the following XAML namespace to use the samples below -->
xmlns:utu="using:Uno.Toolkit.UI"
...

<!-- Assuming the DataContext is set to an instance of ExampleModel -->
<ListView ItemsSource="{Binding Items}">
    <ListView.ItemTemplate>
        <DataTemplate>
            <StackPanel>
                <TextBlock>Current item DataContext: <Run Text="{Binding}" /></TextBlock>
                <TextBlock>Current parent(ExampleModel) DataContext:
                    <Run Text="{utu:ItemsControlBinding Path=DataContext.SomeText}" />
                </TextBlock>
            <StackPanel>
        </DataTemplate>
    </ListView.ItemTemplate>
</ListView>
```

## AncestorBinding

This markup extension provides a means to bind to an ancestor of a specific type.

### Properties

| Property           | Type            | Description                                                                                                                            |
| ------------------ | --------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `AncestorType`     | `Type`          | Type of ancestor to bind from.                                                                                                         |
| `Path`             | `string`        | Binding path from the ancestor.                                                                                                        |
| Converter          | IValueConverter | Converter object that is called by the binding engine to modify the data as it is passed between the source and target, or vice versa. |
| ConverterParameter | object          | Parameter that can be used in the Converter logic.                                                                                     |
| ConverterLanguage  | string          | value that names the language to pass to any converter specified by the Converter property.                                            |

### Usage

```csharp
public class ExampleModel
{
    public int[] Items { get; } = new[] { 1, 2, 3 };
    public string SomeText { get; } = "Lorem Ipsum";
}
```

```xml
<!-- Include the following XAML namespace to use the samples below -->
xmlns:utu="using:Uno.Toolkit.UI"
...

<!-- Assuming the DataContext is set to an instance of ExampleModel -->
<Page Tag="From Page">
    <StackPanel>
        <TextBlock Text="From DataContext:" />
        <TextBlock Text="{Binding SomeText}" />

        <ListView ItemsSource="{Binding Items}" Tag="From ListView">
            <ListView.ItemTemplate>
                <DataTemplate>
                    <StackPanel>
                        <TextBlock Text="Current item DataContext:" />
                        <TextBlock FontWeight="Bold" Text="{Binding}" />

                        <TextBlock Text="Current parent (ExampleModel) DataContext:" />
                        <TextBlock FontWeight="Bold" Text="{utu:ItemsControlBinding Path=DataContext.SomeText}" />

                        <TextBlock Text="Accessing property of a parent ListView:" />
                        <TextBlock FontWeight="Bold" Text="{utu:ItemsControlBinding Path=Tag}" />

                        <TextBlock Text="Accessing property of a Page:" />
                        <TextBlock FontWeight="Bold" Text="{utu:AncestorBinding AncestorType=Page, Path=Tag}" />
                    </StackPanel>
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
    </Grid>
</Page>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/android-activities.md

---
uid: Uno.Development.AndroidActivities
---

# Managing activities in Android

[Activities](https://developer.android.com/reference/android/app/Activity) are an integral element of the Android platform. By default your Uno Platform application runs in a single activity, but you might for example spawn a new activity when a user shares content, or picks an image from their device. This article covers Activity management in Uno.

## Android documentation links

- [Introduction to Activities](https://developer.android.com/guide/components/activities/intro-activities)

- [Understand the Activity Lifecycle](https://developer.android.com/guide/components/activities/activity-lifecycle)

## Creating/Using Android Activities

At the root of every Android Uno app, lies a `BaseActivity` class that extends from `Android.Support.V7.App.AppCompatActivity` which is part of the [Android v7 `AppCompat` Support Library](https://developer.android.com/topic/libraries/support-library/features.html#v7-appcompat). If you ever need to create a new Activity within your app or within Uno, you must be sure to extend `BaseActivity` and, if you need to apply a Theme to the activity, ensure that the Theme you set is a `Theme.AppCompat` theme (or descendant).

## Accessing Android main activity events

Uno Platform provides an API to get access to the events/overrides invoked in the main activity (commonly inheriting from `UI.Xaml.ApplicationActivity`) outside of the activity class.

In order to get access to these events, you can write the following:

```csharp
using Uno.UI.ViewManagement;

App()
{
    // ...
    ApplicationViewHelper.GetBaseActivityEvents().Create += OnCreateEvent;
    // ...
}

private void OnCreateEvent(Android.OS.Bundle savedInstanceState)
{

}
```

Note that some events are raised early during the application lifecycle and may need to be registered from the `App` constructor.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/android-tv.md

---
uid: Uno.Features.AndroidTv
---

# Support for Android TV

Uno Platform is proud to support Android TV, enabling you to extend your application's reach to this wide family of devices with unique use cases.

## Enabling Android TV support

To make your application properly show up among installed apps on Android TV and to be able to publish the app to the store, you need to adjust the app manifest to declare support for Android TV.

First, open the `MainActivity` class in the `YourApp` project (or the `YourApp.Droid` project for older versions of Uno Platform), and add an `[IntentFilter]` attribute for `ActionMain` declaring support for `LeanbackLauncher` category.

> [!IMPORTANT]
> If your activity has multiple IntentFilter attributes, make sure ActionMain follows directly after the Activity attribute, otherwise, the app will not launch for debugging in Visual Studio.

```csharp
[Activity(
    MainLauncher = true,
    ConfigurationChanges = ActivityHelper.AllConfigChanges,
    WindowSoftInputMode = SoftInput.AdjustPan | SoftInput.StateHidden
  )]
[IntentFilter(
  new[] { Android.Content.Intent.ActionMain },
  Categories = new[] {
    Android.Content.Intent.CategoryLauncher,
    Android.Content.Intent.CategoryLeanbackLauncher 
  })]
public class MainActivity : Windows.UI.Xaml.ApplicationActivity
{
  ...
}
```

Next, every Android TV app must provide a banner image, which is used to display the app on the home screen. This can be set via the `Banner` property in the `ApplicationAttribute`, which can be found in the `Main.Android.cs` file (or the `Main.cs` file for older versions of Uno Platform):

```csharp
[global::Android.App.ApplicationAttribute(
  Label = "@string/ApplicationName",
  Banner = "@drawable/banner",
  LargeHeap = true,
  HardwareAccelerated = true,
  Theme = "@style/AppTheme"
)]
```

The banner then must be added to the `Resources/drawable-xhdpi` folder. For the banner, use an xhdpi resource with a size of 320 x 180 px. Text must be included in the image. If your app is available in more than one language, you must provide separate versions of the banner with text for each supported language. See [Android docs](https://developer.android.com/training/tv/start/start#banner) for more information.

Finally, to make your app work on both Android TV and Android mobile devices, declare that neither touchscreen nor leanback mode is required. You can do so using the assembly-wide `[UsesFeature]` attributes (you can place these in any file within the `Mobile` or `Droid` project, we recommend the `Main.Android.cs` or `Main.cs` file):

```csharp
[assembly: UsesFeature("android.software.leanback", Required = false)]
[assembly: UsesFeature("android.hardware.touchscreen", Required = false)]
```

You can now deploy your app on a Android TV emulator or actual device. It should show up among the installed apps:

![Installed Android TV app](../Assets/features/androidtv/androidtvapps.png)

## Remote control support

The integration of focus management allows the Android TV remote control to work seamlessly, just like normal keyboard focus navigation. To navigate the focus in your application via the directional pad of the remote control, you need to make sure `XYFocusKeyboardNavigation` is `Enabled` on all your pages:

```xml
<Page xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      XYFocusKeyboardNavigation="Enabled">
    <!-- Your app's UI elements go here -->
</Page>
```

To disable the native Android highlighting of focused elements, the `styles.xml` file needs to be updated to make the highlight transparent:

```xml
<item name="android:colorControlHighlight">@android:color/transparent</item>
```

Please note, that this will disable all the highlights, even in embedded native controls you may host within the Uno Platform app.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/api-differences.md

---
uid: Uno.Development.ApiDifferences
---

# Differences between Uno.UI and WinUI

Uno Platform strives to closely replicate the WinUI API on all platforms and ensure that existing WinUI code is 100% compatible with Uno. This article covers areas where Uno.UI's implementation differs, typically to better integrate with the native platform, or where the capabilities of .NET differ due to inherent limitations of the native platform.

This article doesn't cover parts of the API that haven't been implemented yet. You can consult a [complete list of implemented and unimplemented controls here](implemented-views.md).

For a practical guide to addressing differences between Uno Platform and WinUI, [read this article](migrating-guidance.md).

## API differences

### `FrameworkElement` inherits from native base view types (Android, iOS, macOS)

As for WinUI, all visual elements in Uno.UI inherit from `FrameworkElement`, which inherits from `UIElement`. (At least, those that are publicly available.) On Windows, `UIElement` inherits from the `DependencyObject` class, which inherits from `System.Object`.

On Android, iOS, and macOS, `UIElement` instead inherits from the native base view type for each platform, as exposed to .NET by Xamarin Native. So, `ViewGroup` for Android, `UIView` for iOS, and `NSView` for macOS.

This allows native views (not defined by Uno.UI or inheriting from `FrameworkElement`) to be directly integrated into the visual tree, [in XAML markup or C# code](native-views.md).

### `DependencyObject` type is an interface (all non-Windows platforms)

This API difference follows directly from the previous one. In order to support native view inheritance, Uno.UI defines `DependencyObject` as an interface, rather than a class.

This is as transparent as possible to the application developer. For example, if a developer defines a class that inherits directly from `DependencyObject`, Uno.UI will automatically generate code that implements the `DependencyObject` interface methods. The only developer action required is to add the `partial` keyword to the class definition.

## Runtime differences

### iOS is AOT-only

.NET code [must be Ahead-Of-Time (AOT) compiled to run on iOS](https://learn.microsoft.com/xamarin/ios/internals/limitations), as a fundamental platform limitation. As a result, a few APIs that require runtime code generation (eg `System.Reflection.Emit`) do not work. This includes code that uses the `dynamic` keyword.

### WebAssembly is single-threaded

Currently, WebAssembly code in the browser executes on a single thread. This limitation is expected to be lifted in the future, but for now, code that expects additional threads to be available may not function as expected.

[This GitHub issue](https://github.com/unoplatform/uno/issues/2302) tracks support for multi-threading on WebAssembly in Uno Platform.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/api-extensions.md

---
uid: Uno.Contributing.ApiExtensions
---

# API Extensions

Uno provides a simple mechanism which allows for external provides to provide an implementation for some known interfaces. The goal behind this is two fold:

- Provide a way to remove some types of dependencies from the main Uno.UI package, reducing the payload size of an app if some features are not required
- Provide a way for developers to provide a custom implementation of a known WinRT or WinUI api for which the default implementation is not provided

A common scenario can be found on Android, where adding an external dependency can increase the build time and payload size unnecessarily.

## Declaring an extension

In a nuget package, depending on the Uno.UI package, define the follow code:

```csharp
[assembly: Uno.Foundation.Extensibility.ApiExtension(typeof(Windows.ISomeExtensibleType), typeof(MySomeExtensibleType))]

public class MySomeExtensibleType : ISomeExtensibleType
{
    public MySomeExtensibleType(object owner)
    {
    
    }
}
```

When a nuget package containing such a declaration is found in the currently built application, the App.InitializeComponent() method will automatically add the following code to the app startup:

```csharp
ApiExtensibility.Register(typeof(Windows.ISomeExtensibleType), o => new MySomeExtensibleType(o));
```

This will make the `Windows.ISomeExtensibleType` available for the `ApiExtensibility.CreateInstance<Windows.ISomeExtensibleType(...)` invocation to be available.

## Available Extensible APIs

- `IApplicationViewSpanningRects` to provide a implementation for `ApplicationView.GetSpanningRects()`

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/app-close-handler.md

---
uid: Uno.Features.AppCloseHandler
---

# Preventing Window Closing

> [!TIP]
> This article covers Uno Platform–specific behavior. For the full API documentation, see [AppWindow.Closing Event](https://learn.microsoft.com/en-us/windows/windows-app-sdk/api/winrt/microsoft.ui.windowing.appwindow.closing).

The `AppWindow.Closing` API lets you respond to or prevent standard app window closing requests—such as clicking the window’s close button or pressing <kbd>Alt</kbd>+<kbd>F4</kbd>. Note that this does **not** block the user from terminating the app by force (e.g., via Task Manager or `kill`).

## Platform Support

| Feature              | Windows App SDK | Android | iOS | Web (WASM) | Desktop (Windows) | Desktop (macOS) | Desktop (Linux) |
|----------------------|------------------|---------|-----|------------|-------------------|------------------|------------------|
| `AppWindow.Closing`  | ✔️               | ❌      | ❌  | ❌         | ✔️                | ✔️               | ✔️               |

> [!NOTE]
> On platforms where this feature is not supported, the `Closing` event will still be raised, but setting `args.Cancel = true` has no effect.

## Usage Example

```csharp
MyWindow.AppWindow.Closing += OnAppWindowClosing;

private void OnAppWindowClosing(AppWindow sender, AppWindowClosingEventArgs args)
{
    // Replace with your own logic, such as checking for unsaved changes
    bool cancelClose = ShouldWindowStayOpen();

    // Cancel the close request if needed
    args.Cancel = cancelClose;
}
```

> [!IMPORTANT]
> The `AppWindow.Closing` event must be handled synchronously. Asynchronous operations (e.g., showing a `ContentDialog`) are not allowed and will not delay the closing process.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/interop/apple-login.md

---
uid: Uno.Tutorials.SignInWithApple
---

# Apple Sign-In Button with MAUI Embedding in Uno

In Uno Platform projects, implementing a "Sign in with Apple" Button is possible through MAUI embedding (more on which in our [Overview](xref:Uno.Extensions.Maui.Overview)). Below is a simple example of how you can add the Apple Sign-In Button to your project. We will inject it into the visual tree from the code-behind and handle the authorization using Apple's Authentication Services.

![Sign in with Apple ID](../interop/assets/signin-with-apple.png)

## General Usage

1. Activate the Apple Sign-In Capability:

   - If you are using Visual Studio, open the `Entitlements.plist` file and locate the "Sign In With Apple" checkbox. After checking it, ensure you save your changes.
   - Alternatively, you can open the `Entitlements.plist` file in any text editor and add the following within the `<dict>` tag:

   ```xml
   <key>com.apple.developer.applesignin</key>
   <array>
       <string>Default</string>
   </array>
   ```

2. Import Necessary Namespaces:

   ```csharp
   using AuthenticationServices;
   using Foundation;
   using UIKit;
   ```

3. In the constructor of your Page or control, create the Apple Sign-In Button:

   > [!Important]
   > Ensure that you wrap platform-specific code in `#if __IOS__` directives. For more details, refer to the [Platform-specific C# documentation](xref:Uno.Development.PlatformSpecificCSharp).

   ```csharp
   var appleSignInButton = new ASAuthorizationAppleIdButton(ASAuthorizationAppleIdButtonType.Default, ASAuthorizationAppleIdButtonStyle.WhiteOutline);
   appleSignInButton.TouchUpInside += HandleAuthorizationAppleIDButtonPress;
   appleSignInButton.CornerRadius = 50;

   // Retain the delegate to prevent garbage collection
   _appleSignInDelegate = new AuthorizationControllerDelegate(this);
   ```

   > [!NOTE]
   > It's important to retain a reference to the delegate (`_appleSignInDelegate`) to avoid garbage collection issues. This ensures that the authorization process is completed without interruption.

4. Inject the Apple Sign-In button into the visual tree using `VisualTreeHelper.AdaptNative`:

   ```csharp
   var adaptedAppleButton = VisualTreeHelper.AdaptNative(appleSignInButton);
   var borderWrapper = new Border
   {
       MinHeight = 50,
       MinWidth = 250,
       HorizontalAlignment = HorizontalAlignment.Center,
       Child = adaptedAppleButton,
   };

   m_MainStackPanel.Children.Add(borderWrapper);
   ```

5. Handle the button's `TouchUpInside` event to initiate Apple Sign-In:

   ```csharp
   private void HandleAuthorizationAppleIDButtonPress(object sender, EventArgs e)
   {
       var appleIDProvider = new ASAuthorizationAppleIdProvider();
       var request = appleIDProvider.CreateRequest();
       request.RequestedScopes = new[] { ASAuthorizationScope.FullName, ASAuthorizationScope.Email };

       var authorizationController = new ASAuthorizationController(new ASAuthorizationRequest[] { request });
       authorizationController.Delegate = _appleSignInDelegate;  // Use the retained delegate
       authorizationController.PresentationContextProvider = new PresentationContextProvider();  // Set the presentation context provider
       authorizationController.PerformRequests();
   }
   ```

## Custom Delegate for Authorization

To handle the result of the sign-in process, create a custom delegate:

```csharp
public class AuthorizationControllerDelegate : ASAuthorizationControllerDelegate
{
    private readonly MyUserControl _parent;

    public AuthorizationControllerDelegate(MyUserControl parent)
    {
        _parent = parent;
    }

    public override void DidComplete(ASAuthorizationController controller, ASAuthorization authorization)
    {
        System.Diagnostics.Debug.WriteLine("Authorization successful.");

        try
        {
            var appleIdCredential = authorization.GetCredential<ASAuthorizationAppleIdCredential>();

            var userIdentifier = appleIdCredential?.User;
            // Handle successful authorization, retrieve user details
        }
        catch (Exception ex)
        {
            System.Diagnostics.Debug.WriteLine($"Authorization failed: {ex.Message}");
        }
    }
}
```

## Managing Delegate in MVVM

If you're using an MVVM architecture, the delegate should handle sign-in logic indirectly by passing the necessary data to the ViewModel. This keeps the code clean and follows MVVM principles. For example:

- Instead of passing the user control (`MyUserControl`) to the `AuthorizationControllerDelegate`, pass a reference to the ViewModel or a dedicated service.
- In the delegate, you can call methods on the ViewModel to handle the authorization flow, such as storing user information or navigating to another page.

Example:

```csharp
public class AuthorizationControllerDelegate : ASAuthorizationControllerDelegate
{
    private readonly MyViewModel _viewModel;

    public AuthorizationControllerDelegate(MyViewModel viewModel)
    {
        _viewModel = viewModel;
    }

    public override void DidComplete(ASAuthorizationController controller, ASAuthorization authorization)
    {
        System.Diagnostics.Debug.WriteLine("Authorization successful.");

        try
        {
            var appleIdCredential = authorization.GetCredential<ASAuthorizationAppleIdCredential>();
            var userIdentifier = appleIdCredential?.User;

            // Pass the user info to the ViewModel for further processing
            _viewModel.HandleSuccessfulAuthorization(userIdentifier);
        }
        catch (Exception ex)
        {
            System.Diagnostics.Debug.WriteLine($"Authorization failed: {ex.Message}");
        }
    }
}
```

## Presentation Context Provider

For proper handling of the presentation context on iOS, implement a `PresentationContextProvider`:

```csharp
public class PresentationContextProvider : NSObject, IASAuthorizationControllerPresentationContextProviding
{
    public UIWindow GetPresentationAnchor(ASAuthorizationController controller)
    {
        return UIApplication.SharedApplication.KeyWindow;
    }
}
```

## More Resources

For more details on platform-specific considerations or to improve the user experience:

- [Apple Sign-In Documentation](https://developer.apple.com/documentation/authenticationservices/implementing_user_authentication_with_sign_in_with_apple)
- [MSAL.NET Authentication with Uno](xref:Uno.Interop.MSAL)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/applicationdata.md

---
uid: Uno.Features.ApplicationData
---

# Application Data and Settings

<img src="../Assets/features/applicationdata/appdata.jpg" alt="Application Data and Preferences" style="width: 400px;" />

To store persistent application data and user settings, you can utilize the `Windows.Storage.ApplicationData` class in Uno Platform.

Legend

- ✔  Supported

| Picker             | WinUI      | WebAssembly | Android | iOS/Mac Catalyst   | macOS | Skia Desktop |
|--------------------|------------|-------------|---------|--------------------|-------|--------------|
| `LocalFolder`      | ✔         | ✔          | ✔       | ✔                 | ✔     | ✔            |
| `RoamingFolder`    | ✔         | ✔          | ✔       | ✔                 | ✔     | ✔            |
| `LocalCacheFolder` | ✔         | ✔          | ✔       | ✔                 | ✔     | ✔            |
| `TemporaryFolder`  | ✔         | ✔          | ✔       | ✔                 | ✔     | ✔            |
| `LocalSettings`    | ✔         | ✔          | ✔       | ✔                 | ✔     | ✔            |
| `RoamingSettings`  | ✔         | ✔          | ✔       | ✔                 | ✔     | ✔            |

Please note that `RoamingFolder` and `RoamingSettings` are not roamed automatically across devices, they only provide a logical separation between data that you intend to roam and that you intend to keep local.

## Storing application data

There are several folders where persistent application data can be stored:

- `LocalFolder/RoamingFolder` - general-use application files
- `TemporaryFolder` - files with limited lifetime
- `LocalCacheFolder` - cached files retrieved from external services

In the case of `TemporaryFolder` and `LocalCacheFolder` it is crucial to remember that the user or operating system may purge files stored in these locations to reclaim storage space. To store persistent files prefer the `LocalFolder` or `RoamingFolder`.

The following example shows how you can create a file in `LocalFolder` and then read the contents back:

```csharp
StorageFolder folder = ApplicationData.Current.LocalFolder;

// Create a file in the root of LocalFolder.
StorageFile file = await folder.CreateFileAsync("file.txt", CreationCollisionOption.ReplaceExisting);

// Write text in the newly created file.
await FileIO.WriteTextAsync(file, "Hello, Uno Platform!");

// Read the text from file.
string text = await FileIO.ReadTextAsync(file);
```

## Storing settings

The `LocalSettings` and `RoamingSettings` properties provide access to simple key-value containers that allow storage of lightweight user and application preferences. The values stored in settings should be simple serializable types. To store more complex data structures, it is preferred to serialize them first into a string (for example using a JSON serializer).

```csharp
ApplicationDataContainer localSettings = ApplicationData.Current.LocalSettings;

// Save a setting.
localSettings.Values["name"] = "Martin";

// Read a setting.
string value = (string)localSettings.Values["name"];
```

## Initialization considerations

`ApplicationData` APIs cannot be used before the `App` instance is constructed (i.e., before the instance constructor runs). It is possible to start using them in the `App` constructor, or the Application.OnLaunched method.

## Data location on Skia Desktop

In the case of Skia Desktop targets, the data are stored in application- and user-specific locations on the hard drive. The default path to the various folders depends on the runtime operating system.

### Windows

- `LocalFolder` - `C:\Users\UserName>\AppData\Local\<Publisher>\<ApplicationName>\LocalState`
- `RoamingFolder` - `C:\Users\<UserName>\AppData\Local\<Publisher>\<ApplicationName>\RoamingState`
- `LocalCacheFolder` - `C:\Users\<UserName>\AppData\Local\<Publisher>\<ApplicationName>\LocalCache`
- `TemporaryFolder` - `C:\Users\<UserName>\AppData\Local\Temp\<Publisher>\<ApplicationName>\TempState`
- `LocalSettings` - `C:\Users\<UserName>\AppData\Local\<Publisher>\<ApplicationName>\Settings\Local.dat`
- `RoamingSettings` - `C:\Users\<UserName>\AppData\Local\<Publisher>\<ApplicationName>\Settings\Roaming.dat`

### Unix-based systems

- `LocalFolder` - `/home/<UserName>/.local/share/<Publisher>/<ApplicationName>/LocalState`
- `RoamingFolder` - `/home/<UserName>/.local/share/<Publisher>/<ApplicationName>/RoamingState`
- `TemporaryFolder` - `/tmp/<Publisher>/<ApplicationName>/TempState`
- `LocalCache` - `/home/<UserName>/.cache/<Publisher>/<ApplicationName>/LocalCache`
- `LocalSettings` - `/home/<UserName>/.local/share/<Publisher>/<ApplicationName>/Settings/Local.dat`
- `RoamingSettings` - `/home/<UserName>/.local/share/<Publisher>/<ApplicationName>/Settings/Roaming.dat`

Where `<UserName>` is the name of the currently logged-in user and `<Publisher>` and `<ApplicationName>` are values coming from the `<Identity>` node of the `Package.appxmanifest` (note that the publisher value is prefixed by `CN=` in the manifest, but this is excluded from the folder name).

The default paths above can be overridden using the following feature flags:

- `WinRTFeatureConfiguration.ApplicationData.TemporaryFolderPathOverride` - affects `TemporaryFolder` location
- `WinRTFeatureConfiguration.ApplicationData.LocalCacheFolderPathOverride` - affects `LocalCacheFolder` location
- `WinRTFeatureConfiguration.ApplicationData.ApplicationDataPathOverride` - affects `LocalFolder`, `RoamingFolder`, `LocalCacheFolder`, `LocalSettings` and `RoamingSettings`

These properties need to be set before the application is initialized. The best place for this is `Program.cs`, before the `UnoPlatformHostBuilder` instance is created.

If you intend to support both Windows and Unix-based systems for the Desktop target, make the path conditional utilizing `RuntimeInformation.IsOSPlatform(OSPlatform.Windows)`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/azure-static-webapps.md

---
uid: Uno.Tutorials.AzureStaticWebApps
---

# Hosting Uno Platform WebAssembly apps on Azure Static Web Apps

Deploying and hosting of Uno Platform WebApps can be accomplished using [Azure Static Web Apps](https://learn.microsoft.com/azure/static-web-apps/overview).

This Azure service allows the publication of GitHub and Azure DevOps Git repositories to a service specialized for static web apps. It uses GitHub Actions or Azure DevOps to build and publish the application. The integration also supports the creation of temporary environments for Pull Requests, giving the ability to perform validations while a Pull Request is opened.

You can review [Configure Azure Static Web Apps from Azure documentation](https://learn.microsoft.com/azure/static-web-apps/configuration) to configure the server-side behavior of the application.

## Publishing Uno Platform WebAssembly app on Azure

Here is how to publish an app from GitHub, using Uno Platform:

- In a new repository, create an Uno Platform app using the following command:

    ```bash
    cd <repository-name>
    dotnet new -i Uno.Templates
    dotnet new unoapp -o MyApp
    ```

- If the `<TargetFrameworks>` value in the `MyApp.csproj` does not contain `net9.0-browserwasm`, [make sure to upgrade to the latest Uno release by following these steps](xref:Uno.Development.MigratingFromPreviousReleases).

- If in the `MyApp/wwwroot`, you find a `web.config` file, delete it. This will enable brotli compression in Azure Static Web Apps.
- Search for [Static Web Apps](https://portal.azure.com/#create/Microsoft.StaticApp) in the Azure Portal
- Fill the required fields in the creation form:

    ![visual-studio-installer-web](../Assets/aswa-create.png)

- Select your repository using the **Sign in with GitHub** button
- Select your organization, repository, and branch
- In the build presets, select **Custom**, and keep the default values

    ![visual-studio-installer-web](../Assets/aswa-settings.png)

- Then click on **Review+Create** button. Azure will automatically create a new **GitHub Actions Workflow** in your repository. The workflow will automatically be started and will fail for this first run, as some parameters need to be adjusted.
- In your repository’s newly added github workflow (in `.github/workflows`), add the following two steps, after the checkout step:

    ```yaml
    - name: Setup dotnet
      uses: actions/setup-dotnet@v4
      with:
        dotnet-version: '9.0.x'

    - run: 
        cd src/MyApp
        dotnet publish -c Release -f net9.0-browserwasm
    ```

- In the Deploy step that was automatically added, change the `app_location` parameter to the following:

    ```yaml
    app_location: "src/MyApp/bin/Release/net9.0-browserwasm/publish/wwwroot"
    ```

- Once changed, the application will be built and deployed on your Azure Static Web App instance.

## Configuring Deep Linking with Fallback Routes

Azure Static Web Apps provides the [ability to configure many parts](https://learn.microsoft.com/azure/static-web-apps/configuration) of the application's behavior, and one particular feature is very useful to enable deep linking in applications.

You will need to [enable fallback routes](https://learn.microsoft.com/azure/static-web-apps/configuration#fallback-routes) in your application this way:

- In the `wwwroot` folder, [create a file named `staticwebapp.config.json`](https://learn.microsoft.com/azure/static-web-apps/configuration#file-location), with the following content:

  ```json
  {
    "navigationFallback": {
      "rewrite": "/index.html",
      "exclude": ["/package_*"]
    },
    "routes": [
      {
        "route": "/_framework/blazor.boot.*",
        "headers": {
          "cache-control": "must-revalidate, max-age=3600"
        }
      },
      {
        "route": "/_framework/dotnet.js",
        "headers": {
          "cache-control": "must-revalidate, max-age=3600"
        }
      },
      {
        "route": "/_framework/*",
        "headers": {
          "cache-control": "public, immutable, max-age=31536000"
        }
      },
      {
        "route": "/package_*",
        "headers": {
          "cache-control": "public, immutable, max-age=31536000"
        }
      },
      {
        "route": "/*",
        "headers": {
          "cache-control": "must-revalidate, max-age=3600"
        }
      }
    ]
  }
  ```

- In your application, you'll need to get the active url of the browser this way:

  ```csharp
  if (System.Uri.TryCreate(
      Uno.Foundation.WebAssemblyRuntime.InvokeJS("document.location.search"),
      UriKind.RelativeOrAbsolute,
      out var browserUrl))
  {
      var appPath = browserUrl.GetComponents(System.UriComponents.Path, UriFormat.Unescaped);
      // TODO: Process the path in your application
  }
  ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/barometer.md

---
uid: Uno.Features.Barometer
---

# Barometer

> [!TIP]
> This article covers Uno-specific information for `Barometer`. For a full description of the feature and instructions on using it, see [Barometer Class | Microsoft Learn](https://learn.microsoft.com/uwp/api/windows.devices.sensors.barometer).

* The `Windows.Devices.Sensors.Barometer` class allows measuring pressure in hectopascals (hPa).

## Supported features

| Feature          | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `GetDefault`     | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `ReadingChanged` | ✔       | ✔       | ✔   | ✖          | ✖     | ✖            | ✖            |
| `ReportInterval` | ✔       | ✔       | ✖   | ✖          | ✖     | ✖            | ✖            |

## Using Barometer with Uno

* The `GetDefault` method is available on all targets and will return `null` on those which do not support `Barometer` or devices that do not have such a sensor.
* Ensure to unsubscribe from the `ReadingChanged` event when you no longer need the readings, so that the sensor is no longer active to avoid unnecessary battery consumption.

## Example

### Capturing sensor readings

```csharp
var barometer = Barometer.GetDefault();
barometer.ReadingChanged += Barometer_ReadingChanged;

private async void Barometer_ReadingChanged(Barometer sender, BarometerReadingChangedEventArgs args)
{
    // If you want to update the UI in some way, ensure the Dispatcher is used,
    // as the ReadingChanged event handler does not run on the UI thread.
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        OutputTextBlock.Text = $"Sensor reading in hPa = {args.Reading.StationPressureInHectopascals}, " +
            $"timestamp = {args.Reading.Timestamp}";
    });
}
```

### Unsubscribing from the readings

```csharp
barometer.ReadingChanged -= Barometer_ReadingChanged;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/best-practices-uno.md

---
uid: Uno.Development.BestPractices
---

# Best practices for developing Uno Platform applications

This article covers some basic best practices when developing cross-platform applications with Uno Platform.

## Questions to ask

1. Which [platforms](xref:Uno.GettingStarted.Requirements) do I plan to target?
2. What framework features do I plan to use? Are they supported on all of my planned target platforms?
3. Which major third-party dependencies will I use? Are they supported on all of my planned target platforms?

## Development workflow

Testing and debugging your application is easier and more rapid on some platforms and trickier and more time-consuming on others. Depending on where you're at in your development cycle, it may make sense to test all platforms, or it may make sense to focus on the 'easiest' platform.

1. **At the beginning of the development cycle,** you should identify key features from the Uno Platform framework and 3rd-party dependencies that you plan to use. Check that the framework controls you plan to use [are implemented](implemented-views.md). Consider creating a simple proof-of-concept (POC) app covering the 'riskiest' features and testing it on all platforms you're targeting.

2. **In the middle of the development cycle,** once the major pieces are in place, when you're iterating on the UI and business logic of your application, most of your day-to-day development should focus on the easiest platform to develop on. Most of the time, this will be Windows, where you can take advantage of Microsoft's excellent tooling (Live Visual Tree, XAML Hot Reload, etc) and where build times are often shortest. For this reason, it's recommended to keep the Windows (WinUI 3) head project in your solution, even if you don't plan to publish your application to Windows.

3. **At the end of the development cycle,** as your attention shifts to testing and fixing bugs, you'll again distribute your time more equally across all of the platforms you plan to target, ensuring that the application looks and behaves consistently everywhere.

## Platform-specific code

It's likely that some part of your application's code, be it C# code or XAML markup, will be specific to only one platform - perhaps because you want to access platform-specific APIs, implement a feature using native third-party libraries, or simply customize the experience to be more idiomatic to that particular platform.

You can read more on the mechanics of platform-specific code [here for C#](xref:Uno.Development.PlatformSpecificCSharp) and [here for XAML](xref:Uno.Development.PlatformSpecificXaml). You should also make sure you understand [an Uno Platform App solution structure](xref:Uno.Development.AppStructure).

The main goals where platform-specific code is concerned are to:

* **Maximize maintainability by keeping as much code shared as possible.**
* **Maximize readability by organizing your code in a consistent, legible way.**

Here are some tips to achieve that:

* **Use [partial class](platform-specific-csharp.md#partial-class-definitions) definitions to mix shared code and platform-specific code in a single class.** Separating all platform-specific code into a dedicated partial definition is usually more readable than interleaving platform-specific `#if` blocks with shared code, particularly if the amount of platform-specific code is significant.
* **Give partial definition files a platform-specific suffix.** Eg, for a `FormHighlighter` class, the shared partial definition would go in `FormHighlighter.cs`, the iOS-specific partial definition would go in `FormHighlighter.iOS.cs`, etc.
* **(Optional) Consider putting platform-agnostic application layers in a separate .NET Standard project.** 'Thinking multi-platform' adds to the cognitive burden of reading and writing code, as well as the testing effort of verifying that it runs the same way on every platform. For this reason, some people prefer to split out platform-agnostic parts of the application into a separate .NET Standard project, eg 'pure' business logic which doesn't interact with the UI or with non-visual platform APIs. This project builds once as a single binary used on all platforms, giving a stronger guarantee that it will behave consistently everywhere. Enforcing that platform-agnostic separation does impose an architectural burden too, so it's a matter of personal preference.

## Application architecture

You have a lot of choice when choosing an architecture for an Uno Platform application. Since it uses the WinUI contract, Uno Platform supports several features which lend themselves to a [model/view/view-model (MVVM) approach](https://learn.microsoft.com/windows/uwp/data-binding/data-binding-and-mvvm), like data binding and dependency properties; but you're perfectly free to use any approach you like best.

Sometimes so much freedom can be paralyzing. To help you get started, we've created several reference applications especially for Uno Platform. These are working, real-world applications utilizing simple but effective architectural patterns for cross-platform development.

* [**Ch9**](https://github.com/unoplatform/Uno.Ch9): browse content from Microsoft's publicly-available Channel 9 video feed.
* [**UADO**](https://github.com/unoplatform/uado): Universal Azure DevOps Organizer

## Performance

See a checklist of performance-related best practices in [Uno Platform Performance](Uno-UI-Performance.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/bluetoothdevice.md

---
uid: Uno.Features.BluetoothDevice
---

# Support for Windows.Devices.Bluetooth

The support for `Windows.Devices.Bluetooth` is not available at this point, but some of the `BluetoothDevice` methods (getting device selectors) are implemented.

## Note for contributors of this Windows.Devices.Bluetooth

To implement the `BluetoothDevice.GetDeviceSelectorFromClassOfDevice` method, you can use some of the information below.

This method should iterate all `ServiceCapabilities`, and use bits from it to construct part of query, and the method may look like:

  ```csharp
return _deviceSelectorPrefix +
    "((System.Devices.Aep.Bluetooth.Cod.Major:=" + classOfDevice.MajorClass +
    "AND System.Devices.Aep.Bluetooth.Cod.Minor:=" + classOfDevice.MinorClass +
    "AND  " e.g. "System.Devices.Aep.Bluetooth.Cod.Services.Information:=System.StructuredQueryType.Boolean#True"
    ") OR " + _deviceSelectorIssueInquiry + "#True)";
  ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/contributing/guidelines/breaking-changes.md

---
uid: Uno.Contributing.BreakingChanges
---

# Guidelines for breaking changes

## Overview

Uno uses a [Package Diff tool](https://github.com/unoplatform/uno.PackageDiff) to ensure that [binary breaking changes](https://learn.microsoft.com/dotnet/standard/library-guidance/breaking-changes#binary-breaking-change) do not
go unnoticed. As [part of our continuous integration process](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/build/Uno.UI.Build.csproj#L529), the PackageDiffTool consumes the last published non-experimental package available on nuget.org, and compares it with the current PR.

This process only diffs against previous versions of Uno, not against the WinUI assemblies, so it doesn't pick up all forms of mismatches. There are [some inconsistencies](https://github.com/unoplatform/uno/pull/1300) dating from before SyncGenerator was added. At some point it might be a good idea to extend SyncGenerator tool to try to report them all (or even automatically fix them)

Breaking changes must be marked as such when committed using the [Conventional Commits formatting](../../uno-development/git-conventional-commits.md).

## When are binary breaking changes acceptable?

### Breaking cross-platform compatibility - not ok

Changes that break compatibility with the public API surface of WinUI are generally never acceptable, because they not only break existing code but break cross-platform compatibility as well.

### Restoring cross-platform compatibility - ok, but discuss with core team

In some cases, Uno's existing API is close to WinUI, but not identical. (Hypothetical example: a property with type `DependencyObject[]` on Uno, but type `IList<DependencyObject>` on WinUI.) This is mostly the case for older code that was written before the use of [generated `NotImplemented` stubs](../../uno-development/uno-internals-overview.md#generated-notimplemented-stubs) and the `PackageDiff` tool, which act in combination to prevent these kinds of errors when implementing new features.

In these cases, we do want to align Uno with WinUI, even at the expense of a breaking change. However, we tend to be more careful with when we merge these changes, compared to other bugfixes. We prefer to 'batch' many such breaking changes into a single stable release cycle, rather than wear out consumers' patience with a steady trickle of breaking changes each release.

The best way to proceed is to create an issue if one doesn't exist already, and open a discussion with the core team about the change in question, so we can jointly work out how best to manage it.

Note that some cases may be sufficiently benign that the breaking change is acceptable in a normal release cycle. (For example, removing a public constructor for an obscure `EventArgs` subclass that would presumably never be created from user code anyway.)

### Breaking changes to Uno-only APIs - it depends

The diff tool guards against all changes to Uno's public API surface, including functionality that has no equivalent in WinUI's API surface.

In the cases where these Uno-only APIs are exposed intentionally (example: the [`VisibleBoundsPadding` behavior](../../features/VisibleBoundsPadding.md)), we would usually reject breaking changes, unless there were a very compelling reason for them.

In other cases, this might be functionality that's inadvertently exposed - in other words, functionality that was made public when it should really have been internal. Here the validity of the breaking change should be considered on a case-by-case basis, taking into account the risk of breaking existing Uno app code (and conversely, the possibility for the Uno-only APIs to collide with 'brownfield' WinUI code). Again, the principle of 'batching' breaking changes applies.

## Adding breaking changes to the allow list

Where a breaking change is acceptable according to the above criteria, and after discussion with the core team where appropriate, it can be marked as such using the [build/PackageDiffIgnore.xml](https://github.com/unoplatform/uno/blob/master/build/PackageDiffIgnore.xml) file.

Please refer to the documentation of the [Uno.PackageDiff tool](https://github.com/unoplatform/uno.PackageDiff) for more information.

## Example report

Below is a comparison report for Uno.UI **1.45.0** with Uno.UI **1.46.0-PullRequest1300.2330** as part of [this pull-request](https://github.com/unoplatform/uno/pull/1300).

You can find the report within the `NuGetPackages.zip` archive on the build server and attached to the pull-request job. The report uses this convention: `ApiDiff.1.46.0-PullRequest1300.2330.md`

Key things to pay attention to:

- the report is for each TFM and the assemblies for that TFM.
- breaking changes which have been blessed have been ~~struck out~~.
- `Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()` is the breaking change which has not been blessed and thus the process failed the build.

```md
## MonoAndroid80 Platform
#### Uno.dll
##### 0 missing types:
##### 8 missing or changed method in existing types:
- `Windows.Phone.Devices.Notification.VibrationDevice`
    * ~~``System.Void Windows.Phone.Devices.Notification.VibrationDevice..ctor()``~~
- `Windows.Devices.Sensors.Accelerometer`
    * ~~``System.Void Windows.Devices.Sensors.Accelerometer..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReading`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerReading..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerShakenEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerShakenEventArgs..ctor()``~~
- `Windows.Devices.Sensors.Barometer`
    * ~~``System.Void Windows.Devices.Sensors.Barometer..ctor()``~~
- `Windows.Devices.Sensors.BarometerReading`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.BindingHelper.Android.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 15 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
    * ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.Popup`
    * ~~``Android.Views.View Windows.UI.Xaml.Controls.Popup.get_Anchor()``~~
    * ~~``System.Void Windows.UI.Xaml.Controls.Popup.set_Anchor(Android.Views.View value)``~~
- `Windows.UI.Xaml.Controls.TextBoxView`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView..ctor()``~~
    * ~~``System.String Windows.UI.Xaml.Controls.TextBoxView.get_BindableText()``~~
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView.set_BindableText(System.String value)``~~
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView.NotifyTextChanged()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 3 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
    * ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
- `Windows.UI.Xaml.Controls.Popup`
    * ~~``Android.Views.View Windows.UI.Xaml.Controls.Popup::Anchor()``~~
- `Windows.UI.Xaml.Controls.TextBoxView`
    * ~~``System.String Windows.UI.Xaml.Controls.TextBoxView::BindableText()``~~
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## MonoAndroid90 Platform
#### Uno.dll
##### 0 missing types:
##### 8 missing or changed method in existing types:
- `Windows.Phone.Devices.Notification.VibrationDevice`
    * ~~``System.Void Windows.Phone.Devices.Notification.VibrationDevice..ctor()``~~
- `Windows.Devices.Sensors.Accelerometer`
    * ~~``System.Void Windows.Devices.Sensors.Accelerometer..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReading`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerReading..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerShakenEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerShakenEventArgs..ctor()``~~
- `Windows.Devices.Sensors.Barometer`
    * ~~``System.Void Windows.Devices.Sensors.Barometer..ctor()``~~
- `Windows.Devices.Sensors.BarometerReading`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.BindingHelper.Android.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 15 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
    * ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.Popup`
    * ~~``Android.Views.View Windows.UI.Xaml.Controls.Popup.get_Anchor()``~~
    * ~~``System.Void Windows.UI.Xaml.Controls.Popup.set_Anchor(Android.Views.View value)``~~
- `Windows.UI.Xaml.Controls.TextBoxView`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView..ctor()``~~
    * ~~``System.String Windows.UI.Xaml.Controls.TextBoxView.get_BindableText()``~~
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView.set_BindableText(System.String value)``~~
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxView.NotifyTextChanged()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 3 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
    * ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
- `Windows.UI.Xaml.Controls.Popup`
    * ~~``Android.Views.View Windows.UI.Xaml.Controls.Popup::Anchor()``~~
- `Windows.UI.Xaml.Controls.TextBoxView`
    * ~~``System.String Windows.UI.Xaml.Controls.TextBoxView::BindableText()``~~
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## netstandard2.0 Platform
#### Uno.dll
##### 0 missing types:
##### 7 missing or changed method in existing types:
- `Windows.Phone.Devices.Notification.VibrationDevice`
    * ~~``System.Void Windows.Phone.Devices.Notification.VibrationDevice..ctor()``~~
- `Windows.Devices.Sensors.Accelerometer`
    * ~~``System.Void Windows.Devices.Sensors.Accelerometer..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReading`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerReading..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerShakenEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerShakenEventArgs..ctor()``~~
- `Windows.Devices.Sensors.BarometerReading`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 9 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
    * ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 1 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
    * ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.Wasm.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## UAP Platform
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## xamarinios10 Platform
#### Uno.dll
##### 0 missing types:
##### 8 missing or changed method in existing types:
- `Windows.Phone.Devices.Notification.VibrationDevice`
    * ~~``System.Void Windows.Phone.Devices.Notification.VibrationDevice..ctor()``~~
- `Windows.Devices.Sensors.Accelerometer`
    * ~~``System.Void Windows.Devices.Sensors.Accelerometer..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReading`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerReading..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerReadingChangedEventArgs..ctor()``~~
- `Windows.Devices.Sensors.AccelerometerShakenEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.AccelerometerShakenEventArgs..ctor()``~~
- `Windows.Devices.Sensors.Barometer`
    * ~~``System.Void Windows.Devices.Sensors.Barometer..ctor()``~~
- `Windows.Devices.Sensors.BarometerReading`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 10 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
    * ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.VirtualizingPanelLayout`
    * ~~``System.Void Windows.UI.Xaml.Controls.VirtualizingPanelLayout.UpdateLayoutAttributesForItem(UIKit.UICollectionViewLayoutAttributes layoutAttributes)``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 1 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
    * ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
#### Uno.UI.Toolkit.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
## xamarinmac20 Platform
#### Uno.dll
##### 0 missing types:
##### 2 missing or changed method in existing types:
- `Windows.Devices.Sensors.BarometerReading`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReading..ctor()``~~
- `Windows.Devices.Sensors.BarometerReadingChangedEventArgs`
    * ~~``System.Void Windows.Devices.Sensors.BarometerReadingChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.Foundation.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
#### Uno.UI.dll
##### 0 missing types:
##### 9 missing or changed method in existing types:
- `Windows.UI.Xaml.Controls.ComboBoxItem`
    * ~~``Windows.UI.Xaml.Controls.Popup Windows.UI.Xaml.Controls.ComboBoxItem.GetPopupControl()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogButtonClickEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosedEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingDeferral`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingDeferral..ctor()``~~
- `Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.ContentDialogClosingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxBeforeTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextBoxTextChangingEventArgs..ctor()``~~
- `Windows.UI.Xaml.Controls.TextChangedEventArgs`
    * ~~``System.Void Windows.UI.Xaml.Controls.TextChangedEventArgs..ctor()``~~
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 1 missing or changed properties in existing types:
- `Windows.UI.Xaml.ResourceDictionary`
    * ``Windows.UI.Xaml.ResourceDictionary[] Windows.UI.Xaml.ResourceDictionary::MergedDictionaries()``
#### Uno.Xaml.dll
##### 0 missing types:
##### 0 missing or changed method in existing types:
##### 0 missing or changed events in existing types:
##### 0 missing or changed fields in existing types:
##### 0 missing or changed properties in existing types:
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/contributing/build-artifacts.md

---
uid: Uno.Contributing.Artifacts
---

# Build artifacts

- Uno publishes a new [pre-release build to NuGet](https://www.nuget.org/packages/Uno.WinUI) after every merge to master.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/building-uno-ui.md

---
uid: Uno.Contributing.BuildingUno
---

# Building Uno.UI

This article explains how to build Uno.UI locally, for instance, if you wish to contribute a bugfix or new feature.

## Prerequisites

- Visual Studio 2026 (18.0+) or later
  - Select the **ASP.NET and Web Development** workload
  - Select the **.NET Multi-Platform App UI development** workload
  - Select the **.NET desktop development** workload
  - To build the UWP flavor of Uno, you'll need **UWP Development**, install all recent UWP SDKs, starting from 10.0.19041 (or above or equal to `TargetPlatformVersion` line [in this file](https://github.com/unoplatform/uno/blob/master/src/Uno.CrossTargetting.targets))
- Install (**Tools** / **Android** / **Android SDK manager**) all Android SDKs starting from 7.1 (or the Android versions `TargetFrameworks` [list used here](https://github.com/unoplatform/uno/blob/master/src/Uno.UI.BindingHelper.Android/Uno.UI.BindingHelper.Android.netcoremobile.csproj))
- Run [Uno.Check](https://github.com/unoplatform/uno.check) on your dev machine to setup .NET Android/iOS workloads
- Install the latest [.NET SDK](https://aka.ms/dotnet/download) from Microsoft.

## Recommended Windows hardware

Loading and building the Uno.UI solution is a resource-intensive task. As a result, opening it in Visual Studio requires a minimum hardware configuration to avoid spending time waiting for builds.

**Minimum configuration:**

- Intel i7 (8th gen) or equivalent
- 16 GB of RAM
- 250GB of Fast SSD

**Optimal configuration:**

- Intel i9 or equivalent
- 32 GB of RAM
- 500GB M2 SSD

## Building Uno.UI for a single target platform

This is the **recommended** approach to building the Uno.UI solution. It will build a single set of binaries for a particular platform (eg Android, iOS, WebAssembly, etc).

Building for a single target platform is considerably faster, much less RAM-intensive, and generally more reliable.

It involves two things - setting an override for the target framework that will be picked up by the (normally multi-targeted) projects inside the Uno solution, and opening a preconfigured [solution filter](https://learn.microsoft.com/visualstudio/ide/filtered-solutions) which will only load the projects needed for the current platform.

The step-by-step process is:

1. Make sure you don't have the Uno.UI solution opened in any Visual Studio instance. (Visual Studio may crash or behave inconsistently if it's open when the target override is changed)
1. Make a copy of the [`src/crosstargeting_override.props.sample`](https://github.com/unoplatform/uno/blob/master/src/crosstargeting_override.props.sample) file and name this copy `src/crosstargeting_override.props`.
1. In `crosstargeting_override.props`, uncomment the line `<UnoTargetFrameworkOverride>xxx</UnoTargetFrameworkOverride>`
1. Set the build target inside `<UnoTargetFrameworkOverride></UnoTargetFrameworkOverride>` to the identifier for the target platform you wish to build for (Identifiers for each platform are listed in the `crosstargeting_override.props` file), then save the file.
1. In the `src` folder, look for the solution filter (`.slnf` file) corresponding to the target platform override you've set, which will be named `Uno.UI-[Platform]-only.slnf` (or the name listed in `crosstargeting_override.props` for the selected `UnoTargetFrameworkOverride`), and open it.
1. To confirm that everything works:
   - For iOS/Android native you can right-click on the `Uno.UI` project
   - For WebAssembly/native, you can right-click on the `Uno.UI.Runtime.WebAssembly` project
   - For Skia, you can right-click on the corresponding `Uno.UI.Runtime.Skia.[Win32|X11|macOS|iOS|Android|Wpf]` project
1. Optionally adjust additional parameters in `crosstargeting_override.props`, such as `UnoDisableNetAnalyzers`, which can improve the build time during debugging sessions.

Once you've built successfully, for the next steps, [consult the guide here](debugging-uno-ui.md) for debugging Uno.UI.

> [!IMPORTANT]
> You will need to repeat the above steps 2. and subsequent when changing the active `UnoTargetFrameworkOverride` value.

If you've followed the steps above, you have your environment set up with the listed prerequisites, and you still encounter errors when you try to build the solution, you can reach out to the core team on Uno's [Discord Server](https://platform.uno/discord).

### Windows and long paths issues

If the build tells you that `LongPath` is not enabled, you may enable it on Windows 10 by using :

```bash
reg ADD HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\FileSystem /v LongPathsEnabled /t REG_DWORD /d 1
```

If for some reason you cannot modify the registry, you can disable this warning by adding `<UnoUIDisableLongPathWarning>false</UnoUIDisableLongPathWarning>` to the project.

Note that long paths may be required when building Uno, and invalid paths errors may arise.

## Building Uno.UI for all available targets

It's recommended to build using the single-target approach, but it's also possible to build for all targets at once, if you wish.

1. If you've previously followed the single-target steps, comment out the `<UnoTargetFrameworkOverride />` line in your `crosstargeting_override.props` file.
2. Open the [Uno.UI.slnx](https://github.com/unoplatform/uno/blob/master/src/Uno.UI.slnx)
3. Select the `Uno.UI` project
4. Build

Inside Visual Studio, the number of platforms is restricted to limit the compilation time.

## Troubleshooting build issues

Here are some tips when building the Uno solution and failures happen:

- Make sure to be on the latest master commit
- Try to close VS 2022, delete the `src/.vs` folder, then try rebuilding the solution
- If the `.vs` deletion did not help, run `git clean -fdx` (after having closed Visual Studio) before building again
- Make sure to have a valid `UnoTargetFrameworkOverride` which matches your solution filter
- Make sure to have the Windows SDK `19041` installed

## Other build-related topics

### Building the reference assemblies for Skia and WebAssembly

Skia and WebAssembly+Native use a custom bait-and-switch technique for assemblies for which the `netX.0` target framework assemblies (called reference assemblies) found in NuGet packages (`lib` folder) are only used for building applications. At the end of a head build, those reference assemblies are replaced by public API compatible assemblies located in the `uno-runtime\[target-framework]` folder of NuGet packages.

When developing a feature using solution filters, if new public APIs are added, building the Uno.UI solution will not update the reference assemblies, causing applications or libraries using the overridden NuGet cache to be unable to use those newly added APIs.

In order to update those reference assemblies, set `<UnoTargetFrameworkOverride>...</UnoTargetFrameworkOverride>` to `netX.0`, then open the `Uno.UI-Reference-Only.slnf` filter. You can now build the `Uno.UI` project. Doing this will generate the proper assemblies with the new APIs to be used in applications or libraries using the NuGet cache override.

### Using the Package Diff tool

Refer to the [guidelines for breaking changes](../contributing/guidelines/breaking-changes.md) document.

### Updating the Nuget packages used by the Uno.UI solution

The versions used are centralized in the [Directory.Build.targets](https://github.com/unoplatform/uno/blob/master/src/Directory.Build.targets) file, and all the
locations where `<PackageReference />` are used.

When updating the versions of NuGet packages, make sure to update all the .nuspec files in the [`build/nuget` folder](https://github.com/unoplatform/uno/tree/master/build/nuget).

### Running the SyncGenerator tool

Uno Platform uses a tool which synchronizes all WinRT and WinUI APIs with the type implementations already present in Uno. This ensures that all APIs are present for consumers of Uno, even if some are not implemented.

The synchronization process takes the APIs provided by the WinMD files referenced by the `Uno.UWPSyncGenerator.Reference` project and generates stubbed classes for types in the `Generated` folders of Uno.UI, Uno.Foundation and Uno.WinRT projects. If the generated classes have been partially implemented in Uno (in the non-Generated folders), the tool will automatically skip those implemented methods.

The tool needs to be run on Windows because of its dependency on the Windows SDK WinMD files.

To run the synchronization tool:

- Open a `Developer Command Prompt for Visual Studio` (2019 or 2022)
- Go to the `uno\build` folder (not the `uno\src\build` folder)
- Run the `run-api-sync-tool.cmd` script; make sure to follow the instructions

Note that the tool needs to be run manually and is not run as part of the CI.

### Android Resources ID generation

To workaround a performance issue, all `Resource.designer.cs` generation is disabled for class libraries in this repo.

If you need to add a new `@(AndroidResource)` value to be used from C# code inside of Uno.UI libraries:

1. Comment out the `<PropertyGroup>` in `Directory.Build.targets` that sets `$(AndroidGenerateResourceDesigner)` and `$(AndroidUseIntermediateDesignerFile)` to `false`.

2. Build Uno.UI as you normally would. You will get compiler errors about duplicate fields, but `obj\Debug\net6.0-android\Resource.designer.cs` should now be generated.

3. Open `obj\Debug\net6.0-android\Resource.designer.cs`, and find the
   field you need such as:

    ```csharp
    // aapt resource value: 0x7F010000
    public static int foo = 2130771968;
    ```

4. Copy this field to the `Resource.designer.cs` checked into source
   control, such as: `src/Uno.UI/Resources/Resource.designer.g.Android.cs`

5. Restore the commented code in `Directory.Build.targets`.

_This performance optimization is inspired by @jonathanpeppers's performance work done in https://github.com/dotnet/maui/pull/2606. Thanks Jonathan!_

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/clipboard.md

---
uid: Uno.Features.Clipboard
---

# Clipboard

> [!TIP]
> This article covers Uno-specific information for `Clipboard`. For a full description of the feature and instructions on using it, see [Copy and paste](https://learn.microsoft.com/windows/uwp/app-to-app/copy-and-paste).

* The `Windows.ApplicationModel.DataTransfer.Clipboard` class allows you to copy content from your application, and paste the content into your application.

## Supported features

| Feature          | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `SetContent`     | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `GetContent`     | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `Clear`          | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `ContentChanged` | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `Flush`          | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |

<!-- Add any additional information on platform-specific limitations and constraints -->

## Using Clipboard with Uno

> [!Video https://www.youtube-nocookie.com/embed/bfT4_LZrSQQ]

* `SetContent` and `GetContent` APIs currently support textual data on all platforms. On Android, they also support URI and HTML formats, but the clipboard can hold only one item. Setting multiple items at once does not work reliably.
* `ContentChanged` event can observe clipboard changes only when the application is in the foreground. On macOS, the `ContentChanged` event checks for clipboard changes by polling the current `NSPasteboard` change count in 1-second intervals. The polling starts only after the first subscriber attaches to the `ContentChanged` event and stops after the last subscriber unsubscribes.
* `Flush` operation has an empty implementation. In contrast to WinUI, on other platforms, data automatically remains in the clipboard even after the application is closed.

## Examples

### Copying text to clipboard

```csharp
var dataPackage = new DataPackage();
dataPackage.SetText("Hello, clipboard");
Clipboard.SetContent(dataPackage);
```

### Pasting text from the clipboard

```csharp
var content = Clipboard.GetContent();
var text = await content.GetTextAsync();
```

### Observing clipboard changes

```csharp
Clipboard.ContentChanged += Clipboard_ContentChanged;

private void Clipboard_ContentChanged(object sender, object e)
{
    // ...
}
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/contributing/guidelines/code-style.md

---
uid: Uno.Contributing.CodeStyle
---

# Guidelines for Code style

Uno uses EditorConfig ([here's our configuration](https://github.com/unoplatform/uno/blob/master/.editorconfig)) to maintain consistent coding styles and settings in our codebase, such as indent style, tab width, end of line characters, encoding, and more. Most IDEs should respect the `EditorConfig` settings by default when applying formatting. We typically observe the [Microsoft C# Coding Conventions](https://learn.microsoft.com/dotnet/csharp/programming-guide/inside-a-program/coding-conventions) with one notable exception - Uno uses Tabs. If you install this [Visual Studio plugin](https://marketplace.visualstudio.com/items?itemName=mynkow.FormatdocumentonSave) it will automatically format your contributions upon file save.

## Refactoring

Pure refactoring for its own sake should generally be done in a separate, refactoring-only pull request, and you should generally open an issue to initiate discussion with the core team before you start such a refactoring, to determine if it's really appropriate. See [this blog post on Open Source Contribution Etiquette](https://tirania.org/blog/archive/2010/Dec-31.html) for some explanation of the reasons why. Consistently-observed conventions are essential to the long-term health of the codebase.

Within a bugfix or enhancement PR, refactoring should be restricted to the relevant files, and it should respect the conventions of existing Uno code.

## Patterns

This section describes some recurring patterns and practices you'll see in Uno code.

### Partial classes

[Partial class definitions](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods) are used extensively in Uno. The two main use cases for partial classes are [platform-specific code](../../platform-specific-csharp.md) and [generated code](../../uno-development/uno-internals-overview.md#generated-notimplemented-stubs).

However, in some cases where it makes sense, partial class files are also used for logical separation of code. If you're implementing a type that owns a lot of dependency properties, consider putting these in a separate partial, to avoid cluttering up the file where the actual business logic is with DP boilerplate. Another use case for a partial is a nested class with a large definition.

### Disposables

Uno uses lightweight `IDisposables` widely for robust lifetime management. The most commonly used types for this purpose are `SerialDisposable`, `CompositeDisposable`, `CancellationDisposable`, and `DisposableAction`.

If you've used the `Reactive Extensions` framework, these names [might be familiar](https://learn.microsoft.com/previous-versions/dotnet/reactive-extensions/hh229090(v=vs.103)), and in fact these disposables behave identically to their Rx equivalents. However, they've been transplanted into [Uno](https://github.com/unoplatform/uno/tree/master/src/Uno.Foundation/Uno.Core.Extensions/Uno.Core.Extensions.Disposables/Disposables), to avoid having to take a dependency on `System.Reactive`.

### Extension methods

[Extension methods](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/extension-methods) are used throughout the Uno Platform codebase to add reusable functionality to existing types, particularly types coming from the Xamarin bindings. Extension methods should be defined in a dedicated class, with the naming convention `[TypeName]Extensions.cs`, where `TypeName` is the name of the type either being returned or passed as the `this` parameter.

A number of extensions to the standard .NET types already exists in [Uno.Foundation](https://github.com/unoplatform/uno/tree/master/src/Uno.Foundation/Uno.Core.Extensions). So, you should check those first to see if they do what you need.

When adding a new extension method class, it should typically be marked `internal`, to avoid naming clashes with existing consumer code.

## Conventions

### Braces

```csharp
if (condition)
{
    // do something
}
else
{
    // use braces even for single line conditions
}
```

## Integration Tests (UI Tests)

```csharp
[ActivePlatforms(Platform.Android, Platform.Browser, Platform.iOS)]
[TestFixture]
public class LocalSettings_Tests : SampleControlUITestBase
{
    [Test]
    [AutoRetry]
    public void ClearAddContainsRemove()
    {
        // Navigate to this x:Class control name
        Run("UITests.Shared.Windows_Storage_ApplicationData.LocalSettings");

        // Define elements that will be interacted with at the start of the test
        var containerName = _app.Marked("ContainerName");
        var clearButton = _app.Marked("ClearButton");
        var addButton = _app.Marked("AddButton");
        var containsButton = _app.Marked("ContainsButton");
        var removeButton = _app.Marked("RemoveButton");
        var output = _app.Marked("Output");

        // Specify what user interface element to wait on before starting test execution
        _app.WaitForElement(clearButton);

        // Take an initial screenshot
        TakeScreenshot("Initial State");

        // Assert initial state
        Assert.AreEqual("Local", containerName.GetDependencyPropertyValue("Text")?.ToString());
        Assert.AreEqual(string.Empty, output.GetDependencyPropertyValue("Text")?.ToString());

        {
            _app.Tap(clearButton);
            _app.WaitForDependencyPropertyValue(output, "Text", 0);
            TakeScreenshot("Clear Button");
        }

        {
            _app.Tap(addButton);
            _app.WaitForDependencyPropertyValue(output, "Text", 1);
            TakeScreenshot("Add Button");
        }

        {
            _app.Tap(containsButton);
            _app.WaitForDependencyPropertyValue(output, "Text", "True");
            TakeScreenshot("Contains Button");
        }

        {
            _app.Tap(removeButton);
            _app.WaitForDependencyPropertyValue(output, "Text", 0);
            TakeScreenshot("Remove Button");
        }
    }
}
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-ai-agents.md

---
uid: Uno.UI.CommonIssues.AIAgents
---

# Issues related to AI Agents

## dnx is not a valid command

The getting started for Claude, Codex, and Copilot CLI use the `dnx` command, which is only available on .NET 10.

If you want to use the App MCP with .NET 9 projects, you'll need to change `dnx` to `uno-devserver` and install it using `dotnet tool install -g uno.devserver`.

## The App MCP does not appear in Visual Studio

1. Open the `.vs/mcp.json` file in Visual Studio. It is located in your solution's root directory.
2. Verify that the Uno MCP server entry is present:

    ```json
    "uno": {
      "url": "https://mcp.platform.uno/v1"
    }
    ```

3. If the entry is missing, add it to the `.vs/mcp.json` file and restart Visual Studio.
4. If the entry exists but the server shows as disconnected, click on "Reconnect" in the file editor:

![Visual Studio MCP reconnect in mcp.json](Assets/vs-mcp-reconnect.png)

The Uno App MCP should now appear in the list of MCPs in Visual Studio.

## The App MCP turns red in Visual Studio 2022/2026

In Visual Studio, the App MCP might turn red on some occasions. To fix this issue, click on the three dots on the right and select `Reload`.

## The uno-app MCP failed to start

The Uno Platform App MCP may fail to start in Claude/Codex/Copilot CLI when it is started in a folder that does not contain an Uno Platform project.

To fix this issue, change directories to a folder that contains the `.sln` or `.slnx` file of your project.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-all-ides.md

---
uid: Uno.UI.CommonIssues.AllIDEs
---

# Issues related to all development environments

## Could not resolve SDK "Uno.Sdk"

This error may happen for multiple reasons:

- Make sure to update your [Uno Platform extension](https://aka.platform.uno/vs-extension-marketplace) in VS 2022 to 5.3.x or later. Earlier versions may automatically update to an incorrect version of the Uno.SDK.
- Make sure to [re-run Uno.Check](xref:UnoCheck.UsingUnoCheck) to get all the latest dependencies.
- Ensure that all [NuGet feeds are authenticated properly](https://learn.microsoft.com/nuget/consume-packages/consuming-packages-authenticated-feeds). When building on the command line, some enterprise NuGet feeds may not be authenticated properly.
- Ensure that no global package mappings are interfering with nuget restore. To validate that no package mappings are set, on Windows for Visual Studio:
  - Make a backup copy of `%AppData%\NuGet\NuGet.Config`
  - Open a visual studio instance that does not have any solution opened
  - Go to **Tools**, **Options**, **NuGet Package Manager**, then **Package Source Mappings**
  - If there are entries in the list, click then click **Remove All**
- Delete the `Uno.Sdk` folder in your development environment's Nuget packages `global-packages` folder:
  - Windows: `%userprofile%\.nuget\packages`
  - Mac/Linux: `~/.nuget/packages`
  [This folder may be overridden](https://learn.microsoft.com/en-us/nuget/consume-packages/managing-the-global-packages-and-cache-folders) using the `NUGET_PACKAGES` environment variable, the `globalPackagesFolder` or `repositoryPath` configuration settings (when using PackageReference and `packages.config`, respectively), or the `RestorePackagesPath` MSBuild property (MSBuild only). The environment variable takes precedence over the configuration setting.

Try building your project again.

## Runtime error `No parameterless constructor defined for XXXX`

This error is generally caused by some missing [IL Linker](https://github.com/dotnet/runtime/tree/main/src/tools/illink) configuration on WebAssembly. You may need to add some of your application assemblies in the LinkerConfig.xml file of your project. You can find [additional information in the documentation](xref:uno.articles.features.illinker).

Similar error messages using various libraries:

- `Don't know how to detect when XXX is activated/deactivated, you may need to implement IActivationForViewFetcher` (ReactiveUI)

## `Layout cycle detected` exception

Layout cycle means that the measuring of a specific part of the visual tree couldn't get stabilized. For example, during an element `Arrange` pass, its measure was invalidated, then it's measured again then arranged, and the app will fall into a layout cycle.

Uno Platform and WinUI run this loop for 250 iterations. If the loop hasn't stabilized, the app will fail with an exception with the message `Layout cycle detected`. For more information, see also [LayoutCycleTracingLevel in Microsoft Docs](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.debugsettings.layoutcycletracinglevel). Note that what Uno Platform logs may be quite different from what WinUI logs.

This error is sometimes tricky to debug. To get more information, in your `App.OnLaunched` method, you can call `DebugSettings.LayoutCycleTracingLevel = Microsoft.UI.Xaml.LayoutCycleTracingLevel.High` in order to get additional troubleshooting information printed out in the app's logs. You will also need to update your logging to `.SetMinimumLevel(LogLevel.Trace)`, as well as add `builder.AddFilter("Microsoft.UI.Xaml.UIElement", LogLevel.Trace);` if you set the log level to high and want to get stack trace information.

When the last 10 iterations out of 150 are reached, we will start logging some information as warnings. Those logs are prefixed with `[LayoutCycleTracing]` and include information such as when an element is measured or arranged, and when measure or arrange is invalidated.

One possible cause of layout cycle is incorrect usage of `LayoutUpdated` event. This event isn't really tied to a specific `FrameworkElement` and is fired whenever any element changes its layout in the visual tree. So, using this event to add or remove an element to the visual tree can lead to layout cycle. The simplest example is having XAML similar to the following

```xaml
<StackPanel x:Name="sp" LayoutUpdated="sp_LayoutUpdated" />
```

and code behind:

```csharp
private void sp_LayoutUpdated(object sender, object e)
{
    sp.Children.Add(new Button() { Content = "Button" });
}
```

In this case, when `LayoutUpdated` is first fired, you add a new child to the `StackPanel` which will cause visual tree root to have its measure invalidated, then `LayoutUpdated` gets fired again, causing visual tree root to have its measured invalidated again, and so on. This ends up causing a layout cycle.

## Cannot build with both Uno.WinUI and Uno.UI NuGet packages referenced

This issue generally happens when referencing an Uno.UI (using WinUI APIs) NuGet package in an application that uses Uno.WinUI (Using WinAppSDK APIs).

For instance, if your application has `<PackageReference Include="Uno.WinUI"` in the `csproj` files, this means that you'll need to reference WinUI versions of NuGet packages.

For instance:

- `Uno.UI` -> `Uno.WinUI`

## Abnormally long build times when using Roslyn analyzers

It is a good practice to use Roslyn analyzers to validate your code during compilation, but some generators may have difficulty handling the source generated by the Uno Platform (one notable example is [GCop](https://github.com/Geeksltd/GCop)). You may need to disable those for Uno projects or get an update from the analyzer's vendor.

## Build errors with .NET workloads

If you encounter errors such as: `error MSB4022: The result "" of evaluating the value "$(MonoTargetsTasksAssemblyPath)" of the "AssemblyFile" attribute in element <UsingTask> is not valid.`, this usually indicates a problem with your .NET workloads installation. If `uno-check` does not report issues but your project still fails to build, try running:

  ```dotnetcli
  dotnet workload repair
  ```

This command can repair missing or misconfigured workload components.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-android.md

---
uid: Uno.UI.CommonIssues.Android
---

# Issues related to Android projects

## Insets not working when using WebView

There is a known issue on Android with the [Edge-to-Edge](https://developer.android.com/develop/ui/views/layout/edge-to-edge) feature, where the bottom Insets do not function correctly when using a WebView. This flaw prevents the inputs from being shifted upward, which results in the keyboard covering them.

> [!IMPORTANT]
> Edge-to-Edge is enforced on devices running Android 15 with a Target SDK of 35 or higher.

A workaround for this issue is to navigate to the `MainActivity.Android.cs` file in your Uno Platform application, override the `OnCreate` method, and call `WindowCompat.SetDecorFitsSystemWindows()`, setting the second parameter, decorFitsSystemWindows, to true.

Your code should be structured as follows:

```csharp
public class MainActivity : Microsoft.UI.Xaml.ApplicationActivity
{
  protected override void OnCreate(Bundle bundle)
  {
      base.OnCreate(bundle);
      WindowCompat.SetDecorFitsSystemWindows(Window, true);
  }
}
```

Learn more about this issue [on Google's issues tracker](https://issuetracker.google.com/issues/311256305?pli=1) website.

> [!IMPORTANT]
> Using the workaround mentioned above will deactivate some benefits of the Edge-To-Edge feature. For instance, your top navigation bar will no longer be "invisible," which removes the immersive appearance associated with edge-to-edge design.

## ADB0020 - The package does not support the CPU architecture of this device

This error may occur when deploying an application to a physical device with ARM architecture. To resolve this issue, you will need to add the following to your csproj anywhere inside the `<PropertyGroup>` tag:

```xml
  <RuntimeIdentifiers Condition="$(TargetFramework.Contains('-android'))">android-arm;android-arm64;android-x86;android-x64</RuntimeIdentifiers>
```

## Deploying an Android app takes a long time

Android deployment requires a few considerations:

- Android physical device
  - Make sure to have a good cable (USB 3 or C) to have a good connection
  - Avoid debugging through wifi
- Android Emulators
  - Use an Android x86_64 emulator. If not, [create a new one](https://learn.microsoft.com/dotnet/maui/android/emulator/device-manager).
  - Ensure that you have either Hyper-V or AEHD enabled. (See [Microsoft's documentation](https://learn.microsoft.com/dotnet/maui/android/emulator/hardware-acceleration))
  - Try disabling `Fast Deployment` in your app configuration
        1. Open your project properties
        1. In the Android section, search for `Fast Deployment`
        1. Uncheck all target platforms
- Try setting `<EmbedAssembliesIntoApk>false</EmbedAssembliesIntoApk>` in the debug configuration of your `.csproj`.

## Android Warning XA4218

When building for Android, the following messages may happen:

```text
obj\Debug\net8.0-android\android\AndroidManifest.xml : warning XA4218: Unable to find //manifest/application/uses-library at path: C:\Program Files (x86)\Android\android-sdk\platforms\android-34\optional\androidx.window.extensions.jar
obj\Debug\net8.0-android\android\AndroidManifest.xml : warning XA4218: Unable to find //manifest/application/uses-library at path: C:\Program Files (x86)\Android\android-sdk\platforms\android-34\optional\androidx.window.sidecar.jar
```

Those messages are from a [known .NET for Android issue](https://github.com/xamarin/xamarin-android/issues/6809) and can be ignored as they are not impacting the build output.

## Additional troubleshooting

You can get additional build [troubleshooting information here](xref:Uno.Development.Troubleshooting).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-ios.md

---
uid: Uno.UI.CommonIssues.Ios
---

# Issues related to iOS projects

## Developing on older Mac hardware

The latest macOS release and Xcode version are required to develop with Uno Platform for iOS. However, if you have an older Mac that does not support the latest macOS release, you can use a third-party tool to upgrade it, such as [OpenCore Legacy Patcher](https://dortania.github.io/OpenCore-Legacy-Patcher/). While not ideal, this can extend the use of older hardware by installing the latest macOS release on it. Please note that this method is not required when developing for other targets such as Android, Skia, WebAssembly, or Windows.

## `Don't know how to marshal a return value of type 'System.IntPtr'`

[This issue](https://github.com/unoplatform/uno/issues/9430) may happen for Uno.UI 4.4.20 and later, when deploying an application using the iOS Simulator, when the application contains a `TextBox`.

In order to fix this, add the following to your `.csproj`:

```xml
<PropertyGroup>
  <MtouchExtraArgs>$(MtouchExtraArgs) --registrar=static</MtouchExtraArgs>
</PropertyGroup>
```

## Error while retrieving iOS device in VS code

When switching to an iOS debugging target in VS Code, you might encounter an error stating that the iOS device could not be retrieved. The error message may appear as follows:

```error
[Info]: Project reload forced to switch to net8.0-ios | Debug
[Error] Could not retrieve ios devices within 10 seconds. Aborting...
```

To resolve this issue, download [Xcodes](https://www.xcodes.app). Inside Xcodes.app, select the correct version of Xcode and click the **Make Active** button to make it the default Xcode for your Mac. After completing this step, you can speed up the process and use the new default Xcode for simulators. On VS Code, open the Command Palette and select `Developer: Reload Window`. This should resolve the error when switching to an iOS debugging target in VS Code.

## Build stops with `Verification of iOS environment is running. Please try again in a moment`

When building for an iOS physical device, the following error may happen in your build `Verification of iOS environment is running. Please try again in a moment.`. If this happens and your Visual Studio is connected to your Mac, you may need to ensure that you have selected a provisioning profile.

Make sure to [configure your Apple account](https://learn.microsoft.com/en-us/dotnet/maui/ios/device-provisioning/automatic-provisioning?view=net-maui-9.0#enable-automatic-provisioning), or in some cases, selecting the development team and provisioning profile is required.

## Debugging takes a long time when connecting from a Windows machine

In case your debugging experience is slow when connecting from a Windows VS environment to a Mac machine, make sure that you're not connected through Wifi on either end. Try pinging your Mac from your Windows machine and ensure it's lower than 5ms.

## Additional troubleshooting

You can get additional build [troubleshooting information here](uno-builds-troubleshooting.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-mobile-debugging.md

---
uid: Uno.UI.CommonIssues.MobileDebugging
---

# Android & iOS emulators: setup & troubleshooting

If Android or iOS emulators are missing or fail to start in JetBrains Rider, Visual Studio, or Visual Studio Code on macOS or Windows, use the checklists and setup paths below.

## Quick-fix checklist (do this first)

- **Start the emulator manually** once, then reopen your IDE.
- **Update tools & images** (Android Emulator, Platform-Tools, system images).
- **Use one Android SDK location** across tools; avoid cloud-synced folders.
- **Windows:** ensure virtualization is enabled (see “Windows virtualization”).
- **ADB refresh:** `adb kill-server && adb start-server`, then `adb devices`.
- **AVD reset:** Cold Boot or Wipe Data for a flaky AVD.
- **macOS/iOS:** open the iOS Simulator from Xcode once to initialize it.
- After changing SDKs, emulator images, or virtualization settings, **restart your IDE** so it refreshes its device list.

## Android emulator setup

There are several common ways to manage Android Virtual Devices (AVDs):

### Option 1 — Android Studio (works with all IDEs)

1. Install the latest Android Studio.
2. **Tools → SDK Manager → SDK Tools**: update **Android Emulator** and **Android SDK Platform-Tools**.
3. **Tools → Device Manager (AVD Manager)**: create/update an AVD with a recent system image.
4. Launch the emulator, then run your Uno Platform app from your IDE.

### Option 2 — Visual Studio

1. Install Visual Studio 2022/2026 with the **Multi-Platform App UI development with .NET** workload.
2. Open **Tools → Android → Android Device Manager**.
3. Create/update an AVD and start it before you deploy from your IDE.

### Option 3 — JetBrains Rider

1. Install **Rider** and the **Android Support** plugin via **Preferences/Settings → Plugins → Marketplace**.
2. From Rider’s Device/AVD Manager, create/update an AVD (you can reuse AVDs made in Android Studio).
3. If Rider doesn’t list it immediately, start the AVD manually and restart Rider.

### Option 4 — Visual Studio Code

> VS Code doesn’t include a built-in AVD manager. It **uses AVDs created by Android Studio, Rider, or Visual Studio** and can start them via extensions or the terminal.

1. **Install/verify Android SDK & tools**
   - Create AVDs in **Android Studio** (recommended) or another IDE.
   - Ensure command-line tools are available in your `PATH` (e.g., `<sdk>/platform-tools` and `<sdk>/emulator`).
   - Optional: confirm the .NET Android workload is present: `dotnet workload list` (look for `android`).

2. **Start an emulator**
   - Use an extension (e.g., an “Android/iOS Emulator” helper) to start/stop AVDs from the Command Palette, **or**
   - Use the terminal:

     ```bash
     emulator -list-avds
     emulator -avd <your_avd_name>
     adb devices
     ```

3. **Make VS Code see the device**
   - **Reload Window** after the emulator starts, or restart VS Code.
   - If the emulator isn’t listed, verify `adb devices` shows it, then relaunch the debugger.

4. **Troubleshooting in VS Code**
   - Ensure `ANDROID_SDK_ROOT` (or `ANDROID_HOME`) points to the correct SDK.
   - Keep only **one** SDK location across tools to avoid a mismatch.
   - If an extension can’t find the emulator, set the SDK/emulator path in its settings.

---

## Windows virtualization (required for fast Android emulation)

Enable **Windows Hypervisor Platform** (and **Hyper-V** on supported editions), then **reboot**. Avoid conflicts with other hypervisors (e.g., VirtualBox in non-Hyper-V mode).

## iOS simulator setup (macOS only)

1. Install the latest **Xcode** from the App Store and launch it once to accept the license.
2. Verify the Simulator runs: **Xcode → Window → Devices and Simulators**.
3. If your IDE can’t find the Simulator, **start it manually** or **reboot**.
4. Inspect available simulators:

   ```bash
   xcrun simctl list devices
   ```

## SDK location

- Keep your **Android SDK** and **AVD** directories **outside** cloud-sync folders (OneDrive/iCloud/Dropbox) to avoid file-locking and partial syncs.
- Verify or change the SDK path in **Android Studio**:
  - **macOS:** *Preferences → Appearance & Behavior → System Settings → Android SDK*
  - **Windows/Linux:** *File → Settings → Appearance & Behavior → System Settings → Android SDK*
- Use a **single SDK location** across all tools (Android Studio, Rider, VS/VS Code).
- Set environment variables so CLIs and IDEs agree:
  - **`ANDROID_SDK_ROOT`** (recommended) or **`ANDROID_HOME`** (legacy).
- Typical locations:
  - **macOS:** `~/Library/Android/sdk`
  - **Windows:** `%LOCALAPPDATA%\Android\Sdk` (or a custom `C:\Android\Sdk`)
  - **Linux:** `~/Android/Sdk`
  - **AVDs:** `~/.android/avd` (macOS/Linux) or `%USERPROFILE%\.android\avd` (Windows)
- After moving or changing SDKs/AVDs, **restart your IDE** so it refreshes device lists.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-rider.md

---
uid: Uno.UI.CommonIssues.rider
---

# Issues related to Rider

You can view the [list of known issues in Rider's bug tracker](https://github.com/unoplatform/uno/issues/15226).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-skia.md

---
uid: Uno.UI.CommonIssues.Skia
---

# Issues related to Skia-based projects

## System.DllNotFoundException: Gtk: libgtk-3-0.dll

When running the Skia.GTK project head, the following error may happen:

```console
Unhandled exception. System.TypeInitializationException: The type initializer for 'Gtk.Application' threw an exception.
---> System.DllNotFoundException: Gtk: libgtk-3-0.dll, libgtk-3.so.0, libgtk-3.0.dylib, gtk-3.dll
```

## Linux

[!include[linux-setup](includes/additional-linux-setup-inline.md)]

## Additional troubleshooting

You can get additional build [troubleshooting information here](uno-builds-troubleshooting.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-vs2022.md

---
uid: Uno.UI.CommonIssues.vs2022
---

# Issues related to Visual Studio 2022/2026

## Unable to select the `MyApp (Unpackaged WinAppSDK)` profile

A [Visual Studio issue](https://developercommunity.visualstudio.com/t/WinAppSDK-Unpackaged-profile-cannot-be-s/10643735) is preventing the Unpackaged profile if iOS/Android target frameworks are present in the project. In order for the unpackaged profile to be selected, you'll need to edit the `Properties/launchSettings.json` file to remove the `MyApp (Packaged WinAppSDK)` entry. Once it is removed, select the `MyApp (Unpackaged WinAppSDK)` then start the debugging of your app.

## An iOS fails to run with `No class inheriting from a valid Application Delegate found`

When using iOS Hot Restart on Visual Studio 2022/2026, a [limitation of the environment](https://developercommunity.visualstudio.com/t/iOS-Hot-Restart-does-not-work-for-non-MA/10714660) prevents an Uno Platform app from starting properly when MAUI Embedding is referenced.

A workaround is to disable MAUI Embedding in the [`UnoFeatures` of your project](xref:Uno.Features.Uno.Sdk#uno-platform-features).

## App builds in Visual Studio 2022/2026 are taking a long time

Take a [look at our article](xref:Build.Solution.TargetFramework-override) in order to ensure that your solution is building and showing intellisense as fast as possible, and to avoid [this Visual Studio issue](https://developercommunity.visualstudio.com/t/Building-a-cross-targeted-project-with-m/651372?space=8&q=building-a-cross-targeted-project-with-many-target) (help the community by upvoting it!) where multi-targeted project libraries always build their full set of targets.

## My app is not running as fast as I want

There could be many reasons for being in this situation, but we've built a list of performance tips in [this article](xref:Uno.Development.Performance) that you can apply to your app. If you haven't found your answer, open a [discussion](https://github.com/unoplatform/uno/discussions) to tell us about it!

## C# Hot Reload troubleshooting

C# Hot Reload is provided by Visual Studio 2022/2026, and there may be occasions where updates are not applied, or the modified code is incorrectly reported as not compiling.

If that is the case:

- Make sure that the top left selector in the C# editor is showing the project head being debugged. For instance, if debugging with `net9.0-desktop`, select the `net9.0-desktop` project.
- Try recompiling the application completely (with the `Rebuild` command)

More troubleshooting information is available [in this section](xref:Uno.Features.HotReload).

## error NETSDK1148: A referenced assembly was compiled using a newer version of Microsoft.Windows.SDK.NET.dll

See [this article](features/winapp-sdk-specifics.md#adjusting-windows-sdk-references) to solve this issue.

### My application does not start under WSL

Your application may fail to run under WSL for multiple reasons:

- Your app is in a path that contains spaces and/or characters such as `[` or `]`
- [WSLg](xref:Uno.GetStarted.vs2022#additional-setup-for-windows-subsystem-for-linux-wsl) has not been installed
- [X11 dependencies](xref:Uno.GetStarted.vs2022#additional-setup-for-skia-desktop-projects) have not been installed

### New Projects in Existing Solutions

Creating a new Uno Platform project inside an existing solution that wasn’t originally created with “Place solution and project in the same directory” is not supported by the `unoapp` templates. You can work around this by following the guide: [Adding Platforms to an Existing Project](xref:Uno.Guides.AddAdditionalPlatforms).

## Legacy issues

### The XAML editor shows `The type 'page' does not support direct content` message

This issue has been fixed in Visual Studio 17.8 and later.

If you're using an earlier version, XAML Intellisense [is not working properly](https://developercommunity.visualstudio.com/content/problem/587980/xaml-intellisense-does-not-use-contentpropertyattr.html) in Visual Studio when the active target framework is not the WinAppSDK one.

To work around this issue, close all XAML editors, open a C# file and select the '[MyApp].Windows' in the top-left drop-down list of the text editor sector. Once selected, re-open the XAML file.

### `InitializeComponent` or `x:Name` variable is not available in code-behind

This issue has been fixed in Visual Studio 17.8 and later.

If you're using an earlier version, Visual Studio [does not refresh the intellisense cache](https://developercommunity.visualstudio.com/content/problem/588021/the-compile-itemgroup-intellisense-cache-is-not-re.html) properly, causing variables to be incorrectly defined.

To fix this issue, build your project once, close the solution and reopen it.

It is also important to note that Uno Platform uses a multi-project structure, for which each project has to be build individually for errors to disappear from the **Error List** window (notice the **Project** column values).

In order to clear the **Error List** window, build the whole solution completely once. Thereafter, build a specific project and prefer the use of the **Output** tool window (in the menu **View** -> **Output**), taking build messages by order of appearance.

### Event handler cannot be added automatically

Event handlers [cannot be automatically](https://github.com/unoplatform/uno/issues/1348#issuecomment-520300471) added using the XAML editor.

A workaround is to use the [`x:Bind` to events feature](features/windows-ui-xaml-xbind.md#examples). This feature allows to use a simpler syntax like `<Button Click="{x:Bind MyClick}" />` and declare a simple method `private void MyClick() { }` in the code-behind.

### WebAssembly: Hot Reload fails to start with Mixed Content: The page at XXX was loaded over HTTPS, but attempted to connect to the insecure WebSocket endpoint

This issue is caused by visual studio enforcing https connections for local content. You can work around this by either:

- Removing the https endpoint in the `Properties/launchSettings.json` file
- Unchecking the `Use SSL` option in the project's Debug launch profiles
- Selecting the project name instead of IISExpress in the toolbar debug icon drop down list

### Error MSB3030: Could not copy the file "MyProject.Shared\MainPage.xbf" because it was not found

This issue is present in Visual Studio 17.2 and 17.3, and can be addressed by [taking a look at this issue](https://github.com/unoplatform/uno/discussions/5007#discussioncomment-2583741).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-vscode.md

---
uid: Uno.UI.CommonIssues.vscode
---

# Issues related to VS Code

## Known limitations for VS Code support

- C# Debugging is not supported when running in a remote Linux Container, Codespaces.
- Calls to `InitializeComponent()` may show intellisense errors until the Windows head has been built once.

## Troubleshooting Uno Platform VS Code issues

For assistance configuring or running Android or iOS emulators, see the [Android & iOS emulator troubleshooting guide](xref:Uno.UI.CommonIssues.MobileDebugging).

If you're not sure whether your environment is correctly configured for Uno Platform development, running the [`uno-check` command-line tool](external/uno.check/doc/using-uno-check.md) should be your first step.

The Uno Platform extension provides multiple output windows to troubleshoot its activities:

- **Uno Platform**, which indicates general messages about the extension
- **Uno Platform - Debugger**, which provides activity messages about the debugger feature
- **Uno Platform - Hot Reload**, which provides activity messages about the Hot Reload feature
- **Uno Platform - XAML**, which provides activity messages about the XAML Code Completion feature

![Extension Outputs](Assets/quick-start/vs-code-extension-outputs.png)

They are also accessible using the status bar Uno logo: hover your mouse pointer over the logo, and the extension status will be shown along with links to the related outputs.

![Extension Status](Assets/quick-start/vs-code-extension-status.png)

If the extension is not behaving properly, try using the `Developer: Reload Window` (or `Ctrl+R`) command in the palette.

## Reporting issues

You can report issues directly from VS Code by either:

- using the Uno logo status bar (see screenshot above); or
- pressing `F1` and selecting `Uno Platform: Report Issue...`

The form is already pre-filled with some useful information to help diagnose issues.
Follow the comments to complete the report.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues-wasm.md

---
uid: Uno.UI.CommonIssues.Wasm
---

# Issues related to WebAssembly projects

## WebAssembly: DllImport unable to load library 'libSkiaSharp'

If you're getting the following message in the browser debugger:

```text
[MONO] DllImport unable to load library 'libSkiaSharp'.
```

Here are a few ways to fix this:

- Make sure that you've run [`uno-check`](xref:UnoCheck.UsingUnoCheck) and that the `dotnet workload list` shows the `wasm-tools` workload. If you're using Visual Studio, make sure to restart it if you've installed workloads.
- If you've run `dotnet publish`, make sure to use the `bin\Release\netX.0-browserwasm\publish\wwwroot` folder to serve your app. Make sure to visit [our publishing docs](xref:uno.publishing.overview) for more information.

## Mixed Content, this request has been blocked

When running a webassembly app under WebAssembly with HTTPS the following error may happen:

```text
Mixed Content: The page at 'https://localhost:5002' was loaded over HTTPS, but attempted to 
connect to the insecure WebSocket endpoint 'ws://XXXX:59867/rc'. This request has been blocked;
this endpoint must be available over WSS.
```

In order to fix this issue, you may need to apply the [HTTPS fixes](xref:Uno.Guides.UsingTheServerProject#adjusting-for-https) mentioned in the server project documentation.

## WebAssembly: Access to fetch at 'https://XXXX' from origin 'http://XXXX' has been blocked by CORS policy

This is a security restriction from the JavaScript `fetch` API, where the endpoint you're calling needs to provide [CORS headers](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) to work properly.

If you control the API, you'll need to use the features from your framework to enable CORS, and if you don't you'll need to ask the maintainers of the endpoint to enable CORS.

To test if CORS is really the issue, you can use [CORS Anywhere](https://cors-anywhere.herokuapp.com/) to proxy the queries.

### Build error `Failed to generate AOT layout`

When building for WebAssembly with AOT mode enabled, the following error may appear:

```console
Failed to generate AOT layout (More details are available in diagnostics mode or using the MSBuild /bl switch)
```

To troubleshoot this error, you can change the text output log level:

- Go to **Tools**, **Options**, **Projects and Solution**, then **Build and Run**
- Set **MSBuild project build output verbosity** to **Normal** or **Detailed**
- Build your project again and take a look at the additional output next to the `Failed to generate AOT layout` error

You can get additional build [troubleshooting information here](uno-builds-troubleshooting.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/common-issues.md

---
uid: Uno.UI.CommonIssues
---

# Troubleshooting

The Uno Platform features and support are constantly evolving, yet you may encounter some of the issues while building your application, for which answers and details are available below.

[!include[getting-help](includes/getting-help.md)]

A better resource for high-level questions about Uno Platform is the [general FAQ](xref:Uno.Development.FAQ).

## Hot Reload

When using Hot Reload, ensure you first review the [supported features](xref:Uno.Features.HotReload#features), [supported features per OS](xref:Uno.Features.HotReload#supported-features-per-os), and [supported features per platform](xref:Uno.Features.HotReload#supported-features-per-platform).

If issues persist, additional troubleshooting information is available in [this section](xref:Uno.Features.HotReload#troubleshooting).

## Development Environments

- [All Development Environments](xref:Uno.UI.CommonIssues.AllIDEs)
- [Visual Studio 2022/2026 for Windows](xref:Uno.UI.CommonIssues.vs2022)
- [VS Code](xref:Uno.UI.CommonIssues.vscode)
- [Rider](xref:Uno.UI.CommonIssues.rider)
- [AI Agents](xref:Uno.UI.CommonIssues.AIAgents)

## Platforms

- [Common issues on WebAssembly](xref:Uno.UI.CommonIssues.Wasm)
- [Common issues on Skia (X11/macOS/Framebuffer/Windows)](xref:Uno.UI.CommonIssues.Skia)
- [Common issues on iOS](xref:Uno.UI.CommonIssues.Ios)
- [Common issues on Android](xref:Uno.UI.CommonIssues.Android)

## Build Errors

- [Troubleshooting build errors](xref:Uno.Development.Troubleshooting)
- [Build error codes](xref:Build.Solution.error-codes)

## Next Steps

Learn more about:

- You can head to [How-tos and tutorials](xref:Uno.Tutorials.Intro) on how to work on your Uno Platform app.
- [List of views implemented in Uno](implemented-views.md) for the set of available controls and their properties.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/community-tutorials.md

---
uid: Uno.Tutorials.CommunityTutorials
---

# Community Tutorials

This page lists links to our community provided tutorials.

> [!NOTE]
> Please use this page to submit links to your blogs, articles, and other resources as community contribution to Uno Platform Advocacy.

- [A Quick Look at Uno Platform Development](https://jamesmccaffrey.wordpress.com/2021/05/31/a-quick-look-at-uno-platform-development/), by James D. McCaffrey.
- [Why I wrote (and you should buy) a book about Uno Platform when there are free resources available](https://www.mrlacey.com/2022/02/why-i-wrote-and-you-should-buy-book.html), by Matt Lacey
- [Uno Platform Getting Started with New Projects](https://www.andrewhoefling.com/Blog/Post/uno-platform-getting-started-with-new-projects), by Skye Hoefling
- [Uno Platform - Build a Todo App - Part 5](https://steven-giesel.com/blogPost/2c025ac6-d67f-45ec-a616-009e0285c999), by Steven Giesel
- [Uno Platform on Surface Duo](https://devblogs.microsoft.com/surface-duo/tag/uno-platform/), by Craig Dunn
- [Introduction to Uno Platform](https://ronicasingh.hashnode.dev/introduction-to-uno-platform), by Ronica Singh
- [Creating your First Uno Platform Application](https://ronicasingh.hashnode.dev/creating-your-first-uno-platform-application), by Ronica Singh
- [Uno Platform and its Fluent app design](https://ronicasingh.hashnode.dev/uno-platform-and-its-fluent-app-design), by Ronica Singh
- _Create a PR tp add yours here!_

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/compass.md

---
uid: Uno.Features.Compass
---

# Compass

> [!TIP]
> This article covers Uno-specific information for `Compass`. For a full description of the feature and instructions on using it, see [Compass Class](https://learn.microsoft.com/uwp/api/windows.devices.sensors.Compass).

* The `Windows.Devices.Sensors.Compass` class returns a heading with respect to Magnetic North and, possibly, True North.

## Supported features

| Feature          | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `GetDefault`     | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `ReadingChanged` | ✔       | ✔       | ✔   | ✔          | ✖     | ✖            | ✖            |
| `ReportInterval` | ✔       | ✔       | ✔   | ✖          | ✖     | ✖            | ✖            |

## Using Compass with Uno

* The `GetDefault` method is available on all targets and will return `null` on those which do not support `Compass` or devices that do not have such a sensor.
* Ensure to unsubscribe from the `ReadingChanged` event when you no longer need the readings, so that the sensor is no longer active to avoid unnecessary battery consumption.

## Platform-specific

### Android

If you are planning to use the `HeadingTrueNorth`, your app must declare `android.permission.ACCESS_FINE_LOCATION` permission, otherwise the value will return `null`:

```csharp
[assembly: UsesPermission("android.permission.ACCESS_FINE_LOCATION")]
```

> [!NOTE]
> Android lacks a dedicated API for accessing the compass heading. Uno Platform utilizes the accelerometer and magnetometer sensors to calculate the magnetic north heading, a method endorsed by Google.
>
> In rare cases, you may encounter inconsistent results due to the need for sensor calibration. The process of recalibrating the compass on Android varies across phone models and Android versions. To recalibrate, consult online resources specific to your device. Here are two links that may assist you in recalibrating the compass:
>
> [Google Help Center: Find and improve your location’s accuracy](https://support.google.com/maps/answer/2839911)
> [Stack Exchange Android Enthusiasts: How can I calibrate the compass on my phone?](https://android.stackexchange.com/questions/10145/how-can-i-calibrate-the-compass-on-my-phone)
>
> It's also important to note that concurrently running multiple sensors in your app may impact sensor speed.

### Web (WASM)

The `Magnetometer` sensor is not currently supported by default on any of the popular browsers. However, users can enable this feature on some browsers. For more information on how to do this, please visit the [Mozilla documentation](https://developer.mozilla.org/en-US/docs/Web/API/Magnetometer) on using the Magnetometer API.

## Example

### Capturing sensor readings

```csharp
var compass = Compass.GetDefault();
compass.ReadingChanged += Compass_ReadingChanged;

private async void Compass_ReadingChanged(Compass sender, CompassReadingChangedEventArgs args)
{
    // If you want to update the UI in some way, ensure the Dispatcher is used,
    // as the ReadingChanged event handler does not run on the UI thread.
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        OutputTextBlock.Text = $"HeadingMagneticNorth in degrees = {args.Reading.HeadingMagneticNorth}, " +
            $"HeadingTrueNorth in degrees = {args.Reading.HeadingTrueNorth}, "
            $"timestamp = {args.Reading.Timestamp}";
    });
}
```

### Unsubscribing from the readings

```csharp
Compass.ReadingChanged -= Compass_ReadingChanged;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/composition.md

---
uid: Uno.Development.Composition
---

# Composition API

Composition Visuals make up the visual tree structure which all other features of the composition API use and build on.
The API allows developers to define and create one or many visual objects each representing a single node in a visual tree.

To get more info, you can refer to [Microsoft's documentation](https://learn.microsoft.com/windows/uwp/composition/composition-visual-tree).

Uno Platform currently supports a small number of the APIs in the [`Windows.UI.Composition` namespace](https://learn.microsoft.com/uwp/api/windows.ui.composition?view=winrt).

The rest of this article details Uno-specific considerations regarding Composition API.

**On Android, most composition features are functional only for Android 10 (API 29) and above.**

## Compositor Thread [Android]

On Android, the composition refers to the [`Draw`](https://developer.android.com/reference/android/view/View#draw(android.graphics.Canvas)) and [`OnDraw`](https://developer.android.com/reference/android/view/View#onDraw(android.graphics.Canvas)) methods.
To get more info about custom drawing on Android, you can refer to the [Android's documentation](https://developer.android.com/training/custom-views/custom-drawing).

By default, those methods are invoked on the UI Thread.

With Uno, you can request to run those methods on a dedicated thread by setting in your Android application's constructor:

```csharp
Uno.CompositionConfiguration.Configuration = Uno.CompositionConfiguration.Options.Enabled;
```

This thread will also be used for [independent animations](https://learn.microsoft.com/windows/uwp/design/motion/storyboarded-animations#dependent-and-independent-animations).

**When overriding the `[On]Draw` methods, it is very important not to access any state that can be edited from the UI Thread, including any `DependencyProperty`.**
**Instead, you should capture the state of your control into a `RenderNode` during the `ArrangeOverride` and render it on the provided `Canvas`.**

_There are a few known issues associated with the used of the compositor thread, [make sure to read the section below](#known-issues)._

## Brush Anti-aliasing [Skia Backends]

On Skia Desktop targets (X11, Framebuffer, macOS, and Windows), anti-aliasing is disabled by default for brushes, You can request it to be anti-aliased by setting this in your application's constructor:

```csharp
#if HAS_UNO
    Uno.CompositionConfiguration.Configuration |= Uno.CompositionConfiguration.Options.UseBrushAntialiasing;
#endif
```

Or alternatively, if you want to enable all available Composition capabilities:

```csharp
#if HAS_UNO
    Uno.CompositionConfiguration.Configuration = Uno.CompositionConfiguration.Options.Enabled;
#endif
```

## Implemented APIs [Skia Backends]

### Windows.UI.Composition

- [CompositionAnimation](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionanimation)
- [CompositionBackdropBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionbackdropbrush)
- [CompositionBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionbrush)
- [CompositionCapabilities](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioncapabilities)
- [CompositionClip](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionclip)
- [CompositionColorBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioncolorbrush)
- [CompositionEffectBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioneffectbrush)
- [CompositionEffectFactory](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioneffectfactory)
- [CompositionEffectSourceParameter](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositioneffectsourceparameter)
- [CompositionEllipseGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionellipsegeometry)
- [CompositionGeometricClip](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositiongeometricclip)
- [CompositionGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositiongeometry)
- [CompositionGradientBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositiongradientbrush)
- [CompositionLinearGradientBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionlineargradientbrush)
- [CompositionLineGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionlinegeometry)
- [CompositionMaskBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionmaskbrush)
- [CompositionNineGridBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionninegridbrush)
- [CompositionObject](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionobject)
- [CompositionPath](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionpath)
- [CompositionPathGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionpathgeometry)
- [CompositionPropertySet](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionpropertyset)
- [CompositionRadialGradientBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionradialgradientbrush)
- [CompositionRectangleGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionrectanglegeometry)
- [CompositionRoundedRectangleGeometry](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionroundedrectanglegeometry)
- [CompositionShape](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionshape)
- [CompositionShapeCollection](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionshapecollection)
- [CompositionSpriteShape](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionspriteshape)
- [CompositionSurfaceBrush](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionsurfacebrush)
- [CompositionViewBox](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionviewbox)
- [CompositionVisualSurface](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositionvisualsurface)
- [Compositor](https://learn.microsoft.com/uwp/api/windows.ui.composition.compositor)
- [ContainerVisual](https://learn.microsoft.com/uwp/api/windows.ui.composition.containervisual)
- [ExpressionAnimation](https://learn.microsoft.com/uwp/api/windows.ui.composition.expressionanimation)
- [InsetClip](https://learn.microsoft.com/uwp/api/windows.ui.composition.insetclip)
- [IVisualElement](https://learn.microsoft.com/uwp/api/windows.ui.composition.ivisualelement)
- [IVisualElement2](https://learn.microsoft.com/uwp/api/windows.ui.composition.ivisualelement2)
- [RectangleClip](https://learn.microsoft.com/uwp/api/windows.ui.composition.rectangleclip)
- [RedirectVisual](https://learn.microsoft.com/uwp/api/windows.ui.composition.redirectvisual)
- [ShapeVisual](https://learn.microsoft.com/uwp/api/windows.ui.composition.shapevisual)
- [SpriteVisual](https://learn.microsoft.com/uwp/api/windows.ui.composition.spritevisual)
- [Visual](https://learn.microsoft.com/uwp/api/windows.ui.composition.visual)
- [VisualCollection](https://learn.microsoft.com/uwp/api/windows.ui.composition.visualcollection)

### Windows.UI.Composition.Interactions

- [InteractionTracker](https://learn.microsoft.com/uwp/api/windows.ui.composition.interactions.interactiontracker)
- [VisualInteractionSource](https://learn.microsoft.com/uwp/api/windows.ui.composition.interactions.visualinteractionsource)

### Windows.Graphics.Effects

- [IGraphicsEffectSource](https://learn.microsoft.com/uwp/api/windows.graphics.effects.igraphicseffectsource)

### Windows.Graphics.Effects.Interop

- [IGraphicsEffectD2D1Interop](https://learn.microsoft.com/en-us/windows/win32/api/windows.graphics.effects.interop/nn-windows-graphics-effects-interop-igraphicseffectd2d1interop)

### Microsoft.Graphics.Canvas.Effects (Win2D/Composition Effects)

- [AlphaMaskEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_AlphaMaskEffect.htm)
- [ArithmeticCompositeEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ArithmeticCompositeEffect.htm)
- [BlendEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_BlendEffect.htm)
- [BorderEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_BorderEffect.htm)
- [ColorMatrixEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ColorMatrixEffect.htm)
- [ColorSourceEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ColorSourceEffect.htm)
- [CompositeEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_CompositeEffect.htm)
- [ContrastEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ContrastEffect.htm)
- [CrossFadeEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_CrossFadeEffect.htm)
- [DistantDiffuseEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_DistantDiffuseEffect.htm)
- [DistantSpecularEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_DistantSpecularEffect.htm)
- [ExposureEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_ExposureEffect.htm)
- [GammaTransferEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_GammaTransferEffect.htm)
- [GaussianBlurEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_GaussianBlurEffect.htm)
- [GrayscaleEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_GrayscaleEffect.htm)
- [HueRotationEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_HueRotationEffect.htm)
- [InvertEffectEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_InvertEffect.htm)
- [LinearTransferEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_LinearTransferEffect.htm)
- [LuminanceToAlphaEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_LuminanceToAlphaEffect.htm)
- [Matrix5x4](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_Matrix5x4.htm)
- [OpacityEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_OpacityEffect.htm)
- [PointDiffuseEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_PointDiffuseEffect.htm)
- [PointSpecularEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_PointSpecularEffect.htm)
- [SaturationEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_SaturationEffect.htm)
- [SepiaEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_SepiaEffect.htm)
- [SpotDiffuseEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_SpotDiffuseEffect.htm)
- [SpotSpecularEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_SpotSpecularEffect.htm)
- [TemperatureAndTintEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_TemperatureAndTintEffect.htm)
- [TintEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_TintEffect.htm)
- [Transform2DEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_Transform2DEffect.htm)

Note that while Uno Platform implements these effects and [their Win2D wrappers](https://github.com/unoplatform/uno/tree/master/src/Uno.UI.Composition/Win2D/Microsoft/Graphics/Canvas/Effects), the Win2D wrappers are still internal and not exposed to users, but the effects can still be used by temporary implementing the [IGraphicsEffectD2D1Interop](https://learn.microsoft.com/en-us/windows/win32/api/windows.graphics.effects.interop/nn-windows-graphics-effects-interop-igraphicseffectd2d1interop) interface manually until the Win2D wrappers become public, like for example the [GaussianBlurEffect](https://microsoft.github.io/Win2D/WinUI2/html/T_Microsoft_Graphics_Canvas_Effects_GaussianBlurEffect.htm) can be implemented like this:

```csharp
#nullable enable

using System;
using Windows.Graphics.Effects;
using Windows.Graphics.Effects.Interop;

internal class GaussianBlurEffect : IGraphicsEffect, IGraphicsEffectSource, IGraphicsEffectD2D1Interop
{
    private string _name = "GaussianBlurEffect";
    private Guid _id = new Guid("1FEB6D69-2FE6-4AC9-8C58-1D7F93E7A6A5");

    public string Name
    {
        get => _name;
        set => _name = value;
    }

    public IGraphicsEffectSource? Source { get; set; }

    public float BlurAmount { get; set; } = 3.0f;

    public Guid GetEffectId() => _id;

    public void GetNamedPropertyMapping(string name, out uint index, out GraphicsEffectPropertyMapping mapping)
    {
        switch (name)
        {
            case nameof(BlurAmount):
                {
                    index = 0;
                    mapping = GraphicsEffectPropertyMapping.Direct;
                    break;
                }
            default:
                {
                    index = 0xFF;
                    mapping = (GraphicsEffectPropertyMapping)0xFF;
                    break;
                }
        }
    }

    public object? GetProperty(uint index)
    {
        switch (index)
        {
            case 0:
                return BlurAmount;
            default:
                return null;
        }
    }

    public uint GetPropertyCount() => 1;
    public IGraphicsEffectSource? GetSource(uint index) => Source;
    public uint GetSourceCount() => 1;
}
```

The GUID used in the example above is the Effect CLSID of the [Direct2D Gaussian Blur Effect](https://learn.microsoft.com/windows/win32/direct2d/gaussian-blur). For a list of built-in Direct2D effects and their corresponding CLSIDs, see [Direct2D Built-in Effects](https://learn.microsoft.com/windows/win32/direct2d/built-in-effects).

## Known issues

- [Android] When using the compositor thread, the native ripple effect of Android (used in native buttons) does not work.

- [Skia Backends] Some Composition effects don't render properly (or at all) on software rendering (CPU), to check if Uno is running on the software rendering (CPU) or the hardware rendering (GPU), you can call `CompositionCapabilities.GetForCurrentView().AreEffectsFast()`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/contributing-intro.md

---
uid: Uno.Contributing.Intro
---

# Contributing to Uno

Everyone is welcome to contribute to the Uno Platform. Here you'll find useful information for new and returning contributors.

For starters, please read our [Code of Conduct](https://github.com/unoplatform/uno/blob/master/CODE_OF_CONDUCT.md), which sets out our commitment to an open, welcoming, harassment-free community.

If you're wondering where to start, [read about ways to contribute to Uno](ways-to-contribute.md). Or, you can peruse the list of [first-timer-friendly open issues](https://github.com/unoplatform/Uno/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).

## Understanding the Uno codebase

For a refresher on what Uno is and what it does and does not do, read [What is the Uno Platform?](../intro.md)

Get an [in-depth introduction to how Uno works](uno-internals-overview.md), or jump straight to platform-specific details on how Uno works on [Android](uno-internals-android.md), [iOS](uno-internals-ios.md), [WebAssembly](uno-internals-wasm.md), or [macOS](uno-internals-macos.md).

## Building and debugging Uno

For the prerequisites you'll need, as well as useful tips like using [solution filters](https://learn.microsoft.com/visualstudio/ide/filtered-solutions) and cross-targeting overrides to quickly load and build Uno for a single platform, start with the guide to [Building Uno.UI](building-uno-ui.md). The guide to [Debugging Uno.UI](debugging-uno-ui.md) will show you how to debug Uno.UI code either in the included UI samples or in an application outside the Uno.UI solution.

You can contribute to Uno directly from your browser using Ona, [find out how](xref:Uno.Features.Gitpod).

Whether you're fixing a bug or working on a new feature, [inspecting the visual tree of a running app](xref:Uno.Contributing.InspectVisualTree) is often a key step.

## Writing code in Uno

See [Uno's code conventions and common patterns here](../contributing/guidelines/code-style.md).

## Implementing a new feature

See how to implement a new [feature here](xref:Uno.Contributing.ImplementWinUIWinRTAPI).

## Experimenting with Samples App

The [Samples App](xref:Uno.Contributing.SamplesApp) is the development app contained in the Uno.UI solution. It serves as a UI and Runtime Tests host, as well as a playground for validating other API scenarios.

This app is available live at these locations, built from the default branch:

- WebAssembly: https://aka.platform.uno/wasm-samples-app

## Adding tests

Uno's stability rests upon a comprehensive testing suite. A code contribution usually isn't complete without a test.

See the [Guidelines for creating tests](../contributing/guidelines/creating-tests.md) for an overview of the different types of tests used by Uno, and how to add one.

[Working with the Samples Applications](working-with-the-samples-apps.md) provides instructions on adding a new UI sample to Uno, and authoring a UI Test to verify that the sample works.

## Creating a Pull Request

Uno uses [Git](https://git-scm.com/) for version control, and GitHub to host the [main repository](https://github.com/unoplatform/uno). You'll need to know the basics of Git to submit changes to Uno, but never fear, there are plenty of great guides available:
[Pro Git book | git-scm](https://git-scm.com/book/en/v2)
[About Git | GitHub](https://guides.github.com/introduction/git-handbook/)
[Tutorials | Atlassian](https://www.atlassian.com/git/tutorials)

> [!IMPORTANT]
> Before you commit your code, take a minute to familiarize yourself with the [Conventional Commits format](git-conventional-commits.md) Uno uses.

Read the [Guidelines for pull requests](../contributing/guidelines/pull-requests.md) in Uno.

Uno's CI process [runs a tool to guard against inadvertent binary breaking changes](../contributing/guidelines/breaking-changes.md).

## Info for the core team

This section covers practices and utilities used by core maintainers.

Uno uses [Dependabot to automatically update external dependencies](../contributing/guidelines/updating-dependencies.md).

Read the [guidelines for issue triage](../contributing/guidelines/issue-triage.md).

Tools and procedures for creating stable releases are described in the [release procedure documentation](release-procedure.md).

Build artifacts produced by the CI are documented in the [build artifacts guide](../contributing/build-artifacts.md).

### More questions?

To discuss an issue you're working on or would like to work on, join us in Uno's [Discord Server](https://platform.uno/discord).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/create-an-app-ai-claude.md

---
uid: Uno.GettingStarted.CreateAnApp.AI.Claude
---

# Creating an app with Claude Code

> [!IMPORTANT]
> Before creating an app, make sure you have completed the [Claude Code setup](xref:Uno.GetStarted.AI.Claude) to install and configure the Uno Platform MCPs.

1. Create a new project using the [Uno Platform Live Wizard](https://aka.platform.uno/app-wizard), or [`dotnet new`](xref:Uno.GetStarted.dotnet-new)

    ```bash
    dotnet new unoapp --tfm net10.0 -o MyNewApp
    ```

1. Change your current directory to be in the folder containing the new project (e.g., `cd MyNewApp`)
1. Run the following command:

    ```bash
    dnx -y uno.devserver login
    ```

    The Uno Studio app will allow you to [sign in or create an account](xref:Uno.GetStarted.Licensing) and get access the [Uno App MCP](xref:Uno.Features.Uno.MCPs).
1. Still in the app folder, open Claude Code:

    ```bash
    claude
    ```

## Next Steps

You can start developing with [**Claude Code**](xref:Uno.BuildYourApp.AI.Agents).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/create-an-app-ai-codex.md

---
uid: Uno.GettingStarted.CreateAnApp.AI.Codex
---

# Creating an app with Codex CLI

To get started with Codex CLI for Uno Platform development:

1. Create a new project using the [Uno Platform Live Wizard](https://aka.platform.uno/app-wizard), or [`dotnet new`](xref:Uno.GetStarted.dotnet-new)

    ```bash
    dotnet new unoapp --tfm net10.0 -o MyNewApp
    ```

1. Change your directory to be in the folder containing the new project (e.g., `cd MyNewApp`)
1. Run the following command:

    ```bash
    dnx -y uno.devserver login
    ```

    The Uno Studio app will allow you to [sign in or create an account](xref:Uno.GetStarted.Licensing) and get access the [Uno App MCP](xref:Uno.Features.Uno.MCPs).

1. If running on linux or macos, run the following:

    ```bash
    export NUGET_PACKAGES=`pwd`/.nuget
    ```

1. Open Codex in the folder of the app

    ```bash
    codex --sandbox workspace-write --ask-for-approval on-request 
    ```

## Next Steps

You can start developing with [**Codex**](xref:Uno.BuildYourApp.AI.Agents).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/create-an-app-ai-cursor.md

---
uid: Uno.GettingStarted.CreateAnApp.AI.Cursor
---

# Creating an app with Cursor

1. Create a new project using the [Uno Platform Live Wizard](https://aka.platform.uno/app-wizard), or [`dotnet new`](xref:Uno.GetStarted.dotnet-new) command and change `-o MyApp` to be `-n MyApp -o .`.

    This will create the solution the folder you've already created in vscode. For example:

    ```bash
    dotnet new unoapp --tfm net10.0 -n MyApp -o .
    ```

1. In Cursor, open the project that was just created (e.g., `MyApp`).
1. Open a terminal in the project folder and run the following command:

    ```bash
    dnx -y uno.devserver login
    ```

    The Uno Studio app will allow you to [sign in or create an account](xref:Uno.GetStarted.Licensing) and get access the [Uno App MCP](xref:Uno.Features.Uno.MCPs).

1. Create a file named `.cursor/mcp.json` and place the following content:

    ```json
    {
      "mcpServers": {
          "uno": {
              "url": "https://mcp.platform.uno/v1"
          },
          "uno-app": {
              "command": "dnx",
              "args": ["-y","uno.devserver","--mcp-app"]
          }
      }
    }
    ```

## Next Steps

You can start developing with [**Cursor**](xref:Uno.BuildYourApp.AI.Agents).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/create-an-app-ai-gh-copilot-cli.md

---
uid: Uno.GettingStarted.CreateAnApp.AI.CopilotCli
---

# Creating an app with GitHub Copilot CLI

To get started with Copilot CLI:

1. Create a new project using the [Uno Platform Live Wizard](https://aka.platform.uno/app-wizard), or [`dotnet new`](xref:Uno.GetStarted.dotnet-new)

    ```bash
    dotnet new unoapp --tfm net10.0 -o MyNewApp
    ```

1. Change your directory to be in the folder containing the new project (e.g., `cd MyNewApp`)
1. Run the following command:

    ```bash
    dnx -y uno.devserver login
    ```

    The Uno Studio app will allow you to [sign in or create an account](xref:Uno.GetStarted.Licensing) and get access the [Uno App MCP](xref:Uno.Features.Uno.MCPs).

1. Start Copilot CLI in the folder of the app:

    ```bash
    copilot
    ```

## Next Steps

You can start developing with [**GitHub Copilot CLI**](xref:Uno.BuildYourApp.AI.Agents).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/create-an-app-rider.md

---
uid: Uno.GettingStarted.CreateAnApp.Rider
---

# Create an app with Rider

> [!NOTE]
> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.Rider).

## Create the App

> [!IMPORTANT]
>
> - **Rider (2024.2 and above)**: For Rider (2024.2 and above), we have released versions of the Uno Platform Plugin that support creating Uno Platform projects using the "New Solution" dialog.
>   Make sure to follow the directions for **Rider 2024.2** provided below.
>
> - **Rider (2024.1 and earlier)**: Current versions of Rider (2024.1 and earlier) do not support creating Uno Platform projects using the "New Solution" dialog, even if the Uno Platform project template appears.
>   Make sure to follow the directions for **Rider 2024.1** provided below.

### [**Rider Version 2024.2+**](#tab/rider2024-2)

Creating an Uno Platform project is done by following these steps:

1. On the **Welcome to JetBrains Rider** screen, click **New Solution**.

    ![A screen showing the Welcome to JetBrains Rider screen](Assets/quick-start/rider-welcome-screen-new-solution.png)

1. From the project types list on the left, locate and click **Uno Platform App**. It will be under the **Uno Platform** section.
1. Configure your new project by providing a solution name and a directory location.
1. Choose a template to build your application.

    ![A screen showing the Uno Platform App Template](Assets/quick-start/rider-configure-new-unoplatform-app.png)

    > [!TIP]
    > For a detailed overview of the Uno Platform project wizard and all its options, see the [Wizard guide](xref:Uno.GettingStarted.UsingWizard).
    > [!NOTE]
    > Starting with Uno.Sdk 6.0, [Skia rendering](xref:Uno.Development.HowItWorks) is now the default rendering engine in Uno Platform templates for iOS/Android/WebAssembly. If you prefer native rendering instead, you can switch this setting in the `Features` tab under `Renderer`.

1. Click the create button and wait for the solution to load.

1. You should now have a folder structure that looks like this:

    ![A screen showing the structure of the solution in Rider](Assets/quick-start/rider-folder-structure.png)

### [**Previous Rider Version 2024.1**](#tab/rider2024-1)

Creating an Uno Platform project is done [using dotnet new](xref:Uno.GetStarted.dotnet-new) and the Uno Platform Live Wizard by following these steps:

1. Open a browser and navigate to the <a target="_blank" href="https://aka.platform.uno/app-wizard">Live Wizard</a>.
1. Configure your new project by providing a project name, then click **Start**.

    ![A screen showing how to choose a solution name](Assets/quick-start/live-wizard-01-choose-name.png)

1. Choose a template to build your application.

    ![A screen showing how to choose template for the new app](Assets/quick-start/live-wizard-02-select-preset.png)

    > [!TIP]
    > For a detailed overview of the Uno Platform project wizard and all its options, see the [Wizard guide](xref:Uno.GettingStarted.UsingWizard).

1. Click the **Create** button on the top right corner, then click the **Copy** button.

    ![A screen showing the dotnet new command to create the new app](Assets/quick-start/live-wizard-03-create-app.png)

1. In your terminal, navigate to the folder that will contain your new app.

1. Create a new project by pasting the command that was previously generated in the Live Wizard.

1. Open the solution in Rider, and you should now have a folder structure that looks like this:

    ![A screen showing the structure of the solution in Rider](Assets/quick-start/rider-folder-structure.png)

> [!TIP]
> If you are not able to run the online Live Wizard, you can explore the [`dotnet new` template](xref:Uno.GetStarted.dotnet-new) directly in the CLI.

---

> [!IMPORTANT]
> A notification should appear prompting you to sign in or register with Uno Platform.
>
> Signing in with your Uno Platform account in Rider unlocks powerful tools like Hot Reload, helping you speed up development.
>
> With a single registration, you also gain early access to new features and the opportunity to connect with the Uno Platform community, where you can share feedback and network.
>
> Detailed information on registration and sign-in is available <a href="https://aka.platform.uno/account-access" target="_blank">here</a>.
>
> ![Uno Platform Sign in / Register notification](Assets/uno-settings-rider-notification.png)

### Considerations for macOS and Linux

When using macOS or Linux for developing your application and you have selected the WinAppSDK target, you may get the **UNOB0014** error, which mentions that building on macOS or Linux is not supported. While Uno Platform is able to filter out unsupported targets from the command line and other IDEs, Rider currently [does not support this automatic filtering](https://youtrack.jetbrains.com/issue/RIDER-114790/Unsupported-target-framework-filtering).

To correct this, you'll need to modify your `csproj` file in order to make the project compatible.

You can change this line:

```xml
<TargetFrameworks>net9.0-android;net9.0-ios;net9.0-windows10.0.26100;net9.0-browserwasm;net9.0-desktop</TargetFrameworks>
```

To be:

```xml
<TargetFrameworks>net9.0-android;net9.0-browserwasm;net9.0-desktop</TargetFrameworks>
<TargetFrameworks Condition=" $([MSBuild]::IsOSPlatform('windows')) ">$(TargetFrameworks);net9.0-windows10.0.26100</TargetFrameworks>
<TargetFrameworks Condition=" !$([MSBuild]::IsOSPlatform('linux')) ">$(TargetFrameworks);net9.0-ios</TargetFrameworks>
```

Make sure to adjust the list of target frameworks based on the platforms you have in your original list.

## Debug the App

### [**Desktop**](#tab/desktop)

Select the **MyUnoApp (Desktop)** debug profile, then click the green arrow or the debug button.

![A view of the Rider taskbar for Desktop](Assets/quick-start/run-desktop-rider.png)

### [**Android**](#tab/android)

Set the Android debug profile in the debugger toolbar, then click the green arrow or the debug button.

![A view of the Rider taskbar for Android](Assets/quick-start/run-android-rider.png)

If you don't already have an emulator, you can create and manage one **directly in Rider**.

1. **Install the Android plugin** (if it isn’t already):
   - `File` → `Settings` → `Plugins` → **Marketplace** → search **Rider Android Support** → **Install** → restart Rider.  
 ![A view of the Rider Android Support plugin on the marketplace](Assets/quick-start/rider-android-support-plugin-on-marketplace.png)

2. **Confirm Android SDK is set**:
   - `File` → `Settings` → search **Android SDK Location** → make sure the SDK path is valid and components are installed.
 ![A view of the Rider Android SDK Location](Assets/quick-start/rider-android-sdk-location.png)

3. **Open Device Manager**:
   - `View` → `Tool Windows` → **Device Manager**.
   - Click **+** → **Create Virtual Device…**, pick a device (e.g., Pixel), choose a recent system image (API 34/35), and finish.

4. **Run your Uno app**:
   - In the Rider debug toolbar, choose the **Android Emulator** profile and press ▶︎ **Run** or  **Debug**.

> [!NOTE]
> Whether you're using a physical device or the emulator, the app will install but may not automatically open. You may have to manually open it.

### [**WebAssembly**](#tab/wasm)

> [!IMPORTANT]
> To run WebAssembly with Rider, you will need to install one of the following browsers:
>
> - **Google Chrome**
> - **Microsoft Edge (Chromium-based)**

Select the **MyUnoApp (WebAssembly)** debug profile, then click the green arrow or the debug button.

![A view of the Rider taskbar for WebAssembly](Assets/quick-start/run-wasm-rider.png)

A new browser window will automatically run your application.

> [!IMPORTANT]
> If you get an **"Error: Default system browser option is not supported for Blazor apps. Please select a Chromium-based browser."** error message, you will also need to change the project configuration in Rider for WebAssembly, to ensure it uses either Chrome or Microsoft Edge. To do this, click on the TFMs dropdown to access the Edit Configuration option. Then navigate to WebAssembly, and change the browser setting from 'Default' to 'Chrome' or 'Edge'.

![Updating Rider WebAssembly Browser Configuration](Assets/quick-start/rider_webassembly_change_browser.png)

> [!IMPORTANT]
> There is currently a known issue with **Rider version 2024.2** on **macOS** that causes an **'Access to localhost was denied' error when launching applications on WebAssembly**. Until this issue is resolved, you will need to reload the browser page to successfully load the application.
> Please refer to this open related [Rider issue](https://youtrack.jetbrains.com/issue/RIDER-115776/MacOS-WASM-Access-to-localhost-was-denied-on-Initial-Run) to track progress on this issue we are prioritizing with the JetBrains team.
>
> [!NOTE]
> There is no debugging for WebAssembly within Rider for Uno Platform, but you can debug using the [built-in Chrome tools](external/uno.wasm.bootstrap/doc/debugger-support.md#how-to-use-the-browser-debugger).

### [**iOS**](#tab/ios)

Select the **MyUnoApp** debug profile with the mobile Apple logo, then click the green arrow or the debug button.

![A view of the Rider taskbar for iOS](Assets/quick-start/run-ios-rider.png)

> [!NOTE]
> Debugging iOS apps is only supported on macOS

### [**WinUI/WinAppSDK**](#tab/winui)

Select the **MyUnoApp (WinAppSDK Unpackaged)** debug profile, then click the green arrow or the debug button.

![A view of the Rider taskbar for WinAppSDK](Assets/quick-start/run-winappsdk-rider.png)

> [!NOTE]
> Debugging Windows App SDK profile is only supported on Windows.

---

## Next Steps

Now that you're Created and Debug the App.

Learn more about:

- [Uno Platform features and architecture](xref:Uno.GetStarted.Explore)
- [Hot Reload feature](xref:Uno.Features.HotReload)
- [Uno Platform App solution structure](xref:Uno.Development.AppStructure)
- [Troubleshooting](xref:Uno.UI.CommonIssues)
- [How-tos and Tutorials](xref:Uno.Tutorials.Intro) See real-world examples with working code.
- <a href="implemented-views.md">Use the API Reference to Browse the set of available controls and their properties.</a>

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/create-an-app-vs2022.md

---
uid: Uno.GettingStarted.CreateAnApp.VS2022
---
# Creating an app with Visual Studio

> [!NOTE]
> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.vs2022).

## Create the App

To create an Uno Platform app:

1. Create a new C# solution using the **Uno Platform App** template, from Visual Studio's **Start Page**, then click the **Next** button

    ![Visual Studio - Get started - Selecting `create a new project` option](Assets/tutorial01/newproject1.PNG)  
    ![Visual Studio - Create a new project - Selecting `Uno Platform App` option](Assets/tutorial01/newproject2.PNG)

1. Configure your new project by providing a project name and a location, check the "**Place solution and project in the same directory**" option, then click the **Create** button

    ![Visual Studio - Configure project name and location](Assets/tutorial01/configure-new-unoplatform-app.PNG)

    > [!NOTE]
    > If you intend to add your new project to an existing solution, continue this guide then [follow our instructions](xref:Uno.Guides.AddUnoToExistingSolution).

1. Choose a template preset to build your application

    ![Visual Studio - Configure your new project](getting-started/wizard/assets/intro.png)

    > [!TIP]
    > For a detailed overview of the Uno Platform project template wizard and all its options, see [this](xref:Uno.GettingStarted.UsingWizard).
    > [!NOTE]
    > Starting with Uno.Sdk 6.0, [Skia rendering](xref:Uno.Development.HowItWorks) is now the default rendering engine in Uno Platform templates for iOS/Android/WebAssembly. If you prefer native rendering instead, you can switch this setting in the `Features` tab under `Renderer`.

1. Click the create button

1. Ensure that the lower left IDE icon shows a check mark and says "Ready" ![A checkmark with a text saying ready](getting-started/wizard/assets/vs2022-ready-statusbar.png). This ensures that the projects have been created, and their dependencies have been restored completely.

1. A Windows Firewall window may appear. If you do not intend to do Linux development with WSL, check "Private networks" only. Otherwise, check "Public networks" and "Private networks".

1. A banner at the top of the editor may ask to reload projects, click **Reload projects**:  
    ![Visual Studio - A banner indicating to reload projects](Assets/quick-start/vs2022-project-reload.png)

1. > [!IMPORTANT]
    > A notification should appear prompting you to sign in or register with Uno Platform.
    >
    > Signing in with your Uno Platform account in Visual Studio unlocks powerful tools like Hot Reload, helping you speed up development.
    >
    > With a single registration, you also gain early access to new features and the opportunity to connect with the Uno Platform community, where you can share feedback and network.
    >
    > Detailed information on registration and sign-in is available <a href="https://aka.platform.uno/account-access" target="_blank">here</a>.
    >
    > ![Uno Platform sign in / register notification](Assets/uno-settings-notification.png)

## Debug the App

### [**Desktop**](#tab/desktop)

To debug your Uno Platform **Desktop** target:

- Directly on Windows:
  - In the **Debug toolbar** drop-down, select the profile `MyApp (Desktop)`

    ![Visual Studio - "Debug toolbar" drop-down selecting the `MyApp (Desktop)` profile](Assets/quick-start/desktop-debug-windows.png)

  - Press `F5` to debug.

- Using WSL with X11:
  - In the **Debug toolbar** drop-down, select the profile `MyApp (Desktop WSL2)`

    ![Visual Studio - "Debug toolbar" drop-down selecting the `MyApp (Desktop WSL2)` profile](Assets/quick-start/desktop-wsl2-debug-windows.png)

  - Then press `F5` or the green arrow to start debugging the app

### [**WebAssembly**](#tab/wasm)

To run the **WebAssembly** (Wasm) head:

- In the debugger toolbar, click the down arrow to select **MyApp (WebAssembly)**

    ![Visual Studio - Select the Wasm profile](getting-started/wizard/assets/wasm-debugger-dropdown.png)

- Press the `MyApp (WebAssembly)` button to deploy the app
- To run/debug your WebAssembly app on a mobile device, you can utilize the Dev Tunnels feature of Visual Studio 2022/2026 (see [Microsoft Learn documentation](https://learn.microsoft.com/aspnet/core/test/dev-tunnels) to get started)

### [**ASP.NET Hosted WebAssembly**](#tab/wasm-hosted)

To run the ASP.NET Hosted **WebAssembly** (Server) head, if you've selected the option in the Wizard:

- Right-click on the `MyApp.Server` project, select **Set as startup project**
- Press the `MyApp.Server` button to deploy the app

### [**Windows**](#tab/windows)

To run the **Windows** (WinAppSDK) head:

- In the debugger toolbar, click the down arrow to select **MyApp (WinAppSDK Packaged)** or **MyApp (WinAppSDK Unpackaged)**

    ![Visual Studio - Select the WinappSDK profile](getting-started/wizard/assets/winappsdk-debugger-dropdown.png)

- Press the `MyApp (WinAppSDK Packaged)` or `MyApp (WinAppSDK Unpackaged)` button to deploy the app
- If you have not enabled Developer Mode, the Settings app should open to the appropriate page. Turn on Developer Mode and accept the disclaimer.

> [!NOTE]
> If you're not able or willing to turn on the Windows developer mode, [read about this common issue](xref:Uno.UI.CommonIssues.vs2022#unable-to-select-the-myapp-unpackaged-winappsdk-profile).

### [**iOS**](#tab/iOS)

To debug for **iOS**:

> [!NOTE]
> For information about connecting Visual Studio to a Mac build host to build iOS apps, see [Pairing to a Mac for .NET iOS development](https://learn.microsoft.com/xamarin/ios/get-started/installation/windows/connecting-to-mac/).

- In the "Debug toolbar" drop-down, select framework `net9.0-ios`:

    ![Visual Studio - "Debug toolbar" drop-down selecting the "net9.0-ios" framework](Assets/quick-start/ios-debug.png)

- Select:
  - An active device, if your IDE is connected to a macOS Host
  - A [local device using Hot Restart](https://learn.microsoft.com/xamarin/xamarin-forms/deploy-test/hot-restart), to debug your application without connecting to a mac

    > [!NOTE]
    > If no iOS devices are available, a Visual Studio 17.7+ issue may require unloading/reloading the project. Right-click on the `MyApp` project and select **Unload Project** then **Load project**.
    > [!IMPORTANT]
    > When using a device connected to a Windows PC, the Release build configuration is not supported. An actual macOS machine is required.

### [**Android**](#tab/Android)

To debug the **Android** platform:

- In the **Debug toolbar** drop-down, select framework `net9.0-android`

    ![Visual Studio - "Debug toolbar" drop-down selecting the "net9.0-android" framework](Assets/quick-start/android-debug.png)

- Select an active device in the "Device" sub-menu
    > [!NOTE]
    > If no android devices are available, a Visual Studio 17.7+ issue may require unloading/reloading the project. Right-click on the `MyApp` project and select **Unload Project** then **Load project**.

---

You're all set!

## Next Steps

Now that you've created and debugged your app, you can continue development or you can [**use Copilot**](xref:Uno.BuildYourApp.AI.Agents) to accelerate your workflow.

Learn more about:

- [Uno Platform features and architecture](xref:Uno.GetStarted.Explore)
- [Hot Reload features](xref:Uno.Features.HotReload)
- [Uno Platform App solution structure](xref:Uno.Development.AppStructure)
- [Troubleshooting](xref:Uno.UI.CommonIssues)
- [How-tos and Tutorials](xref:Uno.Tutorials.Intro) See real-world examples with working code.
- [List of views implemented in Uno](implemented-views.md) for the set of available controls and their properties.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/create-an-app-vscode.md

---
uid: Uno.GettingStarted.CreateAnApp.VSCode
---
<!-- markdownlint-disable MD025 -->
# Creating an app with VS Code

> [!NOTE]
> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.vscode).

## Create the App

There are two ways to create your app. You can either use the Live Wizard or the `/mcp.uno.new` Copilot Agent prompt.

# [**Live Wizard**](#tab/live-wizard)

Creating an Uno Platform project is done [using dotnet new](xref:Uno.GetStarted.dotnet-new) and the Uno Platform Live Wizard by following these steps:

1. Open a browser and navigate to the online <a target="_blank" href="https://aka.platform.uno/app-wizard">Live Wizard</a>
1. Configure your new project by providing a project name, then click **Start**

    ![A screen showing how to choose a solution name](Assets/quick-start/live-wizard-01-choose-name.png)

1. Choose a template to build your application

    ![A screen showing how to choose template for the new app](Assets/quick-start/live-wizard-02-select-preset.png)

    > [!TIP]
    > For a detailed overview of the Uno Platform project wizard and all its options, see the [Wizard guide](xref:Uno.GettingStarted.UsingWizard).
    > [!NOTE]
    > Starting with Uno.Sdk 6.0, [Skia rendering](xref:Uno.Development.HowItWorks) is now the default rendering engine in Uno Platform templates for iOS/Android/WebAssembly. If you prefer native rendering instead, you can switch this setting in the `Features` tab under `Renderer`.

1. Click the **Create** button on the top right corner, then click the **Copy** button

    ![A screen showing the dotnet new command to create the new app](Assets/quick-start/live-wizard-03-create-app.png)

1. In your terminal, navigate to the folder that will contain your new app.
1. Create a new project by pasting and executing the command that was previously generated in the Live Wizard.

> [!IMPORTANT]
> Apple targets are automatically disabled under Linux.

Next, open the project using Visual Studio Code.

* Let's assume your project is named `MyApp` and is located inside a `Projects` folder:

  * **Using the Terminal**
    Ensure you are at the **parent folder** (`Projects`) level, then run:

    ```bash
    code ./MyApp
    ```

  * **Using Visual Studio Code**
    1. Open **Visual Studio Code**.
    2. Go to **File > Open Folder**.
    3. Navigate to the `Projects` folder and select the `MyApp` folder.
* Visual Studio Code might ask to restore the NuGet packages. Allow it to restore them if asked.
* Once the solution has been loaded, in the status bar at the bottom left of VS Code, `MyApp.sln` is selected by default. Select `MyApp.csproj` to load the project instead.

* > [!IMPORTANT]
  > A notification should appear prompting you to sign in or register with Uno Platform.
  >
  > Signing in with your Uno Platform account in Visual Studio Code unlocks powerful tools like Hot Reload, helping you speed up development.
  >
  > With a single registration, you also gain early access to new features and the opportunity to connect with the Uno Platform community, where you can share feedback and network.
  >
  > Detailed information on registration and sign-in is available <a href="https://aka.platform.uno/account-access" target="_blank">here</a>.
  >
  > ![Uno Platform Sign in / Register notification](Assets/uno-settings-vsc-notification.png)

# [**Copilot AI Prompt**](#tab/copilot-prompt)

## Using the `/mcp.uno.new` agent prompt

1. Open VS Code in an empty new folder
1. Add the Uno Platform MCP by creating a file named `.vscode/mcp.json`:

   ```json
   {
     "servers": {
       "uno": {
          "url": "https://mcp.platform.uno/v1"
       }
     }
   }
   ```

1. Save the file, then on top of the registration for the uno MCP, click the **start** button.

    ![start MCP](Assets/vscode-start-mcp.png)

1. Open Copilot using the center title bar icon:

    ![copilot title bar icon](Assets/vscode-copilot-icon.png)

1. Select "Agent" on the bottom-left side:

    ![Agent mode](Assets/vscode-agent-mode.png)

1. In the Copilot Window, type the `/mcp.uno.new` then **Enter**.
1. The Agent will ask you for your app's description, write the following:

    ```text
    I need a desktop app that shows the current date in the middle of the window.
    ```

1. Copilot will proceed for a few minutes until it asks to reload the VS Code window.
1. Once it does, in the command palette, select **Reload Window** in order the Uno Platform extension to load

    ![vscode project selection](Assets/vscode-reload-window.png)

    > [!IMPORTANT]
    > This step is required for the uno extension to be loaded properly.

1. Select a csproj in the VS Code status bar, if there's a red rectangle

    ![vscode project selection](Assets/vscode-project-selection.png)

1. Wait a few seconds for the XAML Hot Reload server to become available

    ![vscode project selection](Assets/vscode-hot-reload-server.png)

---

## Explore the Agent MCP tools

We can now explore the MCP:

1. If you want to use our MCP tools, make sure to be logged in using your account in [Uno Studio](xref:Uno.GetStarted.Licensing) by using the command palette:

    ![vscode project selection](Assets/vscode-uno-studio-open.png)

1. When clicking on the "double wrench" icon on the right side of Copilot, you should be seeing the Uno Platform MCP tools listed:

    ![uno mcp tools](Assets/vscode-tools-config.png)

## Debug the App

Uno Platform provides integrated support for debugging your app on Windows, macOS, and Linux.

### [**WebAssembly**](#tab/Wasm)

> [!NOTE]
> VS Code's built-in JavaScript debugger currently **[only supports](https://github.com/microsoft/vscode-js-debug/blob/main/OPTIONS.md)**:
>
> * **Google Chrome**
> * **Microsoft Edge (Chromium-based)**
>
> To debug WebAssembly with VS Code, **one of these browsers must be installed**.
>
> Safari, Firefox, and other browsers are **not directly supported** via VS Code at the moment.

In VS Code :

1. In the [activity bar](https://code.visualstudio.com/docs/getstarted/userinterface) select the debugger
1. Set the debugger launch to `Uno Platform WebAssembly Debug (Chrome)` or `Uno Platform WebAssembly Debug (Edge)`

![VS Code UI](Assets/quick-start/vs-code-chrome-debug.png)

In the status bar :

1. Just after the Uno logo, ensure the `MyApp` project is selected - by default `MyApp.sln` is selected
1. Next, click on the target framework to select `net9.0-browserwasm | Debug`

![status bar](Assets/quick-start/vs-code-browserwasm-project.png)

Finally, press `F5` to start the debugging session.

### [**Desktop**](#tab/skia)

In VS Code :

1. In the [activity bar](https://code.visualstudio.com/docs/getstarted/userinterface) select the debugger
1. Set the debugger launch to `Uno Platform Mobile` or `Uno Platform Desktop (Debug)`

![VS Code UI](Assets/quick-start/vs-code-mobile-debug.png)

In the status bar :

1. Just after the Uno logo, ensure the `MyApp` project is selected - by default `MyApp.sln` is selected
1. Next click on the target framework to select `net9.0-desktop | Debug`

![status bar](Assets/quick-start/vs-code-desktop-project.png)

Finally, press `F5` to start the debugging session.

#### Debugging using WSL 2 on Windows

VS Code supports debugging Uno Platform Desktop apps through the WSL Extension:

1. Install the [WSL extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl)
1. In the control palette, select **WSL: Connect to WSL**
1. Once connected to WSL, ensure that the [Uno Platform extension](https://marketplace.visualstudio.com/items?itemName=unoplatform.vscode) is installed
1. Once the extension is installed, follow the same steps as the section above

#### Debugging on Linux Remotely

When connecting to a remote Linux machine using the [SSH Extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh), in order for the user interface to show, it is required to specify the `DISPLAY` environment variable:

1. In the `.vscode/launch.json`, find the `Uno Platform Desktop (Debug)` section
1. In the `env` section, add the following:

    ```json
    "env": {
        "DISPLAY": ":0"
    },
    ```

This will allow the application to build on the remote machine and then show on the main display.

#### Considerations for Hot Reload

Note that C# Hot Reload is not available when running with the debugger. See [this section](xref:Uno.Platform.Studio.HotReload.Overview) for more information on Hot Reload.

### [**Android**](#tab/androiddebug)

In VS Code :

1. In the [activity bar](https://code.visualstudio.com/docs/getstarted/userinterface) select the debugger
1. Set the debugger launch to `Uno Platform Mobile`

![VS Code UI](Assets/quick-start/vs-code-mobile-debug.png)

In the status bar :

1. Just after the Uno logo ensure the `MyApp` project is selected - by default `MyApp.sln` is selected
1. Next click on the target framework to select `net9.0-android | Debug`
1. Then select the device to debug with. You will need to connect an Android device or [create an Android emulator](https://developer.android.com/studio/run/managing-avds).

![status bar](Assets/quick-start/vs-code-android-project.png)

Finally, press `F5` to start the debugging session.

### [**iOS**](#tab/iosdebug)

> [!NOTE]
> Debugging for iOS is only possible when running locally (or remotely through [Remote SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)) on a macOS machine.

In VS Code :

1. In the [activity bar](https://code.visualstudio.com/docs/getstarted/userinterface) select the debugger
1. Set the debugger launch to `Uno Platform Mobile`

![VS Code UI](Assets/quick-start/vs-code-mobile-debug.png)

In the status bar :

1. Just after the Uno logo ensure the `MyApp` project is selected - by default `MyApp.sln` is selected
1. Next click on the target framework to select `net9.0-ios | Debug`
1. Then select the device to debug with. You will need to connect an iOS device or [use an installed iOS simulator](https://developer.apple.com/documentation/xcode/installing-additional-simulator-runtimes).

![status bar](Assets/quick-start/vs-code-ios-project.png)

Finally, press `F5` to start the debugging session.

> [!TIP]
> When deploying to an iOS device, you may encounter the following error: `errSecInternalComponent`. In such a case, you'll need to unlock your keychain from a terminal inside VS Code by running the following command: `security unlock-keychain`

### [**Windows**](#tab/windowsdebug)

> [!NOTE]
> Debugging for Windows is only possible when running locally (or remotely through [Remote SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)) on a Windows computer.

In VS Code :

1. In the [activity bar](https://code.visualstudio.com/docs/getstarted/userinterface) select the debugger
1. Set the debugger launch to `Uno Platform Mobile`

![VS Code UI](Assets/quick-start/vs-code-mobile-debug.png)

In the status bar :

1. Just after the Uno logo ensure the `MyApp` project is selected - by default `MyApp.sln` is selected
1. Next click on the target framework to select `net9.0-windows10.0.xxxxx | Debug`
1. The `This Computer` device will be pre-selected. On ARM64-based computers, you will have the option to use `This Computer using emulation` to debug `x64` applications

![status bar](Assets/quick-start/vs-code-windows-project.png)

Finally press `F5` to start the debugging session.

---

You're all set!

You can also find [additional VS Code topics](xref:Uno.vscode.additional), such as using snippets, updating existing apps to use VS Code.

## Next Steps

Now that you've created and debugged your app, you can continue development or you can [**use Copilot**](xref:Uno.BuildYourApp.AI.Agents) to accelerate your workflow.

You can also learn more about:

* [Uno Platform features and architecture](xref:Uno.GetStarted.Explore)
* [Hot Reload features](xref:Uno.Features.HotReload)
* [Uno Platform App solution structure](xref:Uno.Development.AppStructure)
* [Troubleshooting](xref:Uno.UI.CommonIssues)
* [How-tos and Tutorials](xref:Uno.Tutorials.Intro) See real-world examples with working code.
* [List of views implemented in Uno](implemented-views.md) for the set of available controls and their properties.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/creating-custom-controls.md

---
uid: Uno.Tutorials.CreatingCustomControls  
---  

# Creating Custom Controls

Custom controls in the Uno Platform enable developers to create reusable UI components that work seamlessly across iOS, Android, WebAssembly, Linux, macOS, and Windows. Uno Platform supports the same approach as WinUI/WinAppSDK, with a few specific considerations for cross-platform compatibility.

> [!NOTE]  
> For a more detailed explanation of creating custom controls, including dependency properties and control templates, refer to the official WinUI documentation: [Build XAML controls with C# | Microsoft Learn](https://learn.microsoft.com/windows/apps/winui/winui3/xaml-templated-controls-csharp-winui-3).

If you're not familiar with concepts such as **dependency properties**, **control templates**, and **visual states**, it might be useful to explore those topics before diving into custom controls. These are fundamental concepts for creating reusable, maintainable UI components:

- **Dependency Properties**: These are properties that are tracked by a dedicated property system to allow binding, styling, animations, and tracking value changes to work. For more information, see [Dependency properties overview | Microsoft Learn](https://learn.microsoft.com/windows/uwp/xaml-platform/dependency-properties-overview).
- **Control Templates**: These define the visual structure and behavior of a control, allowing you to separate design from logic. Check out [Control templates | Microsoft Learn](https://learn.microsoft.com/windows/apps/design/style/xaml-control-templates) for further reading.
- **Visual States and Visual State Manager**: Visual states help you define different appearances for a control depending on its state (e.g., pressed, focused). Learn more here: [VisualStateManager Class | Microsoft Learn](https://learn.microsoft.com/en-us/dotnet/api/system.windows.visualstatemanager).

## Ensuring Cross-Platform Compatibility

To ensure your custom control functions properly across all platforms, make sure that the `Themes/Generic.xaml` file is included in your Uno project and correctly referenced for each platform. On non-Windows platforms, this file might not be automatically included, and you may need to adjust your project settings or add custom build steps to ensure it is properly referenced.

In WinUI apps, `Themes/Generic.xaml` is the standard location for default styles. It should be supported across all platforms and automatically referenced when Uno searches for implicit or default styles in any `TemplatedControl` defined in `Generic.xaml`. Additionally, it's common to use a `MergedDictionary` to reference resources from other directories within `Generic.xaml`. Currently, styles defined in `Themes/Generic.xaml` are not found automatically across platforms in Uno.

To resolve this, you can define styles in `App.xaml` and use a `MergedDictionary` to pull in the resources, as shown in the following example:

```xml
<Application xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
             xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                <ResourceDictionary Source="ms-appx:///Themes/Generic.xaml" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
</Application>
```

## Handling Platform-Specific Adjustments

In some cases, custom control behavior might need adjustments based on the platform. Uno Platform provides the flexibility to handle platform-specific differences using conditional code in both XAML and C#. For XAML, platform-specific XML namespaces can be utilized, while `#if` preprocessor directives are available in C#. For more details, refer to the documentation on [Platform-Specific C#](xref:Uno.Development.PlatformSpecificCSharp) and [XAML Conditions](xref:Uno.Development.PlatformSpecificXaml).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/creating-mocked-tests.md

---
uid: Uno.Contributing.CreateMockedTests
---

# Creating unit tests in Uno.UI.Tests

Unit tests in `Uno.UI.Tests` run against a .NET Framework build of `Uno.UI`, which uses the 'real' Uno code for platform-independent components (eg the dependency-property system) and mocks platform-dependent aspects (eg actual rendering).

Adding tests here is closest to the 'traditional' unit test experience: you can run tests from the Visual Studio test window pane, easily debug the code you're modifying, etc. This is the ideal place to test platform-independent parts of the API, like dependency property behaviors and XAML-generated code.

## Running tests in Uno.UI.Tests

1. Open and build the Uno.UI solution [for the unit tests target](building-uno-ui.md).
2. Open Test Explorer from the TEST menu.
3. Tests are listed under `Uno.UI.Tests`. You can run all tests or a subsection, with or without debugging. Tests run in a vanilla .NET Framework environment. (Note: You usually don't need to run `Uno.Xaml.Tests` tests locally, unless you're making changes to low-level XAML parsing in `Uno.Xaml`. )

## Adding a new test

1. Locate the test class corresponding to the control or class you want to create a test for. If you need to add a new test class, create the file as `Namespace_In_Snake_Case/ControlNameTests/Given_ControlName.cs`. be marked with the `[TestClass]` attribute.
2. Add tests for your cases, naming it as `When_Your_Scenario` and marking it with the `[TestMethod]` attribute. (For more information about the 'Given-When-Then' naming style, read <https://martinfowler.com/bliki/GivenWhenThen.html> )

The mocking layer of Uno.UI for unit tests has been added as needed, and depending on your case, you may encounter areas of functionality that aren't supported. Your options if that happens are either to add the missing mocking, or to [add the test in Uno.UI.RuntimeTests](creating-runtime-tests.md) instead.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/creating-runtime-tests.md

---
uid: Uno.Contributing.CreateRuntimeTests
---

# Creating unit tests in Uno.UI.RuntimeTests

Platform-runtime unit tests are relatively cheap (in terms of developer productivity and CI time) whilst still allowing functionality to be verified across all supported platforms and in a realistic environment. Accordingly they're appropriate for many bugfixes and new features.

Tests in Uno.UI.RuntimeTests are easy to write. There are a few special attributes and environmental helpers to know about, which this guide will cover.

For other types of automated tests used internally by Uno.UI, [see here](../contributing/guidelines/creating-tests.md).

## Running tests locally

Since the Uno.UI.RuntimeTests tests run in the platform environment using the real Uno.UI binaries, they must be run from within SamplesApp.

1. Build and launch the SamplesApp, following [the instructions here](working-with-the-samples-apps.md). Note: if you're testing a mobile platform, it's recommended to run on a tablet in landscape mode. On a phone-sized layout, a few tests will fail because they don't have enough space to measure properly.
2. From the sample menu, navigate to 'Unit Tests' > 'Unit Tests Runner' or click on the top-left-most button.
3. (Optional) Add a filter string in the text input control at the top of the page (for example the name or part of the name of your test method); only tests matching the filter will be run. Otherwise, all tests will run.
    > On mobile devices with limit screen width, you can drag the grid-slitter (the horizontal and vertical blue bars) to make more space for the filter textbox or test area.
4. Press the 'Run' button. Tests will run in sequence, and the results will be shown.

## Authoring tests

To add a new runtime test:

1. Locate the test class corresponding to the control or class you want to create a test for. Tests are located in `Uno.UI.RuntimeTests/Tests`. If you need to add a new test class, create the file as `Tests/Namespace_In_Snake_Case/Given_ControlName.cs`. The class should be marked with the `[TestClass]` attribute.
2. Create your test as a method, naming it as `When_Your_Scenario` and marking it with the `[TestMethod]` attribute. (For more information about the 'Given-When-Then' naming style, read <https://martinfowler.com/bliki/GivenWhenThen.html> )
3. The runtime tests run from a background thread by default, but when testing UI-related scenarios this isn't desirable. You can use the `[RunsOnUIThread]` attribute, either on individual test methods or the whole test class, to configure the test (or suite of tests) to be run on the UI thread.
4. Use the helpers described below to set up the state required to repro your bug, and use standard `Assert` calls and/or [FluentAssertions](https://fluentassertions.com/introduction) to verify expected state.
5. Verify your test locally by running according to the instructions above. Typically it's fine to test locally on just one target platform; the CI will take care of the others.

### Helpers

A number of helper methods are available to set up a state for testing common UI scenarios.

#### WindowHelper

The `Private.Infrastructure.TestServices.WindowHelper` class exposes several static methods and properties to easily insert a control into the running visual tree, and to wait for modifications to the UI to have been fully processed, since updates to the UI typically take effect asynchronously.

- `WindowHelper.WindowContent`: assigning a `FrameworkElement` to this static property will cause that element to be loaded into the running visual tree. Subsequently setting it to `null` (or another element) will cause the old element to be unloaded from the visual tree.
- `Task WindowHelper.WaitForLoaded(FrameworkElement element)`: returns a task that will complete once `element` is fully loaded into the visual tree. You'd typically await it after assigning `WindowContent = element`, to ensure that `element` has been loaded, measured, and arranged, before further manipulations or assertions.
- `Task WindowHelper.WaitForIdle()`: returns a task that will complete when the idle dispatcher is raised, roughly indicating that the UI thread 'isn't doing anything'. Await this to wait for the UI thread to 'settle' without a specific condition.
- `Task WindowHelper.WaitFor(Func<bool> condition)`: returns a task that will complete once `condition` is met, or throw an exception if it times out. Await this to wait for the UI to reach a specific expected state.

#### StyleHelper

- `IDisposable UseNativeStyle<T>() where T : Control`: This allows you to override the style settings to use a native default style for the duration of a test. Eg, `using (UseNativeStyle<Slider>()) { }` will cause all `Slider` elements to use the native style by default.
- `IDisposable UseNativeFrameNavigation()`: This is a helper which sets native styles as default for the control types implicated in frame navigation (`Frame`, `CommandBar` and `AppBarButton`). This is useful for testing native frame navigation.

#### Useful methods coming from `Uno.UI` itself

 The `FindFirstChild<T>` and `FindFirstParent<T>` extension methods are helpful in the common case that you want to retrieve a descendant or ancestor element by traversing the visual tree. They optionally take a condition to be met.

 Note that for Android/iOS/macOS, the versions of the methods that allow native views to be traversed and retrieved are located in different namespaces. The complete set of usings to conditionally include is:

 ```csharp
 #if NETFX_CORE
using Uno.UI.Extensions;
#elif __APPLE_UIKIT__
using UIKit;
#else
using Uno.UI;
#endif
 ```

### Other tips

- If you open a popup in some way (including indirectly via a `ComboBox`, `Flyout` etc), ensure to close it at the end of the test, ideally in a `try/finally` block. Otherwise it may interfere with the correct execution of subsequent tests.

### Example

Let's look at a complete test, from the `Given_ListViewBase` test class. The code is below.

The test is ignored on iOS and Android since it verifies a feature that's not yet supported on those platforms. Note that since the `Uno.UI.RuntimeTests` assembly is compiled separately for each platform, we use compiler conditionals to ignore a test per-platform.

The test is an `async` method that returns `Task` because we want to perform asynchronous operations on the UI thread (add the view and wait for it to be measured and arranged). Since the `Given_ListViewBase` class is marked with the `[RunsOnUIThread]` attribute, we don't need to add it again to the method.

We create a new items source, then create a `ListView` and assign its `ItemsSource` property. Then we put the `ListView` inside of a `Border` (because this is the specific measurement scenario we wish to test), and add the `Border` to the active visual tree by assigning it to the `WindowHelper.WindowContent` property.

We call `await WindowHelper.WaitForIdle()` to wait for the newly-added visual trees to be loaded, measured and arranged. (We could also have used the `WindowHelper.WaitForLoaded()` method here.)

In this test we want to check that the item containers inside the list have been properly measured and arranged. We use the `ContainerFromItem()` method to get each container; we wrap it inside a `WaitFor()` check because, on some platforms, it takes a few UI loops for the list to materialize its items. Another way to get the containers would have been to use `FindFirstChild<ListViewItem>()` and an appropriate predicate.

Finally we assert that the `ActualWidth` of each container is what we expect, and the `ActualWidth` of the list itself for good measure.

```csharp
[TestMethod]
#if __IOS__ || __TVOS__ || __ANDROID__
[Ignore("ListView only supports HorizontalAlignment.Stretch - https://github.com/unoplatform/uno/issues/1133")]
#endif
public async Task When_ListView_Parent_Unstretched()
{
 var source = Enumerable.Range(0, 5).ToArray();
 var SUT = new ListView
 {
  HorizontalAlignment = HorizontalAlignment.Stretch,
  ItemsSource = source
 };

 const int minWidth = 193;
 var border = new Border
 {
  HorizontalAlignment = HorizontalAlignment.Left,
  MinWidth = minWidth,
  Child = SUT
 };

 WindowHelper.WindowContent = border;

 await WindowHelper.WaitForIdle();

 ListViewItem lvi = null;
 foreach (var item in source)
 {
  await WindowHelper.WaitFor(() => (lvi = SUT.ContainerFromItem(item) as ListViewItem) != null);
  Assert.AreEqual(minWidth, lvi.ActualWidth);
 }

 Assert.AreEqual(minWidth, SUT.ActualWidth);
}
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/contributing/guidelines/creating-tests.md

---
uid: Uno.Contributing.CreatingTests
---

# Guidelines for creating tests

Good test coverage is essential to maintaining Uno stable and free of regressions. Appropriate tests are generally a requirement for bugfix and new feature PRs.

There's no 'one size fits all' strategy to testing UI. Simple in-process unit tests have the traditional advantages of speed and simplicity, but more complex out-of-process testing harnesses are necessary for simulating user interaction and verifying actual screen input. Consequently Uno internally incorporates several different types of tests. These different test strategies complement each other and work together to provide the widest possible coverage.

This guide offers an overview of the various types of tests used within Uno, and shows you how to decide which one is appropriate for testing a given behavior.

The 'TLDR' rule of thumb for adding tests is:

- if you're testing platform-independent functionality, like the dependency property system, [use Uno.UI.Tests](../../uno-development/creating-mocked-tests.md);
- if you're testing platform-dependent functionality that can be verified programmatically in-process, like checking that a control is measured and arranged properly, [use Uno.UI.RuntimeTests](../../uno-development/creating-runtime-tests.md);
- if your test needs to simulate user interaction or check that the final screen output is correct, [use SamplesApp.UITests](../../uno-development/creating-ui-tests.md).

## Types of tests

These are the main types of tests in Uno:

 Test type                   | Location
 --------------------------- | ---------------------------------------------------------------------------------
 UI tests                    | <https://github.com/unoplatform/uno/tree/master/src/SamplesApp/SamplesApp.UITests>
 Unit tests                  | <https://github.com/unoplatform/uno/tree/master/src/Uno.UI.Tests>
 Platform runtime unit tests | <https://github.com/unoplatform/uno/tree/master/src/Uno.UI.RuntimeTests>
 XAML code generation tests  | <https://github.com/unoplatform/uno/tree/master/src/SourceGenerators/XamlGenerationTests>
 UI snapshot tests           | <https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared>

 All these tests are run on each CI build, and all tests must pass before a PR can be merged.

### UI tests

Uno's UI tests use the [Uno.UITest](https://github.com/unoplatform/Uno.UITest) testing harness, which mimics the [`Xamarin.UITest` API](https://learn.microsoft.com/appcenter/test-cloud/uitest/) and extends it to WebAssembly. These tests run out-of-process and interact with a running app (the [SamplesApp](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared)) to confirm that it behaves correctly on each supported platform.

UI tests can mimic the actions of a user:

- tapping buttons and other UI elements
- entering keyboard input
- scrolling, swiping, and other gestures

They can verify assertions about the state of the app:

- text labels
- any DependencyProperty value
- onscreen bounds of a view element
- comparing screenshots at different stages of the app, and asserting equality or inequality

A complete set of instructions for authoring UI tests is available in [Using the SamplesApp documentation](../../uno-development/working-with-the-samples-apps.md).

Although only a subset of the samples in the SamplesApp are covered by automated UI tests, _all_ samples are screen-shotted on every build, and a reporting tool (runs on Skia, Wasm, Android, and iOS) reports any screenshots that differ from the previous build. Currently, the build isn't gated on these checks, but this may be adjusted in the future.

> [!NOTE]
> Platform runtime tests are generally preferred to UI tests as their execution performance is generally faster than UI Tests.

### Unit tests (`Uno.UI.Tests`)

These are 'classic' unit tests which are built against a mocked version of the `Uno.UI` assembly.

These tests are ideal for testing platform-agnostic parts of the code, such as the dependency property system. They [have access to](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/src/Uno.UI/AssemblyInfo.cs#L7) internal Uno.UI members, and the mocking layer allows values to be read or written which can't be accessed via the 'real' API.

### Platform runtime tests (`Uno.UI.RuntimeTests`)

Again these are 'classic' unit tests, but they are run 'in-process' on the actual target platform, using the 'real' Uno.UI assemblies. They can be run locally through the [Unit Tests Runner](https://github.com/unoplatform/uno/blob/master/src/SamplesApp/SamplesApp.Shared/Samples/UnitTests/UnitTestsPage.xaml) sample in the SamplesApp.

These tests are useful for testing behavior which can run synchronously, or on the UI Thread and where correctness can be asserted programmatically. Relative to the unit tests, they have the advantage that platform-dependent behavior can be tested, and also that the same test can easily be run on WinUI by compiling and running the Windows head of the SamplesApp, giving confidence that the test is verifying the correct behavior.

The platform runtime tests also have access to internal Uno.UI members if need be, but when possible they should be restricted to the public API, since this allows them to be run on WinUI as just mentioned.

### XAML code generation tests (`XamlGenerationTests`)

These specifically target [the parser](https://github.com/unoplatform/uno/tree/master/src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator) which generates C# code from XAML files. They are 'tests' in a simple sense that if the parser throws an error, or if it generates invalid C# code, they will fail the CI build.

If you want to actually test that generated XAML produces correct behavior, which will be the case most of the time, you should use one of the other test types.

### Source generator tests

These can be used to assert that a given input to a given source generator produces specific expected diagnostics. The infrastructure for the tests easily allows to test the generator output exactly, but you should avoid that kind of assertion if you can. These tests exist in [`Uno.UI.SourceGenerators.Tests`](https://github.com/unoplatform/uno/tree/master/src/SourceGenerators/Uno.UI.SourceGenerators.Tests).

### UI snapshot tests

These are 'semi-automated' tests that takes a screenshot of each sample in the [SamplesApp](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared).

On Android, iOS, and Wasm, a minimal UI test is [generated](https://github.com/unoplatform/uno/blob/master/src/SamplesApp/SamplesApp.UITests.Generator/SnapShotTestGenerator.cs) which simply runs the sample (which automatically takes a screenshot of the loaded sample).

On Skia and macOS, we [loop over the samples and load them](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/src/SamplesApp/SamplesApp.UnitTests.Shared/Controls/UITests/Presentation/SampleChooserViewModel.cs#L364-L427), then [save a screenshot](https://github.com/unoplatform/uno/blob/b1a6eddcad3bcca6d9756b0a57ff6cf458321048/src/SamplesApp/SamplesApp.UnitTests.Shared/Controls/UITests/Presentation/SampleChooserViewModel.cs#L1221-L1244) of each sample using `RenderTargetBitmap` and `BitmapEncoder`. This is generally faster than relying on UI tests.

The screenshots from each sample, as well as all screenshots generated by the main UI tests (using the `TakeScreenshot()` method), are [compared](https://github.com/unoplatform/uno/tree/master/src/Uno.UI.TestComparer) with the same sample from the most recent merged CI build.

**Failed** comparisons will not fail the build (for one thing, it's possible the differences are expected or even desired). Instead, a report is generated, with a summary added to the PR as a comment listing all samples that changed. The onus is on the PR author to manually review these changes to ensure that no regressions have been introduced.

Screenshots can be viewed by going to the CI build (from the main PR summary, press the 'Details' link for the build), opening the **Tests** tab, and opening **Attachments** for individual tests. For failed comparisons, one attachment will be a per-pixel XOR with the screenshot from the previous build, which will give some insight into why the comparison failed. Attached screenshots also contain multiple versions of the same screenshot from previous successful builds of the target branch (e.g. master or main). The file name for those screenshots contains a leading number for which the highest is from your current build.

Note: there may be 'false positives' in the comparison results due to inherently 'noisy' samples: ones with animated content, ones that show a timestamp, etc. It's possible to exclude screenshots for specific samples and/or UI tests.

### Excluding snapshots from comparison

Skip screenshot for static sample using `IgnoreInSnapshotTests`:

```csharp
namespace Uno.UI.Samples.Content.UITests.ButtonTestsControl;

[Sample("Button", IgnoreInSnapshotTests = true)]
public sealed partial class CheckBox_Button_With_CanExecute_Changing : UserControl
{
  ...
}
```

Skip screenshot comparison for UI tests:

```csharp
[Test]
[AutoRetry]
public void TimePicker_Flyout()
{
  Run("UITests.Shared.Windows_UI_Xaml_Controls.TimePicker.TimePicker_Flyout_Automated", skipInitialScreenshot: true);

  ...

  TakeScreenshot("TimePicker - Flyout", ignoreInSnapshotCompare: true);
}
```

## Which type of test should I create?

The UI tests are in some sense the most powerful means of testing behavior, since they can simulate real user input and verify the state of the running app. However they're also typically more time-consuming to author, and take several orders of magnitude longer to run , which affects both your own personal development loop and also very importantly the running time of the CI build. Sometimes, a UI test is a sledgehammer where you only need... some... smaller hammer.

As a rule of thumb, if the behavior you're testing can be verified by a unit test (in `Uno.UI.Tests`) or a runtime test (in `Uno.UI.RuntimeTests`), you should write it as such.

If you're fixing a bug that can be verified by a static sample, create a SamplesApp sample that can be monitored by the snapshot comparer.

If you're fixing a bug that involves user interaction or multiple asynchronous UI operations, or you want a hard verification of the onscreen visual state, then create a UI test.

## What can't be tested?

Some UI behaviors are difficult to test in an automated fashion, such as transient animations.

Some non-UI APIs may not be testable in the emulated environment on the CI build.

If you're working on something that falls under one of these descriptions, you should add a [sample](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared) that covers the bug or feature you're working on, and verify that the existing samples in the same feature category aren't negatively affected by your changes. Also, you should mark such sample as a manual test. For more information about manual tests, see [Adding a manual test sample section in Using the SamplesApp documentation](../../uno-development/working-with-the-samples-apps.md#adding-a-manual-test-sample).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/creating-ui-tests.md

---
uid: Uno.Contributing.CreateUITests
---

# Creating automated UI tests

Internally Uno.UI uses automated UI tests using the [Uno.UITest framework](https://github.com/unoplatform/Uno.UITest). These tests run out-of-process relative to the application itself. They can simulate user interaction, and can also record and verify on-screen pixels.

UI tests contribute significantly to the CI build time, and for many purposes a test in [Uno.UI.RuntimeTests](creating-runtime-tests.md) could be sufficient. You should write a `Uno.UITest`-based UI test if:

- you need user interaction to put the app in a state that reproduces the bug, and/or
- you need to verify the final visual output onscreen.

 Conversely, you can use an in-process unit test in Uno.UI.RuntimeTests if:

- you can put the app in the required state programmatically, and
- you can verify the correct behavior programmatically (eg by checking DesiredSize, ActualWidth/ActualHeight etc).

  For more on general testing strategy in Uno.UI, see [Guidelines for creating tests](../contributing/guidelines/creating-tests.md).

> [!NOTE]
> [Platform runtime unit tests](../contributing/guidelines/creating-tests.md) are generally preferred to UI tests as their execution performance is generally faster than UI Tests.

## Running UI tests locally

1. Ensure [your environment is configured](xref:Uno.GetStarted.vs2022) for the platform you want to run on.
1. Ensure `UnoTargetFrameworkOverride` is set to `net7.0-android` for testing on Android, `net7.0-ios` for testing on iOS, and `net7.0` for testing on Wasm.
1. Open Uno.UI with the [correct target override and solution filter](building-uno-ui.md) for the platform you want to run on.
1. [Build and run the SamplesApp](working-with-the-samples-apps.md) at least once.
1. Only Android and WASM are supported from Visual Studio for Windows. (Running tests on iOS using a Mac is possible, see additional instructions below.)
1. If testing on WebAssembly, ensure that [`WebAssemblyDefaultUri`](https://github.com/unoplatform/uno/blob/master/src/SamplesApp/SamplesApp.UITests/Constants.cs) matches Url used when the sample app was launched in the step above. Visual Studio may change the Url on demand to avoid conflicts with already running sites on the same machine.
1. Open the [Test Explorer](https://learn.microsoft.com/visualstudio/test/run-unit-tests-with-test-explorer) in Visual Studio.
1. UI tests are grouped under 'SamplesApp.UITests'. From the Test Explorer you can run all tests, debug a single test, etc.

> [!IMPORTANT]
> Running the UI tests won't automatically rebuild the SamplesApp. If you add or modify samples, make sure to re-deploy the SamplesApp before you try to run UI tests against your modifications.

### Troubleshooting

- For Android, ensure that your system-level environment variables `JAVA_HOME` and `ANDROID_HOME` are set to the same values as the ones set in Visual Studio's Xamarin Android options panel. Note that you may need to restart Visual Studio once the variables have been set. You may need to set these values if you get this message when running tests:

   ```console
   Failed to execute: C:\Program Files\Android\Jdk\microsoft_dist_openjdk_1.8.0.25\bin\keytool.exe -J-Duser.language=en -list -v -alias androiddebugkey -keystore
   ```

- For Android, ensure that you are running hardware accelerated emulators. See [this documentation for details](https://learn.microsoft.com/xamarin/android/get-started/installation/android-emulator/hardware-acceleration?pivots=windows).

## Adding a new test

1. Typically the first step is to [add a sample to the SamplesApp](working-with-the-samples-apps.md) that reproduces the bug you're fixing or demonstrates the functionality you're adding, unless you can do so with an existing sample.
2. The UI test fixtures themselves are located in [SamplesApp.UITests](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/SamplesApp.UITests). Locate the test class corresponding to the control or class you want to create a test for. If you need to add a new test class, create the file as `Namespace_In_Snake_Case/ControlNameTests/ControlName_Tests.cs`. The class should inherit from `SampleControlUITestBase` and be marked with the `[TestFixture]` attribute.
3. Add your test, making sure to include the `[Test]` and `[AutoRetry]` attributes. (The `[AutoRetry]` attributes indicates that the test should be retried if it fails. Currently it's required for all tests.)

## Selectively ignore tests per platform

It may be that some UI Tests are platform specific, or that some tests may not work on a particular platform.

The `ActivePlatformsAttribute` allows to specify which platform are active for a given test.

This attribute is used as follows:

```csharp
[ActivePlatforms(Platform.iOS, Platform.Browser)] // Run on iOS and Browser.
```

This attribute can be placed at the test or class level.

## Test format

The basic structure of a UI test is to run one of the samples from the SamplesApp, issue instructions that mimic user interaction, and then verify the correct state of the program, either via programmatic properties or by inspecting the visible display.

A simple complete test is presented below.

The `[ActivePlatforms]` attribute restricts the test to only run on the listed platforms. In this case it's there because the bug in question still needs to be fixed on WebAssembly.

The `Run()` method launches the sample used for the test. The `_app` field, defined on `SampleControlUITestBase`, provides hooks to interact with the running application. Using `_app.Marked("ControlName")` we can retrieve a [query](https://github.com/unoplatform/Uno.UITest/blob/master/src/Uno.UITest.Helpers/Helpers/UITests.Queries/Query.cs) for the visual element designated `x:Name="ControlName"`. Queries can be used to interact with and retrieve information from visual elements; in many cases, there are overrides that also allow passing the name string directly.

The `_app.WaitForElement(element)` method will wait until the designated element is loaded and available. It's always important to remember when writing UI tests that the interactions you program will not execute synchronously. You must explicitly wait for a condition that confirms that the expected change has occurred. `WaitForElement()` and `WaitForText()` are two common ways to do this.

The `TakeScreenshot()` method, as the name suggests, takes a screenshot of the application in its current state. This can be visually analyzed in the running test, and it will also be available as an attachment in the tests browser on the CI.

The `_app.FastTap()` method simulates the user tapping on an element in the app, in this case a button. (It's called `FastTap()` because it's more performant than the `_app.Tap()` method.)

The `_app.WaitForText("ElementName", "ExpectedText")` method waits until the `TextBlock` named "ElementName" is displaying "ExpectedText", as a confirmation that the button was tapped and the visual tree has had time to update. The `WaitForText()` method is a convenience wrapper for the generalized `WaitForDependencyPropertyValue()` method, which allows any public 'DependencyProperty` value to be waited upon.

Finally, we take another screenshot, and then use the `ImageAssert` class to verify that the onscreen display has changed as expected.

```csharp
[TestFixture]
public class LinearGradientBrush_Tests : SampleControlUITestBase
{
 [Test]
 [AutoRetry]
 [ActivePlatforms(Platform.Android, Platform.iOS)] // This should be enabled for WASM once it no longer uses the LEGACY_SHAPE_MEASURE code path - https://github.com/unoplatform/uno/issues/2983
 public void When_GradientStops_Changed()
 {
  Run("UITests.Windows_UI_Xaml_Media.GradientBrushTests.LinearGradientBrush_Change_Stops");

  var rectangle = _app.Marked("GradientBrushRectangle");

  _app.WaitForElement(rectangle);

  var screenRect = _app.GetRect(rectangle);

  var before = TakeScreenshot("Before");

  _app.FastTap("ChangeBrushButton");

  _app.WaitForText("StatusTextBlock", "Changed");

  var after = TakeScreenshot("After");

  ImageAssert.AreNotEqual(before, after, screenRect);
 }
}
```

## Running iOS UI Tests in a Simulator on macOS

Running UI Tests in iOS Simulators on macOS requires, as of VS4Mac 8.4, to build and run the tests from the command line. Editing the Uno.UI solution is not a particularly stable experience yet.

In a terminal, run the following:

```bash
cd build
./test-scripts/local-ios-uitest-run.sh
```

The Uno.UI solution will build, and the UI tests will run. You may need to adjust some of the parameters in the script, such as:

- `UITEST_SNAPSHOTS_ONLY` which runs automated or snapshots tests
- `UITEST_SNAPSHOTS_GROUP` which controls which group of tests will be run. Note that this feature is mainly used for build performance, where tests from different groups can be run in parallel during the CI.

## Uno.UITest

[`Uno.UITest`](https://github.com/unoplatform/Uno.UITest) is a standalone UI testing framework with an API very similar to the [Xamarin.UITest framework](https://learn.microsoft.com/appcenter/test-cloud/frameworks/uitest/), allowing tests written for 'Xamarin.UITest' to be imported with little or no modifications and additionally run on Uno WebAssembly apps.

On Android and iOS, `Uno.UITest` is actually a thin wrapper over `Xamarin.UITest`, this means for example that you can [use the REPL](https://learn.microsoft.com/appcenter/test-cloud/frameworks/uitest/#using-the-repl) while authoring a test.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.toolkit.ui/refs/heads/main/doc/cupertino-getting-started.md

---
uid: Toolkit.GettingStarted.Cupertino
---
# Uno Cupertino Toolkit Library

The Uno Cupertino Toolkit library is available as NuGet packages that can be added to any new or existing Uno solution.

## Installation

> [!NOTE]
> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.vs2022).

### Creating a new project with the Uno Material Toolkit

1. Install the [`dotnet new` CLI templates](xref:Uno.GetStarted.dotnet-new) with:

    ```bash
    dotnet new install Uno.Templates
    ```

2. Create a new application with:

    ```bash
    dotnet new unoapp -o CupertinoToolkitApp -toolkit -theme cupertino
    ```

---

### Installing Uno Cupertino Toolkit in an existing project

Depending on the type of project template that the Uno Platform application was created with, follow the instructions below to install the Uno Cupertino Toolkit.

#### [**Single Project Template**](#tab/singleproj)

1. Edit your project file (`PROJECT_NAME.csproj`) and add `Toolkit` and `Cupertino` to the list of `UnoFeatures`:

    ```xml
    <UnoFeatures>Toolkit;Cupertino</UnoFeatures>
    ```

2. Initialize the resources in the `App.xaml`:

    ```xml
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>

                <!-- Code omitted of brevity -->

                <!-- Load Cupertino resources -->
                <CupertinoColors xmlns="using:Uno.Cupertino"  />
                <CupertinoFonts xmlns="using:Uno.Cupertino"  />
                <CupertinoResources xmlns="using:Uno.Cupertino" />

                <!-- Load Cupertino Toolkit resources -->
                <ToolkitResources xmlns="using:Uno.Toolkit.UI" />
                <CupertinoToolkitResources xmlns="using:Uno.Toolkit.UI.Cupertino" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
    ```

#### [**Multi-Head Project Template (Legacy)**](#tab/multihead)

1. In the Solution Explorer panel, right-click on your app's **App Code Library** project (`PROJECT_NAME.csproj`) and select `Manage NuGet Packages...`
2. Install the [`Uno.Toolkit.WinUI.Cupertino`](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Cupertino)
3. Add the resources to `AppResources.xaml`:

    ```xml
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>

            <!-- Load Cupertino resources -->
            <CupertinoColors xmlns="using:Uno.Cupertino"  />
            <CupertinoFonts xmlns="using:Uno.Cupertino"  />
            <CupertinoResources xmlns="using:Uno.Cupertino" />

            <!-- Load Cupertino Toolkit resources -->
            <ToolkitResources xmlns="using:Uno.Toolkit.UI" />
            <CupertinoToolkitResources xmlns="using:Uno.Toolkit.UI.Cupertino" />

        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
    ```

#### [**Shared Project (.shproj) Template (Legacy)**](#tab/shproj)

1. In the Solution Explorer panel, right-click on your solution name and select `Manage NuGet Packages for Solution ...`. Choose either:
     - The [`Uno.Toolkit.UI.Cupertino`](https://www.nuget.org/packages/Uno.Toolkit.UI.Cupertino/) package when targetting Xamarin/UWP
     - The [`Uno.Toolkit.WinUI.Cupertino`](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Cupertino) package when targetting net6.0+/WinUI

2. Select the following projects for installation:
    - `PROJECT_NAME.Wasm.csproj`
    - `PROJECT_NAME.Mobile.csproj` (or `PROJECT_NAME.iOS.csproj`, `PROJECT_NAME.Droid.csproj`, and `PROJECT_NAME.macOS.csproj` if you have an existing project)
    - `PROJECT_NAME.Skia.Gtk.csproj`
    - `PROJECT_NAME.Skia.WPF.csproj`
    - `PROJECT_NAME.Windows.csproj` (or `PROJECT_NAME.UWP.csproj` for existing projects)
3. Add the following resources inside `App.xaml`:

    ```xml
    <Application ...>
        <Application.Resources>
            <ResourceDictionary>
                <ResourceDictionary.MergedDictionaries>

                    <!-- Load WinUI resources -->
                    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />

                    <!-- Load Cupertino resources -->
                    <CupertinoColors xmlns="using:Uno.Cupertino"  />
                    <CupertinoFonts xmlns="using:Uno.Cupertino"  />
                    <CupertinoResources xmlns="using:Uno.Cupertino" />

                    <!-- Load Cupertino Toolkit resources -->
                    <ToolkitResources xmlns="using:Uno.Toolkit.UI" />
                    <CupertinoToolkitResources xmlns="using:Uno.Toolkit.UI.Cupertino" />

                    <!-- Load custom application resources -->
                    <!-- ... -->

                </ResourceDictionary.MergedDictionaries>
            </ResourceDictionary>
        </Application.Resources>
    </Application>
    ```

---

## Customization

For instructions on changing the default color palette or the font family, please refer to the [Uno Cupertino Customization guide](xref:Uno.Themes.Cupertino.GetStarted#customization).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/cursors.md

---
uid: Uno.Features.Cursors
---

# Using pointer cursors

You can change the pointer cursor when the pointer hovers certain elements in your application at runtime on WebAssembly, macOS, or Skia Desktop by making a subclass of the `UIElement` of interest and setting its protected `ProtectedCursor` property, for example by adding a method in the the subclass.

```csharp
public void ChangeCursor(InputCursor cursor)
{
    this.ProtectedCursor = cursor;
}
```

Note that you must perform this action on the UI thread. For more details on how to use `ProtectedCursor`, follow this [discussion](https://github.com/microsoft/WindowsAppSDK/discussions/1816).

Note that the legacy `CoreWindow.PointerCursor` API is no longer supported.

## Changing the default cursor for button-based controls on WASM

To provide a web-like feel of Uno Platform WebAssembly apps, we use the "hand" cursor for "interactive" controls (currently including controls derived from `ButtonBase` and `ToggleSwitch` control). This makes the experience feel familiar to users. If you want your application to feel more like a native application, you can set the `FeatureConfiguration.Cursors.UseHandForInteraction` to `false`:

```csharp
Uno.UI.FeatureConfiguration.Cursors.UseHandForInteraction = false;
```

Make sure to set this property early in the application lifecycle, before the window content is first set, for example at the beginning of the `Main` method in `Program.cs`, which is located in the WASM project.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/custom-fonts.md

---
uid: Uno.Features.CustomFonts
---

# Custom Fonts

The `FontFamily` of many controls (e.g. `TextBox` or `Control`) property allows you to customize the font used in your application's UI. Please note that in the following examples, `yourfont.ttf` is a placeholder for the font file name, and `Your Font Name` is a placeholder for its actual name. Use a font management app to make figuring out the correct format easier. The free application, [Character Map](https://www.microsoft.com/store/productId/9WZDNCRDXF41), can be used to extract the full string for your selected font:

![Character Map UWP providing font information](../Assets/features/customfonts/charactermapuwp.png)

## Default text font

The default text font on WinUI is [Segoe UI](https://learn.microsoft.com/en-us/typography/font-list/segoe-ui). However, Segoe UI isn't available on macOS, Linux, or Browsers running on macOS or Linux.

In order to get a consistent experience across targets, Uno Platform 5.3 or later automatically sets the default text font to OpenSans by using the [Uno.Fonts.OpenSans](https://nuget.org/packages/Uno.Fonts.OpenSans) NuGet package. This font is used on all targets except Windows App SDK, where Segoe UI continues to be used.

### Disabling Open Sans

If you are upgrading to 5.3 or later and your project uses the Uno.Sdk, but want to keep the legacy behavior (Segoe UI), add `<UnoDefaultFont>None</UnoDefaultFont>` to a `PropertyGroup` in `Directory.Build.props` or your `.csproj`.

### Using Open Sans in non-Uno.Sdk projects

If you are not using Uno.Sdk (Uno Platform 5.1 or earlier project templates), Segoe UI remains the default font even when using Uno Platform 5.3 and later. To switch to OpenSans, add a `PackageReference` to `Uno.Fonts.OpenSans` and also set `DefaultTextFontFamily` in the `App.xaml.cs` file:

```csharp
global::Uno.UI.FeatureConfiguration.Font.DefaultTextFontFamily = "ms-appx:///Uno.Fonts.OpenSans/Fonts/OpenSans.ttf";
```

## Adding a custom font in the App assets folder

In order to use a custom font in your application:

1. Add font file in a folder named `Assets/Fonts` in your application's **App Code Library** project. It should be using the `Content` build action (as seen in the properties for that file).
2. Reference it using the `ms-appx:///` scheme:

   ```xml
   <Setter Property="FontFamily" Value="ms-appx:///Assets/Fonts/yourfont.ttf#Your Font Name" />
   ```

   > [!TIP]
   > If your font is located in a **Class Library**, you'll need to use a path like `ms-appx:///MyClassLibrary1/Assets/Fonts/yourfont.ttf#Your Font Name`. You will need to replace `MyClassLibrary1` by the name class library project, or its `AssemblyName` if it was changed manually.

## Variable fonts and font manifest

Variable fonts are font files that can store multiple variants. They contain axes that define an aspect of design that can be varied. Common axes are width (`wdth`), weight (`wght`), italic (`ital`), and slant (`slnt`).

The width axis corresponds to `FontStretch` property in Uno Platform and WinAppSDK, the weight axis corresponds to the `FontWeight` property, and italic and slant axes correspond to the `FontStyle` property.

Variable fonts are currently properly supported on Android and Wasm, have partial support on iOS\*, and not supported on Skia due to [SkiaSharp issue](https://github.com/mono/SkiaSharp/issues/2318).

\* on Android and Wasm, if you set an aspect of a font that the variable font file doesn't have an axis for, the platform fakes it. For example, a variable font may have width and weight axes but not italic or slant. If you try to use italic, the platform will make "faux" italic. However, iOS doesn't have this behavior, which makes using variable fonts problematic in some cases.

To overcome the issues on Skia and iOS, we introduced the font manifest in Uno Platform 5.3. A font manifest is a JSON file that maps weight, stretch, and style to a static font. Note that the font manifest is only supported on Skia and iOS because other platforms don't need it.

### High level overview of how font manifest work

When you specify `FontFamily="ms-appx:///path/to/myfont.ttf`:

- On iOS and Skia, we check if `ms-appx:///path/to/myfont.ttf.manifest` exists. From there, we find the correct static font file to use.
- On other platforms, `ms-appx:///path/to/myfont.ttf` will be used right away. When this file is a variable font, it will work as expected.

### Example manifest file

You can see an example manifest file from `Uno.Fonts.OpenSans` NuGet package on [uno.fonts GitHub repository](https://github.com/unoplatform/uno.fonts/blob/cbb838712a299f9da4b424b9b5152cacccb15466/nuget/OpenSans/Uno.Fonts.OpenSans/Fonts/OpenSans.ttf.manifest).

## Fonts preloading on WebAssembly

On Wasm platform, fonts files are loaded by the browser and can take some time to load, resulting in performance degradation and potential flickering when the font is actually available for rendering. In order to prevent this, it is possible to instruct the browser to preload the font before the rendering:

```csharp
// Preloading of font families on Wasm. Add this before the Application.Start() in the Program.cs

public static void Main(string[] args)
{
    // Add this in your application to preload a font.
    // You can add more than one, but preloading too many fonts could hurt the user experience.
    // IMPORTANT: The string parameter should be exactly the same string (including casing)
    //            used as FontFamily in the application.
    Uno.UI.Xaml.Media.FontFamilyHelper.PreloadAsync("ms-appx:///[MyApp]/Assets/Fonts/yourfont01.ttf#ApplicationFont01");
    Uno.UI.Xaml.Media.FontFamilyHelper.PreloadAsync("https://fonts.cdnfonts.com/s/71084/antikythera.woff#Antikythera");

    // Preloads a font which has been specified as a CSS font, either with a data uri or a remote resource.
    Uno.UI.Xaml.Media.FontFamilyHelper.PreloadAsync("Roboto");

    Microsoft.UI.Xaml.Application.Start(_ => _app = new App());
}
```

Uno Platform for WebAssembly also supports remote fonts directly from the XAML, but it is exclusively supported on WebAssembly:

```xml
<!-- This is exclusive to Wasm platform -->
<Setter Property="FontFamily" Value="https://fonts.cdnfonts.com/s/71084/antikythera.woff#Antikythera" />
```

> [!NOTE]
> The `#` part is optional and is there for cross-platform compatibility. It is completely ignored on Uno WASM and can be omitted.

## Custom Fonts Notes

Please note that some custom fonts need the `FontFamily` and `FontWeight` properties to be set at the same time in order to work properly on `TextBlock`, `Runs`, and for styles Setters.
If that's your case, here are some examples of code:

```xml
<FontFamily x:Key="FontFamilyLight">ms-appx:///[MyApp]/Assets/Fonts/PierSans-Light.otf#Pier Sans Light</FontFamily>
<FontFamily x:Key="FontFamilyBold">ms-appx:///[MyApp]/Assets/Fonts/PierSans-Bold.otf#Pier Sans Bold</FontFamily>

<Style x:Key="LightTextBlockStyle"
      TargetType="TextBlock">
   <Setter Property="FontFamily"
         Value="{StaticResource FontFamilyLight}" />
   <Setter Property="FontWeight"
         Value="Light" />
   <Setter Property="FontSize"
         Value="16" />
</Style>

<Style x:Key="BoldTextBlockStyle"
      TargetType="TextBlock">
   <Setter Property="FontFamily"
         Value="{StaticResource FontFamilyBold}" />
   <Setter Property="FontWeight"
         Value="Bold" />
   <Setter Property="FontSize"
         Value="24" />
</Style>

<TextBlock Text="TextBlock with Light FontFamily and FontWeight."
         FontFamily="{StaticResource FontFamilyLight}"
         FontWeight="Light" />

<TextBlock Style="{StaticResource BoldTextBlockStyle}">
   <Run Text="TextBlock with Runs" />
   <Run Text="and  Light FontFamily and FontWeight for the second Run."
       FontWeight="Light"
       FontFamily="{StaticResource FontFamilyLight}" />
</TextBlock>
```

## Custom fonts in Uno Platform 4.6 or below

Uno Platform 4.7 introduces a unified way to include fonts in applications, but if you are still using a previous version of Uno Platform, you can use these directions.

### Custom Fonts on Android

Fonts must be placed in the `Assets` folder of the head project, matching the path of the fonts in Windows, and marked as `AndroidAsset`.
The format is the same as Windows:

```xml
<Setter Property="FontFamily" Value="/Assets/Fonts/yourfont.ttf#Your Font Name" />
```

   or

```xml
<Setter Property="FontFamily" Value="ms-appx:///Assets/Fonts/yourfont.ttf#Your Font Name" />
```

### Custom Fonts on iOS

Fonts must be placed in the `Resources/Fonts` folder of the head project, and be marked as
`BundleResource` for the build type.

Each custom font **must** then be specified in the `info.plist` file as follows:

```xml
<key>UIAppFonts</key>
<array>
    <string>Fonts/yourfont.ttf</string>
    <string>Fonts/yourfont02.ttf</string>
    <string>Fonts/yourfont03.ttf</string>
</array>
```

The format is the same as Windows, as follows:

```xml
<Setter Property="FontFamily" Value="/Assets/Fonts/yourfont.ttf#Your Font Name" />
```

or

```xml
<Setter Property="FontFamily" Value="ms-appx:///Assets/Fonts/yourfont.ttf#Your Font Name" />
```

## Custom Fonts on macOS

Fonts must be placed in the `Resources/Fonts` folder of the head project, and be marked as
`BundleResource` for the build type.

The fonts location path **must** then be specified in the `info.plist` file as follows:

```xml
<key>ATSApplicationFontsPath</key>
<string>Fonts</string>
```

> [!IMPORTANT]
> Please note that unlike iOS, for macOS only the path is specified. There is no need to list each font independently.

The format is the same as Windows, as follows:

```xml
<Setter Property="FontFamily" Value="/Assets/Fonts/yourfont.ttf#Your Font Name" />
```

or

```xml
<Setter Property="FontFamily" Value="ms-appx:///Assets/Fonts/yourfont.ttf#Your Font Name" />
```

### Custom fonts on WebAssembly

There are 3 ways to use fonts on the WebAssembly platform:

1. Referencing a **font defined in CSS**: Use a font defined using a `@font-face` CSS clause.

   > [!NOTE]
   > This was the only available way to define and use a custom font before Uno.UI v4.4. This is useful if the application is using externally referenced CSS as those commonly available on a CDN.

2. Referencing a **font file in application assets**: Use a font file (any web-compatible file format, such as `.ttf`, `.woff`, etc...). This can also be used to reference a font hosted elsewhere using an HTTP address.

#### Adding a custom font defined in CSS

First, the font needs to be defined in CSS.

```css
/* First way: defined locally using data uri */
@font-face {
  font-family: "RobotoAsBase64"; /* XAML: <FontFamily>RobotoAsBase64</FontFamily> */
  src: url(data:application/x-font-woff;charset=utf-8;base64,d09GMgABAAA...) format('woff');
}

/* Second way: defined locally using external uri targetting the font file */
@font-face {
  font-family: "Roboto"; /* XAML: <FontFamily>CssRoboto</FontFamily> */
  src: url(/Roboto.woff) format('woff');
}

/* Third way: Use an external font definition, optionally hosted on a CDN. */
@import url('http://fonts.cdnfonts.com/css/antikythera'); /* XAML: <FontFamily>Antikythera</FontFamily> + others available */
```

Second, you can use it in XAML in this way:

```xml
<!-- XAML usage of CSS defined font -->

<TextBlock FontFamily="MyCustomFontAsBase64">This text should be rendered using the font defined as base64 in CSS.</TextBlock>

<TextBlock FontFamily="CssRoboto">This text should be rendered using the roboto.woff font referenced in CSS.</TextBlock>

<TextBlock FontFamily="Antikythera">This text should be rendered using the Antikythera font hosted on a CDN.</TextBlock>
```

> [!NOTE]
> This approach is nice and pretty flexible, but not friendly for multi-targeting. Until Uno.UI v4.4, this was the only way to define custom fonts on this platform.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/customizing-uiapplicationdelegate.md

---
uid: Uno.Features.CustomizingUIApplicationDelegate
---

# Customizing the `UIApplicationDelegate` on iOS

Uno Platform provides the ability to provide custom behavior for `UIApplicationDelegate` on iOS in case of both native- and Skia-based rendering.

## Skia rendering

In Skia-based apps, the `App` type no longer derives from `UIApplicationDelegate`. Instead, Uno Platform provides `Uno.UI.Runtime.Skia.AppleUIKit.UnoUIApplicationDelegate`. If you decide to implement your own application lifecycle handling, create a new type that derives from it:

```csharp
public class MyApplicationDelegate : Uno.UI.Runtime.Skia.AppleUIKit.UnoUIApplicationDelegate
{
    // Your own code or overrides
}
```

You then need to inform Uno Platform to use this custom class instead of the built-in delegate by adjusting the host creation in `Main.iOS.cs`:

```csharp
using Uno.UI.Hosting;

var host = UnoPlatformHostBuilder.Create()
    .App(() => new SamplesApp.App())
    .UseAppleUIKit(builder => builder.UseUIApplicationDelegate<MyApplicationDelegate>())
    .Build();

host.Run();
```

> [!IMPORTANT]
> Make sure to call the `base` methods when you override key application lifecycle methods, so that the internals of Uno Platform are still properly executed.

## Native rendering

Your `App` class already derives from `UIApplicationDelegate`. This means you can directly override the UIKit methods this class provides:

```csharp
public App : Application
{
    // Existing code in App.xaml.cs

    public override bool FinishedLaunching(UIApplication application, NSDictionary launchOptions)
    {
        // Your custom handling

        return base.FinishedLaunching(application, launchOptions);
    }
}
```

> [!IMPORTANT]
> Make sure to call the `base` methods when you override key application lifecycle methods, so that the internals of Uno Platform are still properly executed.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/debugging-inspect-visual-tree.md

---
uid: Uno.Contributing.InspectVisualTree
---

# Inspecting the runtime visual tree of an Uno app

Often the first step in debugging a UI bug is to scrutinize the application's visual tree. The visual tree is derived from the app's layout defined in XAML, but there's not a straightforward 1-to-1 mapping from XAML to runtime visual tree, due to templating, view manipulation in code, etc. Also, by definition if you're getting a UI bug then there's a discrepancy between what you expect based on the XAML and code and the behavior you're actually observing. Don't live in suspense – check the visual tree!

Tools for inspecting the visual tree differ by platform.

## UWP

UWP has by far the easiest and most convenient experience for debugging the visual tree. The small black toolbar at the top center of your app during debugging enable buttons to go to the Live Visual Tree view, directly select a visual element for inspection, and show layouting decorations. The complement to the Live Visual Tree is the Live Property Explorer, which allows you to inspect current values for any property of a view, and even change some of them on the fly.  

![UWP Live Visual Tree](assets/debugging-inspect-visual-tree/UWP-Live-Visual-Tree.jpg)

## Android

There are a couple of options for viewing the visual tree of an Uno app running on Android.

One approach is to use [Android Studio](https://developer.android.com/studio). You can then attach the debugger to your running process and take a snapshot with the [Layout Inspector](https://developer.android.com/studio/debug/layout-inspector), which allows you to select different elements visually, see their properties, see the whole visual tree, etc.

![Android Studio Layout Inspector](assets/debugging-inspect-visual-tree/Android-Layout-Inspector.jpg)

The other approach is to use the [Stetho package](https://www.nuget.org/packages/nventive.Stetho.Xamarin). It integrates into your app with a few lines of code, and then allows you to inspect the visual tree in Chrome. One nice feature is it allows you to press any element on the device's screen to locate it in the visual tree.

Unfortunately neither of these approaches give you an easy way to inspect properties defined on UIElement, FrameworkElement, and other managed types. You can however look at native properties to obtain information like layout size, opacity, etc.

## iOS

In principle it's possible to use Xcode's 'Debug View Hierarchy' feature on any iOS app, including Uno apps. The steps are the following:

1. Launch Xcode
2. Create a dummy iOS app (or open an existing one) - you won't actually run this app.
3. Run the app whose layout you wish to inspect.
4. Set the device or simulator you're using as the active device in the upper toolbar.
5. Select Debug -> Attach to Process -> [name of the app]
6. Once the debugger has successfully attached, select Debug -> View Debugging -> Capture View Hierarchy.

In practice, Xcode is somewhat temperamental, and this approach may fail for some apps. It's recommended to fall back on the breakpoint-based inspection method described below.

## Web

For an Uno.WASM app you can simply use the layout inspection tools built into whatever browser you're using. For example, for Chrome, open the 'Developer tools' panel (`F12`) and select the 'Elements' tab, or just right-click any element in the visual tree and choose 'Inspect.'

![DOM tree in Chrome](assets/debugging-inspect-visual-tree/WASM-DOM-Elements.jpg)

You can configure Uno to annotate the DOM with the values of common XAML properties. Just add the following somewhere in your app's entry point (eg the constructor of `App.cs` or `App.xaml.cs`):

```csharp
#if DEBUG && __WASM__
    // Annotate generated DOM elements with x:Name
    Uno.UI.FeatureConfiguration.UIElement.AssignDOMXamlName = true;
    // Annotate generated DOM elements with commonly-used XAML properties (height/width, alignment etc)
    Uno.UI.FeatureConfiguration.UIElement.AssignDOMXamlProperties = true;
#endif
```

**Note:** for performance reasons, if a _release build_ of Uno.UI is used, `AssignDOMXamlProperties` will only display the values of properties as they were when the element was loaded - that is, they may be stale in some cases. If a _debug build_ of Uno.UI is used, this limitation is lifted and the DOM annotation will reflect the most up-to-date values.

## Retrieving the visual tree through code or at a breakpoint (Android/iOS/WebAssembly/macOS)

It's common enough when debugging Uno to be at a breakpoint and want to quickly know exactly where the view is in the visual tree, that we added a helper method.  

If you're using a debug build of Uno, this is directly available on UIElement as the `public string ShowLocalVisualTree(int fromHeight)` method (for ease of use in the watch window). If you're using the release version of Uno, the same method is available as an extension in UIKit.UIViewExtensions for iOS or Uno.UI.ViewExtensions for Android.  

The method returns the visual tree from a certain 'height' above the target element as an indented string. So if you call ShowLocalVisualTree(2), you'll get the visual subtree from the target element's grandparent down. If you call ShowLocalVisualTree(100), you'll almost certainly get the entire visual tree starting from the root element. The original target is picked out with an asterisk (*) so you can find it.  

![ShowLocalVisualTree() on iOS](assets/debugging-inspect-visual-tree/iOS-ShowLocalVisualTree.jpg)

Similarly to the `ShowLocalVisualTree` method, there is also the `TreeGraph` method that produces a tree with more details suited for troubleshooting visual/layout issue:

```csharp
using Uno.UI.Extensions;
...

private void DebugVT(object sender, RoutedEventArgs e)
{
    var tree = this.TreeGraph();
} // <-- add a breakpoint here
```

![TreeGraph](assets/debugging-inspect-visual-tree/tree-graph.png)

The advantage of this over `ShowLocalVisualTree` is the ability to customize the amount of details, as it has an overload that takes in a `Func<object, string>` to describe the visual tree node:

> [!NOTE]
> For more examples of control details, check out these source files:
>
> - [`DebugVTNode\GetDetails()` method in Toolkit](https://github.com/unoplatform/uno.toolkit.ui/blob/main/src/Uno.Toolkit.UI/Helpers/VisualTreeHelperEx.cs)
> - [`DescribeVTNode\GetDetails()` method in Uno](https://github.com/unoplatform/uno/blob/master/src/Uno.UI/Extensions/ViewExtensions.visual-tree.cs)

```csharp
var tree = this.TreeGraph(Describe);
...


private static string Describe(object x)
{
    if (x is null) return "<null>";

    return new StringBuilder()
        .Append(x.GetType().Name)
        .Append((x as FrameworkElement)?.Name is string { Length: > 0 } xname ? $"#{xname}" : string.Empty)
        .Append(GetPropertiesDescriptionSafe())
        .ToString();

    string? GetPropertiesDescriptionSafe()
    {
        try
        {
            return string.Join(", ", DescribeDetails(x)) is { Length: > 0 } propertiesDescription
                ? $" // {propertiesDescription}"
                : null;
        }
        catch (Exception e)
        {
            return $"// threw {e.GetType().Name}: {e.Message}";
        }
    }
}

private static IEnumerable<string> DescribeDetails(object x)
{
    // add details pertinent to your debug session:
    if (x is FrameworkElement fe)
    {
        yield return $"Actual={fe.ActualWidth:0.#}x{fe.ActualHeight:0.#}";
        yield return $"Constraints=[{fe.MinWidth:0.#},{fe.Width:0.#},{fe.MaxWidth:0.#}]x[{fe.MinHeight:0.#},{fe.Height:0.#},{fe.MaxHeight:0.#}]";
        yield return $"HV={fe.HorizontalAlignment}/{fe.VerticalAlignment}";
    }
    if (x is ScrollViewer sv)
    {
        yield return $"Offset={sv.HorizontalOffset:0.#},{sv.VerticalOffset:0.#}";
        yield return $"Viewport={sv.ViewportWidth:0.#}x{sv.ViewportHeight:0.#}";
        yield return $"Extent={sv.ExtentWidth:0.#}x{sv.ExtentHeight:0.#}";
    }
    if (x is ListViewItem lvi)
    {
        yield return $"Index={ItemsControl.ItemsControlFromItemContainer(lvi)?.IndexFromContainer(lvi) ?? -1}";
    }
}
```

### Retrieving the visual tree of a flyout/popup

You can add a slight delay before dumping the visual tree, giving you time to open the flyout:

```csharp
private async void DebugVT(object sender, RoutedEventArgs e)
{
    // ample time to click on the flyout
    await Task.Delay(5000);

    // grab the popup's root for tree-graphing
    var root = VisualTreeHelper.GetOpenPopupsForXamlRoot(XamlRoot).FirstOrDefault()?.Child;
    var tree2 = root?.TreeGraph();
} // <-- add a breakpoint here
```

This same technique is also useful for when you need the visual tree at certain specific moments, like during mouse-hover, pressed states of some control.

## Tips for interpreting runtime view information

- Look for view types defined in the app's namespace to 'orient yourself' in the visual tree.
- Expect to see more views in the materialized tree than just those defined by XAML. Some are added by default control templates, some are platform-specific, some may be created by code-behind...

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/debugging-templates.md

---
uid: Uno.Contributing.DebuggingTemplates
---

# Debugging Uno Platform Solution templates

The uno platform project contains multiple types of templates:

- `dotnet new` templates
- Visual Studio (2022/2026) Extensions templates (vsix)

Some of the templates are reusing the same sources. For example the full solution template is defined in the vsix project, and building the `dotnet new` template creates a transformed version of the vsix template.

## dotnet new templates

`dotnet new` new templates use the dotnet/templating engine, and are located in the `src/SolutionTemplate/Uno.ProjectTemplates.Dotnet` folder.

To make modifications to those templates and test the result:

- In Visual Studio, open the solution using the [Uno.UI-SolutionTemplates.slnf](building-uno-ui.md) filter
- Right click on the `Uno.ProjectTemplates.Dotnet` project, select `Pack`
- This will create a `Uno.ProjectTemplates.Dotnet.255.255.255.255.nupkg` file
- Install this file using `dotnet new -i C:\[your_path]\bin\Debug\Uno.ProjectTemplates.Dotnet.255.255.255.255.nupkg`
- In another temporary folder, create a new application using the updated templates with `dotnet new unoapp -o MyTestUnoApp01`

Ensure that the application runs properly by building it in Visual Studio and running it on all targets.

Once you're done with debugging the templates, you can go back to the official templates with:

```dotnetcli
dotnet new -i Uno.ProjectTemplates.Dotnet
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/debugging-troubleshooting.md

---
uid: Uno.Debugging.Troubleshooting
---

# Debugging Troubleshooting

This section covers common issues along with simple workarounds to resolve them. If you're hitting roadblocks, you might find a solution here!

## Issue: Breakpoint Misfires on a Line with Multiple Statements

**Problem:**  
When setting a breakpoint on a line with multiple statements, such as:

```csharp
int x = 1; int y = 2;
```

or

```csharp
public object MyObject { get => _myObject; set => _myObject = value; }
```

On **Mobile (Android and iOS)** or **WebAssembly (WASM)**, Mono might only hit the first or last statement due to how it handles sequence points. This makes debugging on such lines unreliable.

**Workaround:**
To ensure proper breakpoint hits, split each statement onto its own line:

```csharp
int x = 1;
int y = 2;
```

```csharp
public object MyObject 
{
    get => _myObject;
    set => _myObject = value;
}
```

Now, Mono will correctly hit each breakpoint as expected.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/debugging-uno-ui.md

---
uid: Uno.Contributing.DebuggingUno
---

# Debugging Uno.UI

> [!NOTE]
> [Find instructions for building the Uno.UI solution here.](xref:Uno.Contributing.BuildingUno)

## Debugging Uno.UI samples

To debug the **SamplesApp** in the Uno.UI solution, which includes an extensive set of samples and test cases for the controls supported by Uno.UI, as well as non-UI features:

1. Clone the repo, and ensure using a short target path, e.g. _D:\uno_ etc.  
   > [!NOTE]
   > This is required to avoid path length limitations in the .NET framework being used by Visual Studio.
2. Open the solution filter in Visual Studio for the target platform you wish to run on, [as detailed here](xref:Uno.Contributing.BuildingUno).
3. Set `SamplesApp.[TargetPlatform]` as the selected Startup Project.
4. Launch the samples app from Visual Studio.

See [this article](working-with-the-samples-apps.md) for more information on working with the SamplesApp and authoring new samples.

## Debugging Uno in another application

It is also possible to debug Uno.UI code in an application outside the Uno.UI solution. The Uno.UI build process has an opt-in mechanism to overwrite the contents of the NuGet cache, causing the application to use your local build of Uno.

> [!NOTE]
> This will **overwrite your local NuGet cache**.

This is useful when debugging a problem that can't easily be reproduced outside the context of the app where it was discovered.

It can even speed up your development loop when working on a new feature or fixing a bug with a standalone repro, because a small 'Hello World' app builds considerably faster than the full SamplesApp.

First, update `global.json` of the app you will be debugging to instead use a `-dev.xxx` version:

```diff
 {
   // To update the version of Uno please update the version of the Uno.Sdk here. See https://aka.platform.uno/upgrade-uno-packages for more information.
   "msbuild-sdks": {
-    "Uno.Sdk": "6.1.23"
+    "Uno.Sdk": "6.2.0-dev.59"
   },
```

The versions of Uno.Sdk are listed on [NuGet.org](https://www.nuget.org/packages/Uno.Sdk/). Typically, you want to use the latest one, in order to match the most recent commit on the `master` branch of uno.

Once `global.json` has been updated, restore your app's solution:

```dotnetcli
dotnet restore
```

Next, determine the _`$(UnoNugetOverrideVersion)` value_ for your selected `-dev.xxx` version:

1. View the specified `Uno.Sdk` package version on NuGet.org, e.g. <https://www.nuget.org/packages/Uno.Sdk/6.2.0-dev.59>
1. Select the **README** tab.
1. On the **README** tab, determine the value of the `UnoVersion*` property.

    For the Uno.Sdk 6.2.0-dev.59 NuGet package, the `UnoVersion*` property is `6.2.0-dev.171`.

    This is the `$(UnoNugetOverrideVersion)` value.

Then, here are the steps to use a local build of Uno.UI in another application:

1. Configure the Uno.UI solution to build for the target platform you wish to debug, [as detailed here](xref:Uno.Contributing.BuildingUno).
1. Close any instances of Visual Studio with the Uno.UI solution opened.
1. Open the solution containing the application you wish to debug to ensure the package is restored and cached.
1. Prepare the application
1. Make a copy of `src/crosstargeting_override.props.sample` and name it as `src/crosstargeting_override.props`.
1. In `src/crosstargeting_override.props`, uncomment the line `<!--<UnoNugetOverrideVersion>xx.xx.xx-dev.xxx</UnoNugetOverrideVersion>-->` and set the `$(UnoNugetOverrideVersion)` value to the value determined in the previous section, e.g. `6.2.0-dev.171`.  You want to use the `UnoVersion*` version here. _Do not mix it up with `Uno.Sdk` version_.
1. Open the appropriate Uno.UI solution filter and build the following:
   - For iOS/Android native, you can right-click on the `Uno.UI` project
   - For WebAssembly/native, you can right-click on the `Uno.UI.Runtime.WebAssembly` project
   - For Skia, you can right-click on the corresponding `Uno.UI.Runtime.Skia.[Win32|X11|macOS|iOS|Android|Wpf]` project.

To debug Uno.UI code in the application, follow these steps (using `FrameworkElement.MeasureOverride()` as an example):

1. Open [`FrameworkElement.cs`](https://github.com/unoplatform/uno/blob/master/src/Uno.UI/UI/Xaml/FrameworkElement.cs) in the Uno.UI solution.
2. Right-click on the `FrameworkElement.cs` tab header in Visual Studio and choose 'Copy Full Path'.
3. Switch to the Visual Studio instance where your application is open.
4. In your application solution, choose File->Open->File... or simply `Ctrl+O`, paste the path to `FrameworkElement.cs` into the file open dialog, and open `FrameworkElement.cs` in the application solution.
5. Put a breakpoint in the `MeasureOverride()` method.
6. Launch the application.
7. You should hit the breakpoint, opening the `FrameworkElement.cs` file, and be able to see local variable values, etc.
8. To revert to the original Uno.UI version from NuGet, simply navigate to the NuGet cache folder (`%USERPROFILE%\.nuget\packages`) and delete the `Uno.UI` folder within it. You may need to close Visual Studio first. The original version will be automatically restored the next time the application builds.

### Tips about the NuGet version override process

- Be aware that setting `UnoNugetOverrideVersion` will **overwrite your local NuGet cache** for the nominated Uno.UI version. Any applications that you build locally will use your local build if they depend on that Uno.UI version.

- Building for Android requires the API level to match the version you specified in `UnoTargetFrameworkOverride`. A common issue is that the app being debugged uses Android 10.0, and `Uno.UI` is built using Android 11.0. You can change the API level in the debugged project's build properties.

- The NuGet override process only works on already installed versions. The best way to ensure that the override is successful is to build the debugged application once before overriding the Uno.UI version the app uses.

- Make sure to close the application that uses the overridden nuget package, to avoid locked files issues on Windows.

- Verify that your updated files are actually used.  View [diagnostic logs](https://learn.microsoft.com/en-us/visualstudio/msbuild/obtaining-build-logs-with-msbuild?view=vs-2022), search for the assembly that you are modifying, and verify that it contains the updated `$(UnoNugetOverrideVersion)` value in the path, e.g. that the `@(RuntimeCopyLocalItems)` item group contains `%USERPROFILE%\.nuget\packages\uno.winrt\6.2.0-dev.171\lib\net9.0-android30.0\Uno.UI.Dispatching.dll` (Windows) or `$HOME/.nuget/packages/uno.winrt/6.2.0-dev.171/lib/net9.0-android30.0/Uno.UI.Dispatching.dll` (Linux, macOS).

### Troubleshooting

It may happen that the package cache for the version you're debugging is corrupted, and the override is not working as intended.

If this is the case:

- In your debugged app, install another package version you've never debugged with
- Make sure to build the app once to populate the NuGet cache
- Rebuild the Uno.UI project (or **Uno.UI.WebAssembly**/**Uno.UI.Runtime.Skia.\***) to replace the binaries with your debug versions
- Rebuild your app and debug it again

## Microsoft Source Link support

Uno.UI supports [SourceLink](https://github.com/dotnet/sourcelink/) and it now possible to
step into Uno.UI without downloading the repository.

Make sure **Enable source link support** check box is checked in **Tools** / **Options**
/ **Debugging** / **General** properties page.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/debugging-wasm.md

---
uid: Uno.Development.DebuggingWasm
---

# Using the WebAssembly C# Debugger

There are two ways to debug a WebAssembly application:

- Using Visual Studio integrated debugger (preferred)
- Using the browser's debugger

## Using Visual Studio

Here's what you need to do to debug an Uno Platform application in Visual Studio (2022 17.3+ or later):

- Install the latest [Uno Platform Visual Studio templates](./get-started-vs-2022.md#install-the-solution-templates)
- Have Chrome or Edge (Chromium based)
- In the NuGet Package Manager, update `Uno.Wasm.Bootstrap` and `Uno.Wasm.Bootstrap.DevServer` 8.0.0 or later
- Ensure that `<MonoRuntimeDebuggerEnabled>true</MonoRuntimeDebuggerEnabled>` is set in your csproj. It is automatically set [when using the Uno.SDK](xref:Uno.Features.Uno.Sdk).
- Ensure that in the `Properties/launchSettings.json` file, the following like below each `launchBrowser` line:

    ```json
    "inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}",
    ```

Then you can start debugging with the VS debugger toolbar:

- Select **MyApp (WebAssembly IIS Express)** or your application name as the debugging target
- Select **Chrome** or **Microsoft Edge** as the Web Browser
- Press <kbd>F5</kbd> or _Debug_ > _Start Debugging_

You should now be able to set breakpoints or do step-by-step debugging of your code.

### Tips for debugging in visual studio

- Some debugger features may not have yet been implemented by the .NET and Visual Studio team. You can take a look at the [dotnet/runtime](https://github.com/dotnet/runtime) repository for more details.
- If the breaking does not hit, make sure that the `inspectUri` lines have been added to the `Properties/launchSettings.json` file.
- Methods with only invocations to generated code (e.g. control constructors with only "InitializeComponent" in it) may not allow placing breakpoints. Add some explicit code in the scope to place breakpoints.

## Using the browser debugger

To debug your application:

- Make the `net9.0-browserwasm` active debugging target framework (right-click **set as startup** in Solution Explorer)
- Ensure that `<MonoRuntimeDebuggerEnabled>true</MonoRuntimeDebuggerEnabled>` is set in your csproj. It is automatically set [when using the Uno.SDK](xref:Uno.Features.Uno.Sdk).
- In the debugging toolbar:

  - Select **MyApp (WebAssembly IIS Express)** as the debugging target
  - Select **Chrome** or **Microsoft Edge** as the Web Browser
  - Make sure script debugging is disabled<br/>
   ![IIS express settings](Assets/quick-start/wasm-debugging-iis-express.png)

- Start the debugging session using <kbd>Ctrl</kbd><kbd>F5</kbd> or _Debug_ > _Start Without Debugging_ from the menu, (<kbd>F5</kbd> will work, but the debugging experience won't be in Visual Studio)
- Once your application has started, press <kbd>Alt</kbd><kbd>Shift</kbd><kbd>D</kbd> (in Chrome, on your application's tab)
- A new tab will open with the debugger or instructions to activate it
![Debugger - New tab with instructions to activate it](Assets/quick-start/wasm-debugger-step-01.png)
- You will now get the Chrome DevTools to open listing all the .NET loaded assemblies on the Sources tab:<br/>
![Debugger - Chrome DevTools listing all the .NET loaded assemblies on the Sources tab](Assets/quick-start/wasm-debugger-step-02.png)
- You may need to refresh the original tab if you want to debug the entry point (Main) of your application.<br/>
![Debugger - The smaller refresh button location in the preview section of the Chrome DevTools](Assets/quick-start/wasm-debugger-step-03.png)

> ### Tips for debugging in Chrome
>
> - You need to launch a new instance of Chrome with right parameters. If Chrome is your main browser
> and you don't want to restart it, install another version of Chrome (_Chrome Side-by-Side_).
> You may simply install _Chrome Beta_ or _Chrome Canary_ and use them instead.
> - Sometimes, you may have a problem removing a breakpoint from code (it's crashing the debugger).
> You can remove them in the _Breakpoints list_ instead.
> - Once _IIS Express_ is launched, no need to press <kbd>Ctrl</kbd><kbd>F5</kbd> again: you simply need to rebuild your
> _WASM_ head and refresh it in the browser.
> - **To refresh an app**, you should use the debugger tab and press the _refresh_ button in the content.
> - **If you have multiple monitors**, you can detach the _debugger tab_ and put it on another window.
> - For breakpoints to work properly, you should not open the debugger tools (<kbd>F12</kbd>) in the app's tab.
> - If you are **debugging a library which is publishing SourceLinks**, you must disable it or you'll
> always see the SourceLink code in the debugger. SourceLink should be activated only on Release build.
> - When debugging in Chrome, <kbd>Ctrl</kbd>+<kbd>O</kbd> brings up a file-search field. That way it's a lot easier to find .cs files versus searching through the whole folder hierarchy.

---

# Source: https://raw.githubusercontent.com/unoplatform/figma-docs/refs/heads/main/get-started/design-to-code.md

---
uid: Uno.Figma.GetStarted.DesignToCode
---

# Design to Code

This section will guide you through the process of generating UI code (XAML or C# Markup) from a Figma document using the [Uno Platform Figma Plugin](https://aka.platform.uno/uno-figma-plugin).

> [!IMPORTANT]
> Is it required to have completed the [Setup](setup.md) section before starting this one.

## Start with a clean copy of the Uno Material Toolkit document

1. Must be in a copy of the _Uno Material Toolkit_ document. If not, follow the [Setup](setup.md) section to create a new copy.
2. Navigate to _Example App_ Figma page

   ![Navigate to Example App page](assets/navigate-example-app-page.png)
3. Locate the _01. Login_ frame, right-click on it and launch the _Uno Platform (Figma to C# or XAML)_ plugin

   ![Launching the plugin by right-clicking on a frame](assets/launch-plugin-right-click.png)

   ... the plugin should launch in the side panel or a module window.
   > [!NOTE]
   > This step assumes the plugin has been closed. If already opened, just select the _01. Login_ frame and continue to the next step.

4. Click the _Refresh_ button to see the selected page in the plugin previewer

   ![Previewing the Login page in the plugin](assets/plugin-render-login.png)
5. Switch to the _Export_ tab, where the generated XAML is displayed

   ![Switching to the Export tab](assets/export-xaml-tab.png)
6. Click the _Copy_ button to copy the generated XAML to the clipboard.

   Alternatively, you can also select the XAML and copy it manually.

> [!NOTE]
> This simple tutorial generates XAML code, but it is also possible to generate C# markup instead.
> Click here for more information: [Overview of C# Markup in Uno Platform](xref:Uno.Extensions.Markup.Overview).

## Next step

This tutorial has shown you how to generate code from a Figma document using the Uno Platform Figma Plugin. The next step is to use that generated code in an app by following the [Create an App](create-an-app.md) guide.

The code generated in this section will be used in this next section.

## See also

<!--* [How it works](xref:Uno.Figma.Overview.HowItWorks) - This section explains how the plugin extracts the information from the Figma file and how this information is used to generate the code.-->
* [Setup](setup.md) - This section explains how to setup your environment to use the plugin.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/dev-server.md

---
uid: Uno.DevServer
---

# Dev Server

The Dev Server is the local development companion that enables productive inner-loop features in Uno Platform, such as Hot Reload, design-time updates, and IDE integration. It runs as a lightweight HTTP process and maintains a bidirectional channel with the IDE and the running application.

## Overview

- Provides a transport between the IDE and the running application to exchange development-time messages
- Powers Hot Reload and Hot Design experiences by delivering code and XAML updates
- Starts automatically and stays out of the way; you usually do not have to configure it

## Prerequisites

- Requires .NET SDK, [same version as uno](xref:Uno.Development.NetVersionSupport)
- Works in Debug builds, where connection information is embedded so the app can reach the Dev Server

## When and how the Dev Server starts

> [!NOTE]
> The Dev Server starts only when Uno Platform packages are referenced by your project(s).
>
> [!NOTE]
> The Dev Server won't start until NuGet package restore has completed successfully (a failed or pending restore prevents startup).

1. Open the solution: the IDE reserves a free TCP port and writes it to each project's .csproj.user file under the UnoRemoteControlPort property.
2. Build/run in Debug: the app is built with the Dev Server connection information.
3. Launch the app (Debug): the app connects back to the Dev Server.
4. Develop: the IDE and app exchange development-time messages (e.g., Hot Reload updates).

## Command-line (advanced usage for specific scenarios)

You can manage the Dev Server from the command line using the dotnet tool `Uno.DevServer` (command: uno-devserver):

- `uno-devserver start`: Start the Dev Server for the current solution directory
- `uno-devserver stop`: Stop the Dev Server attached to the current directory
- `uno-devserver list`: List running Dev Server instances
- `uno-devserver cleanup`: Terminate stale Dev Server processes
- `uno-devserver login`: Open the Uno Platform settings application
- `--mcp-app`: Run an MCP proxy mode for integration with MCP-based tooling
- `--port | -p <int>`: Optional port value for MCP proxy mode
- `--mcp-wait-tools-list`: Wait for the upstream Uno App tools to become available before responding to clients. Use this when working with MCP agents that do not react to `tool_list_changed` (for example, Codex or Claude Code).
- `--force-roots-fallback`: Skip the MCP `roots` handshake and expose the `uno_app_set_roots` tool so agents that cannot send workspace roots can still initialize (required for Google Antigravity).
- `--force-generate-tool-cache`: Immediately request the Uno App tool list once the Dev Server is online and persist it to the local cache. Use this to prime CI environments or agents that expect a tools cache before they can call `list_tools`.
- `--solution-dir <path>`: Explicit solution directory Uno.DevServer should monitor. Useful when starting the DevServer manually (e.g., CI agents) or when priming tools via `--force-generate-tool-cache`. Defaults to the current working directory when omitted.

## Hot Reload

The Dev Server enables Hot Reload for a faster inner loop:

- C# Hot Reload for managed code changes
- XAML and resource updates without restarting the app
- Asset updates in supported scenarios

## Security

- Uses a random local port, making it hard to guess
- Intended for local development only and relies on your local network security
- Do not expose the Dev Server to untrusted networks

> [!IMPORTANT]
> The Dev Server is a development-time facility. It is not required nor recommended for production deployments.

## Troubleshooting

### [**Common issues**](#tab/common-issues)

- The TCP port number used by the app to connect back to the IDE is located in the <UnoRemoteControlPort> property of the [ProjectName].csproj.user file. If the port number does not match with the one found in the Uno Platform - Hot Reload output window, restart your IDE.
- If the Dev Server does not start, ensure NuGet restore has completed successfully and Uno Platform packages are referenced by your project(s).

### [**Visual Studio**](#tab/vswints)

- The Output window in Visual Studio includes an output category named `Uno Platform`. Diagnostic messages from the Uno Platform VS extension appear there. To enable logging, set MSBuild project build output verbosity to at least "Normal" (above "Minimal"). These changes should take effect immediately without a restart; if you do not see additional logs, try restarting Visual Studio. For more details on build log verbosity, refer to the [official Visual Studio documentation](https://learn.microsoft.com/en-us/visualstudio/ide/how-to-view-save-and-configure-build-log-files?view=vs-2022#to-change-the-amount-of-information-included-in-the-build-log).  

    If you need to share logs when opening an issue on the GitHub [Uno Platform repository](https://github.com/unoplatform/uno), set verbosity to **Diagnostic** to provide the most detailed logs for investigation.

    **Steps to change MSBuild output verbosity:**
    1. Open **Tools > Options > Projects and Solutions > Build and Run**, then set **MSBuild output verbosity** to **Diagnostic** or the required level.

       ![MSBuild output verbosity drop-down](Assets/features/hotreload/vs-msbuild-output-verbosity.png)
    2. Restart Visual Studio, re-open your solution, and wait a few seconds.
    3. Go to **View > Output**.
    4. In the Output window, select `Uno Platform` from the drop-down.

       ![Uno Platform output drop-down](Assets/features/hotreload/vs-uno-platform-logs.png)

### [**Visual Studio Code**](#tab/vscodets)

- The Output window in Visual Studio Code includes an output category named `Uno Platform` in its drop-down menu. Diagnostic messages from the Uno Platform VS Code extension appear there.

    **Steps to see the `Uno Platform` output:**  
    1. In the status bar at the bottom left of VS Code, ensure `NameOfYourProject.csproj` is selected (by default `NameOfYourProject.sln` is selected).

       ![.csproj selection in Visual Studio Code](Assets/features/hotreload/vscode-csproj-selection.png)
    2. Wait a few seconds.
    3. Go to **View > Output**.
    4. In the Output window, select `Uno Platform` from the drop-down.

       ![`Uno Platform` output drop-down](Assets/features/hotreload/vs-code-uno-platform-hr-output.png)

### [**Rider**](#tab/riderts)

- The Output window in Rider includes an output category named `Uno Platform` in its sidebar. Diagnostic messages from the Uno Platform Rider plugin appear there.

    **Steps to see the Uno Platform output:**  
    1. In the sidebar at the bottom left of Rider, click on the Uno Platform logo.

       ![Uno Platform output logo](Assets/features/hotreload/rider-uno-platform-output.png)
    2. In the Output window, select **LEVEL: Trace** from the drop-down.

       ![Level output drop-down](Assets/features/hotreload/rider-output-level-trace.png)

---

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/dialogs.md

---
uid: Uno.Features.Dialogs
---

# Dialogs

> [!TIP]
> This article covers Uno-specific information for dialog controls in Uno Platform. For a full description of the feature and instructions on using it, see [Dialog controls | Microsoft Learn](https://learn.microsoft.com/windows/apps/design/controls/dialogs-and-flyouts/dialogs).

* The `Microsoft.UI.Xaml.Controls.ContentDialog` class provides a XAML-based and highly customizable user dialog.
* The `Windows.UI.Popups.MessageDialog` represents a legacy dialog which provides less control over UI.

## Using `ContentDialog`

The recommended way to display user dialogs is via the `Microsoft.UI.Xaml.Controls.ContentDialog` class.

```csharp
ContentDialog noWifiDialog = new ContentDialog
{
    Title = "No WiFi connection",
    Content = "Check your connection and try again.",
    CloseButtonText = "OK"
};

// Make sure to set the XamlRoot!
noWifiDialog.XamlRoot = anyLoadedControl.XamlRoot;

ContentDialogResult result = await noWifiDialog.ShowAsync();
```

It is crucial to set the `XamlRoot` property before calling `ShowAsync`. This way the dialog will become associated with the visual tree. `XamlRoot` can be retrieved from any loaded control in your window (e.g. a `Button`, your `Page`, etc.).

> [!WARNING]
> Only one ContentDialog can be open per thread at a time. Attempting to open two ContentDialogs will throw an exception, even if they are trying to open in separate AppWindows.

### Opening a `ContentDialog` from a Model/ViewModel

When you want to open a `ContentDialog` from a Model or ViewModel, you can pass the `XamlRoot` from the view to the model or view model by creating a service (e.g., `IXamlRootProvider`) that is initialized at the start of the app with the XamlRoot of the main window.

Here is a more detailed example of how to display a `ContentDialog` with result handling:

```csharp
private async Task DisplayDeleteFileDialog()
{
    ContentDialog deleteFileDialog = new ContentDialog
    {
        Title = "Delete file permanently?",
        Content = "If you delete this file, you won't be able to recover it. Do you want to delete it?",
        PrimaryButtonText = "Delete",
        CloseButtonText = "Cancel"
    };

    deleteFileDialog.XamlRoot = anyLoadedControl.XamlRoot;

    ContentDialogResult result = await deleteFileDialog.ShowAsync();

    // Delete the file if the user clicked the primary button.
    // Otherwise, do nothing.
    if (result == ContentDialogResult.Primary)
    {
        // Delete the file.
    }
    else
    {
        // The user clicked the CloseButton, pressed ESC, Gamepad B, or the system back button.
        // Do nothing.
    }
}
```

### [MVVM](#tab/mvvm)

If you are using the MVVM pattern, you can use the `AsyncRelayCommand` from the Uno Platform to bind the command to the dialog display method. Here is an example of how to bind the command to the dialog display method in the ViewModel:

```csharp
public MainViewModel()
{
    DisplayDeleteFileDialogCommand = new AsyncRelayCommand(DisplayDeleteFileDialog);
}

// ...

public ICommand DisplayDeleteFileDialogCommand { get; }

private async Task DisplayDeleteFileDialog()
{
    // ...
}
```

### [MVUX](#tab/mvux)

If you are using the MVUX pattern, you don't need to specify the Command. Instead, you can directly call the dialog display method in your view, it is generated automatically in `BindableModel`:

```csharp
public async Task DisplayDeleteFileDialogCommand()
{
    // ...
}
```

---

To bind the command to a button in your view, you can use the following code snippets:

### [XAML](#tab/xaml)

```xml
<Button Content="Delete file" Command="{Binding DisplayDeleteFileDialogCommand}" />
```

### [C# Markup](#tab/cs-markup)

```csharp
new Button()
    .Content("Delete file")
    .AutomationProperties(automationId: "DeleteFileButton")
    .Command(() => vm.DisplayDeleteFileDialogCommand)
```

---

If you are using Uno.Extensions Navigation, you can utilize its features to display a dialog. For more information, check out this documentation: [Dialogs with Uno.Extensions.Navigation](xref:Uno.Extensions.Navigation.HowToShowDialog).

Considering adding a dialog to your app? Check out our comprehensive video for detailed guidance on the implementation:

> [!Video https://www.youtube-nocookie.com/embed/VAUYH01LMEE]

## Customize a `ContentDialog`

You can use various properties to customize its display and also provide a custom XAML-based content for it. For more information, see [ContentDialog Class | Microsoft Learn](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.contentdialog).

In order for your custom dialog to follow the Fluent design, it's important that you add the following line in the constructor of your dialog:

```csharp
Style = Application.Current.Resources["DefaultContentDialogStyle"] as Style;
```

Your dialog will look similar to this dialog:

![Content dialog with style sample](../Assets/features/contentdialog/withstyle.png)

If you omit this line, your dialog will look like this:

![Content dialog without style sample](../Assets/features/contentdialog/withoutstyle.png)

## Overlay Background (iOS/Android)

You can override the overlay background by adding the following resources to the application resources:

```xml
<SolidColorBrush x:Key="ContentDialogLightDismissOverlayBackground" Color="#99000000" />
```

> [!NOTE]
> There is no specific key to override for this other than `SystemControlPageBackgroundMediumAltMediumBrush` on Windows, see [Changing the Overlay background color for ContentDialog question on StackOverflow](https://stackoverflow.com/a/40397576).

## Using `MessageDialog`

> [!WARNING]
> `MessageDialog` is a legacy API that is no longer officially supported. If possible, please use `ContentDialog` instead.

For existing applications that rely on `MessageDialog`, updating to Uno Platform 5.2 and newer requires you to associate the `MessageDialog` with a window before it is displayed. This can be done via the `WinRT.Interop` APIs:

```csharp
var dialog = new MessageDialog();

// ...

// Get the current window's HWND by passing a Window object
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(window);
// Associate the HWND with the dialog
WinRT.Interop.InitializeWithWindow.Initialize(dialog, hwnd);

await dialog.ShowAsync();
```

### Using native or XAML-based UI for `MessageDialog`

Uno Platform targets offer two different display modes for `MessageDialog`. To switch between them, you can use the [`UseNativeDialog`](../feature-flags.md#messagedialog).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/doc-on-docs.md

---
uid: Uno.Contributing.Docs
---

# Contributing docs to Uno Platform

Good documentation is essential, and writing docs is a valued contribution that makes Uno more useful for everybody. This article covers *when* to write docs and *what* you should write, with a focus on two of the most common forms of documentation: step-by-step guides (ie howtos or tutorials), and feature documentation.

We have a few different fill-in-the-blanks style templates, linked below.

For the DocFX tool used to build the docs website, see [more info here](docfx.md).

## Key links

* how-to template: https://github.com/unoplatform/uno/blob/master/doc/.howto-template.md
* WinUI feature template: https://github.com/unoplatform/uno/blob/master/doc/.feature-template.md
* Uno-only feature template: https://github.com/unoplatform/uno/blob/master/doc/.feature-template-uno-only.md

## Resources

Some useful resources on writing good technical documentation:

* [ReactiveUI docs style guide](https://www.reactiveui.net/contribute/content-style-guide/)
* [Divio's Documentation System](https://documentation.divio.com/)

## Writing step-by-step guides

Step-by-step guides that address a particular problem or use case that multiple developers are likely to encounter.

* For longer tutorials, it's fine to split the content over multiple pages.
* Guides should always be accompanied by working code. Standalone applications should be added to the [Uno.Samples repository](https://github.com/unoplatform/Uno.Samples) and linked to from the associated tutorial.
* Use the [how-to template](https://github.com/unoplatform/uno/blob/master/doc/.howto-template.md) as a starting point.
* Structure guides as a series of clear, actionable steps. After carrying out every step as described, the user should end up with working code that demonstrates the objective of the guide (either a standalone sample, or a new feature in their existing app).

## Documenting features

Let's say you're implementing a new Uno Platform feature. Do you need to add documentation for it?

It depends.

There's two different cases:

### I'm implementing a feature from the WinUI contract

Uno's API matches WinUI's API, and most of the time, a new Uno feature will map to an existing WinUI feature.

In this case, to the extent that the behavior you're adding is the same as the WinUI behavior, you **don't** need to add documentation. The existing WinUI documentation is fine. It's already linked to from [Uno's reference documentation](../implemented-views.md).

What if the Uno behavior deviates from WinUI behavior?

If it's just a case of part of the functionality not being implemented yet, **and** the developer using the corresponding type/method/event would discover that it's marked with the `[NotImplemented]` attribute, then that's fine - there's no need to document it further.

But sometimes the functionality **can't** be supported, due to intrinsic limitations of the target platform. (This is more likely to be the case with non-UI features.) And/or part of the functionality may implicitly fail to work, even though none of the entry points are marked `NotImplemented`.

In those cases, it's important to add documentation. Copy the [WinUI feature template](https://github.com/unoplatform/uno/blob/master/doc/.feature-template.md) to the [features directory](https://github.com/unoplatform/uno/tree/master/doc/articles/features) (or [controls directory](https://github.com/unoplatform/uno/tree/master/doc/articles/controls) for controls inheriting from `FrameworkElement`) and fill in the appropriate sections. Make sure to fill in the matrix describing which features are supported on which platforms.

### I'm implementing a feature that's not part of WinUI

Rarely, features are added to Uno Platform that aren't part of WinUI (`VisibleBoundsPadding` and `ElevatedView` are two examples). Somewhat more commonly, platform-specific functionality or options are added to an existing feature.

It's important to document these novel features when you add them, since they aren't covered anywhere else. Again, copy the [Uno-only feature template here](https://github.com/unoplatform/uno/blob/master/doc/.feature-template-uno-only.md) to the [features directory](https://github.com/unoplatform/uno/tree/master/doc/articles/features) and fill in the sections.

## Updating the documentation from linked repositories

The Uno Platform documentation is aggregated onto https://platform.uno/docs/articles/intro.html, including some repositories that are in the unoplatform GitHub organization.

### Updating the documentation for other repositories

The CI includes a step to clones repositories at a specified commit or branch, and provides the path to the DocFX table of content.

To include documentation (let's take Uno.Themes as an example):

* Update your documentation in `Uno.Themes` repository, preferably in a folder named `doc`
* Include a file named `toc.yml`, using this file as a template:

  ```yml
  items:
  - name: Introduction to Uno Themes
    href: ../Readme.md
  ```

* Once you have merged your changes into `Uno.Themes`' `main` (or the default branch), take the commit id and place it in the `doc/import_external_docs.ps1` of the uno repository, as follows:

   ```powershell
   @("https://github.com/unoplatform/uno.themes", "uno.themes", "INSERT_COMMIT_HASH_OR_BRANCH_NAME"),
   ```

* Create a PR and validate that the content you added is appearing in the Uno Platform `toc.yml` where `external/uno.themes/` is visible. Ensure href path ends by `toc.yml` for all nodes to be visible.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/docfx.md

---
uid: Uno.Contributing.DocFx
---

<!-- markdownlint-disable MD001 -->

# The Uno docs website and DocFX

Uno Platform's docs website uses [DocFX](https://dotnet.github.io/docfx/) to convert Markdown files in the [articles folder](https://github.com/unoplatform/uno/tree/master/doc/articles) into [html files](xref:Uno.Documentation.Intro).

## Adding to the table of contents

Normally when you add a new doc file, you also add it to [articles/toc.yml](https://github.com/unoplatform/uno/blob/master/doc/articles/toc.yml). This allows it to show up in the left sidebar Table of Contents on the docs website.

## DocFX-flavored Markdown

DocFX supports extended Markdown syntaxes that are treated specially when converting to html.

### Formatted blockquotes

You can declare a [specially-styled blockquote](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#note-warningtipimportant) like so:

```md
> [!NOTE]
> This is a Note, showing how to declare notes.
```

This is how it looks when converted to .html:

> [!NOTE]
> This is a Note, showing how to declare notes.

Use pre-formatted blockquotes when you want to call special attention to particular information.

The following note types are supported:

```md
> [!NOTE]
> ...

> [!TIP]
> ...

> [!WARNING]
> ...

> [!IMPORTANT]
> ...

> [!CAUTION]
> ...

```

### Tabs

DocFX can generate tabs. Make sure to follow the [syntax specification](https://dotnet.github.io/docfx/spec/docfx_flavored_markdown.html#tabbed-content) precisely.

#### Example

Markdown:

```md
# [WinUI](#tab/tabid-1)

`WinUI.Namespace`

# [Uno Platform](#tab/tabid-2)

`Uno.Namespace`

---
```

Html output:

# [WinUI](#tab/tabid-1)

`WinUI.Namespace`

# [Uno Platform](#tab/tabid-2)

`Uno.Namespace`

---

### TOC checker script

The [`check_toc` script](https://github.com/unoplatform/uno/blob/master/doc/articles/check_toc.ps1) checks for dead links in the TOC, as well as Markdown files in the 'articles' folder that are not part of the TOC. At the moment it's not part of the CI, but contributors can run it locally and fix any bad or missing links.

<!-- TODO: ## Anchor links -->

## Building docs website locally with DocFX

Sometimes you may want to run DocFX locally to validate that changes you've made look good in html.

### Prerequisites

Before building the documentation locally, ensure you have the following installed:

#### Install DocFX

# [macOS](#tab/tabid-macos)

```bash
brew install docfx
```

# [Windows](#tab/tabid-windows)

```bash
choco install docfx
```

> [!NOTE]
> On Windows, run the `choco install docfx` command from an elevated PowerShell prompt (Run as Administrator) to avoid permission errors.

---

#### Install Node.js

Use a Node.js version manager (nvm or nvs) with the version specified in the `.nvmrc` file in the `doc` folder.

```bash
# Using nvs
nvs use

# Or using nvm
nvm use
```

Then install the npm dependencies:

```bash
cd doc
npm install
```

### Generate implemented views (optional)

"Implemented views" are documentation pages that are generated from the Uno source code to describe how specific APIs are implemented across platforms. They are consumed by DocFX as part of the full docs build, but most day-to-day documentation changes (guides, how-tos, etc.) do not require regenerating them.

You typically only need to generate implemented views when you are working on the tooling that produces them, or when you want to validate a full local DocFX build that includes these generated pages. For most contributors, this step can be safely skipped.

If you do need to generate them:

1. Open the `Uno.UI-Tools.slnf` solution filter in the `src` folder with Visual Studio.
2. Edit the properties of the `Uno.UwpSyncGenerator` project. Under the 'Debug' tab, set Application arguments to "doc".
3. Set `Uno.UwpSyncGenerator` as startup project and run it. It may fail to generate the full implemented views content; if so, it should still nonetheless generate stubs so that DocFX can run successfully.

> [!NOTE]
> By default, the build does not fail on DocFX errors (it prints them in the console). This is for simplicity since you don't need the implemented views for most documentation work. To test DocFX and break on error, run the `npm run strict` command.

### Build and serve the documentation locally

#### Using npm commands (Recommended)

The easiest way to build and serve the documentation locally is using npm scripts:

```bash
cd doc

# Start development server with live reload
npm start
```

This command will:

- Start a local development server with BrowserSync
- Watch for changes in Sass, JavaScript, and DocFX templates
- Automatically rebuild and reload the browser when changes are detected
- Generate source maps for easier debugging
- Serve the documentation at `http://localhost:3000` (or the next available port)

#### Other npm commands

```bash
# Build for production (minified, no source maps)
# Run this before committing changes
npm run build

# Build and serve with production settings
npm run prod

# Build with strict error checking (fails on DocFX errors)
npm run strict

# Clean generated files
npm run clean
```

> [!IMPORTANT]
> Always run `npm run build` before committing changes to ensure the production assets are properly generated and minified.

#### Using DocFX directly

If you prefer to run DocFX directly without npm:

1- Navigate to the `doc` folder.

2- Run DocFX with the configuration file:

```bash
docfx docfx.json
```

3- The generated HTML will be in the `_site` folder.

### Serve the built documentation

After building with DocFX directly, you can serve the documentation using a local HTTP server.

#### Using dotnet-serve

`dotnet-serve` is a simple command-line HTTP server:

1- Install `dotnet-serve`:

```bash
dotnet tool install --global dotnet-serve
```

2- Navigate to the `_site` folder and start the server:

```bash
cd _site
dotnet serve -o -S
```

This will start a server with HTTPS and open the browser automatically.

For more information about `dotnet-serve` usage and options, [please refer to the documentation](https://github.com/natemcmaster/dotnet-serve).

## Testing Algolia DocSearch locally

The documentation website uses Algolia DocSearch for search functionality. The search is configured in `doc/templates/uno/partials/scripts.tmpl.partial`.

### DocSearch configuration

The DocSearch implementation is already integrated into the documentation templates and will work automatically when you serve the documentation locally using `npm start` or after building with `npm run build`.

The search configuration includes:

- **App ID**: `PHB9D8WS99`
- **Index Name**: `platform`
- **Container**: `#docsearch` (located in the sidebar)

### Testing search locally

When running the documentation locally:

1- Start the development server:

```bash
cd doc
npm start
```

2- Open your browser to the local server URL (typically `http://localhost:3000`).

3- The search box should appear in the left sidebar.

4- Type a search query to test the search functionality.

> [!NOTE]
> The search uses the production Algolia index, so search results will reflect the content currently deployed to the live documentation site, not your local changes. To see your local content in search results, your changes need to be deployed to production and the Algolia index needs to be updated.

### How DocSearch works locally

The DocSearch initialization is handled by JavaScript in the `scripts.tmpl.partial` file:

- A `MutationObserver` watches for the `#docsearch` element to be added to the DOM
- When detected, it initializes the Algolia DocSearch widget
- The search connects to the Algolia API to fetch results from the production index

### Debugging DocSearch

If the search isn't working as expected:

1. Open your browser's Developer Tools Console
2. Look for DocSearch initialization messages (e.g., "DocSearch initialized")
3. Check for any errors related to Algolia or DocSearch
4. Verify the `#docsearch` element exists in the DOM (it's in the sidebar's `.sidefilter` div)

## Run the documentation generation performance test

If needed, you can also run a script that will give you a performance summary for the documentation generation.

To run the script on Windows:

1. Make sure `crosstargeting_override.props` is not defining UnoTargetFrameworkOverride
2. Open a Developer Command Prompt for Visual Studio (2019 or 2022)
3. Go to the uno\build folder (not the uno\src\build folder)
4. Run the `run-doc-generation.cmd` script; make sure to follow the instructions

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/explore-your-app-ai-agents.md

---
uid: Uno.BuildYourApp.AI.Agents
---

# Prompting in your App

Once you have a running app, you're setup to have your agent help you develop features.

In the agent chat, ask the following:

  > [!IMPORTANT]
  > The MCP tools are best used by agents when using premium models like Claude 4.5, GPT-5-Codex or GPT-5.

  ```text
  Add a button and a textblock in my main page. Have a button click
  display the current date in the new TextBlock. Make sure to validate
  the app's runtime behavior using your tools.
  ```

Your AI agent will act and use the tools provided by Uno Platform.

## Using the MCP tools

Uno Platform provides two **[MCP](https://modelcontextprotocol.io/docs/getting-started/intro) (Model Context Protocol) servers**, the **Remote Uno MCP** and the **Local App MCP**.

For more detailed information, you can read further on [the tools offered by Uno Platform MCPs](xref:Uno.Features.Uno.MCPs).

### MCP (Remote)

This is hosted publicly and provides:

- A set of tools to search and fetch Uno Platform documentation
- A set of prompts to create and develop Uno Platform applications.

### App MCP (Local)

The Uno App MCP is a runtime service for the Uno Platform that allows large language models (LLMs) or other agent-based tools to intelligently interact with live Uno applications across platforms such as Windows, WebAssembly, macOS, iOS, Android, and Linux, in a real runtime context.

Rather than relying on static UI captures or screenshots, Uno App MCP exposes structured application state (like the Visual Tree, data context, and control properties), enabling rich, meaningful automation and inspection.

It allows tools and agents to:

- Attach to or stop a running Uno application session
- Inspect the application state, such as the visual tree, data context, taking screenshots, not just visual output
- Perform actions like clicking on controls, typing text, navigating pages, or invoking automation peers
- Leverage those interactions for higher-level automation: UI testing, adaptive exploration, telemetry, and intelligent workflow orchestration

In other words: while traditional Uno tests are written and maintained by developers, Uno App MCP opens the door for AI agents or other automation systems to drive and reason about the app autonomously, with deeper context and less manual scripting, across all Uno-supported platforms.

## Sample prompts for MCP tools

In your agent, there are some phrases that can be used to nudge the agent to use the tools.

> [!NOTE]
> Your agent will execute tools from our MCPs, you will need to approve them at your convenience.
> [!NOTE]
> In Visual Studio 2022/2026 MCPs might not be enabled automatically. Make sure to [click the "tools" icon](https://learn.microsoft.com/en-us/visualstudio/ide/mcp-servers?view=vs-2022#configuration-example-with-a-github-mcp-server) in the chat window to check both Uno Platform MCPs.
>
> If the Uno App MCP is missing, see [how to make the App MCP appear in Visual Studio](xref:Uno.UI.CommonIssues.AIAgents#the-app-mcp-does-not-appear-in-visual-studio).

- To ask the agent to explain what MVUX is:

  ```text
  Can you use the uno platform documentation to explain what MVUX is?
  ```

- To ask the agent to take a screenshot and analyze it:

    ```text
    Can you take a screenshot of the running app and describe what you see?
    ```

    > [!NOTE]
    > Some models don't yet support analyzing images, particularly in Visual Studio. Saving a screenshot on disk is always available.

- To ask the agent to click on a specific element on screen:

    ```text
    Can you click the second button on the left, close to the middle of the screen?
    ```

- To ask the agent to click on a specific element on screen:

    ```text
    Can you type "Hello Uno Platform, the MCP is talking!" in the third textbox on the screen?
    ```

- To ask to delete all the text of a textbox

    ```text
    Can you select all the text of the second textbox and delete all of it?
    ```

- To analyze the DataContext of the app:

    ```text
    Can you tell me if there's an object of type "XYZ" in the app's 
    DataContext, starting from the grid in the middle of the screen?
    ```

- To create a more specialized Uno Platform agent:

    ```text
    /mcp.uno.init
    ```

    > [!NOTE]
    > The default command is `/mcp.uno.init`, but depending on the agent you are using, it might be named differently (such as `/uno.init`).

    Which primes the agent with Uno Platform's best practices.

    Then ask the agent to build a new feature:

    ```text
    Let's add a new page in my app that shows the "About" information.
    ```

All those phrases will hint the model to use one or more of the tools to answer your request.

## Troubleshooting MCP Servers

You can find additional information about [troubleshooting AI Agents](xref:Uno.UI.CommonIssues.AIAgents) in our docs.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/faq.md

---
uid: Uno.Development.FAQ
---

# FAQ: General

## About Uno Platform

### What is the Uno Platform?

Uno Platform lets you write an application once in XAML and/or C#, and deploy it to [any target platform](getting-started/requirements.md). Read more in the [Uno Platform introduction](xref:Uno.Documentation.Intro).

### Who makes Uno Platform?

Uno Platform is an [open-source project](https://github.com/unoplatform/Uno) with many contributors. It was developed internally by [nventive](https://nventive.com) from 2013-2018, and has been open source since 2018. It's maintained by [Uno Platform](https://platform.uno).

### What platforms can I target with Uno Platform?

Uno Platform applications run on the Web (via WebAssembly), Windows, Linux, macOS, iOS, and Android. [Check supported platform versions.](xref:Uno.GettingStarted.Requirements)

### Are Uno Platform applications native?

Yes - Uno Platform taps into the native UI frameworks on most supported platforms, so your final product is a native app. [Read more about how Uno Platform works.](xref:Uno.Documentation.Intro)

### Can applications look the same on all platforms?

Yes. Unless configured otherwise, your application's UI renders exactly the same on all targeted platforms, to the pixel. Uno Platform achieves this by either taking low-level control of the native visual primitives on the targeted platform or by using a Skia-based rendering approach. [Read more about how Uno works.](xref:Uno.Documentation.Intro)

### How is Uno Platform different from .NET MAUI?

First, Uno Platform is available in production today to build single-codebase, pixel-perfect applications for Web, Desktop, and Mobile. .NET MAUI is a successor to Xamarin.Forms.

Second, Uno Platform can target additional platforms like Linux and the Web.

Third, Uno Platform aligns with WinUI, which uses a flavor of XAML most Windows developers are familiar with. It also allows you to tap into WinUI's rich styling engine to create pixel-perfect applications.

Fourth, Uno Platform provides [Hot Design](https://platform.uno/hot-design/) for visually designing your Uno Platform apps.

Fifth, Uno Platform provides an optional [Figma plugin](https://platform.uno/unofigma/) for pixel-perfect XAML export for Uno Platform apps.

Finally, by extending the reach of WinUI across all supported platforms, it also allows you to leverage the rich 1st and 3rd party ecosystem and bring rich controls everywhere like `DataGrid`, `TreeView`, `TabView`, `NavigationView`, and many others.

At the practical level, we suggest you try both and see which works the best for your skill set and scenario.

### How is Uno Platform different from Blazor?

Uno Platform applications are cross-platform, running on the web as well as mobile and desktop, equally, from a single codebase. Blazor is a feature of ASP.NET for primarily building web applications.

Uno Platform applications are written in C# and XAML markup, whereas Blazor applications are written in 'Razor' syntax, a hybrid of HTML/CSS and C#.

Uno Platform and Blazor both make use of .NET's WebAssembly support to run natively in the browser.

### How is Uno Platform different from Flutter?

Uno Platform and Flutter solve a similar problem - pixel-perfect applications on all target platforms. However, Uno Platform leverages decades of Microsoft's investment made into developer tooling, .NET, and C# programming language for developing applications.

### Do I need to have an existing WinUI app or skills to use Uno Platform?

No, there's no need to have an existing WinUI application or have that specific skill set. The [Uno Platform templates](xref:Uno.GetStarted) make it easy to create a new project in Visual Studio or from the command line for anyone familiar with C# and XAML.

### What 3rd parties support Uno Platform?

Uno Platform is supported by several 3rd-party packages and libraries. This includes advanced controls from Microsoft Windows Community Toolkit, Syncfusion, and LightningChart; graphics processing with SkiaSharp; presentation and navigation with Prism, ReactiveUI, and MVVMCross; HTTP/API clients with Refit and Kiota; and local database management with SQLite. [See the full list of supported 3rd-party libraries.](xref:Uno.Development.SupportedLibraries)

### Where can I get support?

Support is available through [GitHub Discussions](https://github.com/unoplatform/uno/discussions) or [Discord Server](https://www.platform.uno/discord) - where our engineering team and community will be able to help you.  
Paid support is also available and allows you to collaborate with our engineering team to ensure the success of your projects and address your GitHub issues faster. [Contact us for more details.](https://platform.uno/contact/)

### How can I get involved?

There are lots of ways to contribute to the Uno Platform and we appreciate all the help we get from the community. You can provide feedback, report bugs, give suggestions, contribute code, and participate in the platform discussions. If you're interested, the [contributors' guide](uno-development/contributing-intro.md) is a great place to start.

### How can I report a bug?

If you think you've found a bug, please [log a new issue](https://github.com/unoplatform/Uno/issues) in the Uno Platform GitHub issue tracker. When filing issues, please use our bug filing template. The best way to get your bug fixed is to be as detailed as you can be about the problem. Providing a minimal project with steps to reproduce the problem is ideal. Here are questions you can answer before you file a bug to make sure you're not missing any important information.

## Features

### Is [Control X] supported by Uno Platform?

Consult [the list of supported WinUI controls](implemented-views.md).

### What do I need to develop Uno Platform applications?

You can develop Uno Platform applications on Windows, macOS, or Linux. Supported IDEs include Visual Studio, Visual Studio Code, and Rider. Consult the [setup guide](get-started.md) for more details. If you need help with issues specific to your developer environment or hardware, check out [Common Issues](xref:Uno.UI.CommonIssues).

### Can I use VB.NET for Uno Platform applications?

Much like the new UI technologies from Microsoft, Uno Platform doesn’t support creation of new applications using VB.NET.

If you have an existing VB.NET application that you would like to port/modernize for cross-platform scenarios with Uno Platform, you should be able to reuse all of your VB.NET business logic. It needs to be built as .NET standard libraries, then used in a new Uno Platform app where only the new UI code would be defined in XAML with some glue in C#.
To be exact, add "Class Library" VB project (not "Class Library (.Net Framework)", and not "Class Library (Universal Windows)"). Use ".NET Standard 2.0" as Target Framework.
To use this library in Uno heads for all platforms, add a reference to this library (the simplest way is to right-click on "References" nodes inside these heads).
You can also use the same Class Library in your original VB project. The same Class Library can also be used in any other .NET Standard compatible projects.
Additionally, if you’d like to move any of your VB.NET code to C#, you may be able to use automated tools such as https://converter.telerik.com

The best course of action is to do a POC and our team is happy to assist you in validating Uno Platform’s fit. Please [contact us](https://platform.uno/contact) with any queries.

## Technologies

### What is WinUI 3?

WinUI 3 is the [next generation of Microsoft's Windows UI library](https://learn.microsoft.com/windows/apps/winui/).

From [Microsoft](https://learn.microsoft.com/windows/apps/winui/):

> WinUI is the path forward for all Windows apps—you can use it as the UI layer on your native UWP or Win32 app, or you can gradually modernize your desktop app, piece by piece, with XAML Islands.
> All new XAML features will eventually ship as part of WinUI. The existing UWP XAML APIs that ship as part of the OS will no longer receive new feature updates. However, they will continue to receive security updates and critical fixes according to the Windows 10 support lifecycle.

Read more about [Uno Platform and WinUI 3](uwp-vs-winui3.md).

### How is Uno Platform different from Xamarin.Forms, MAUI or Avalonia?

Multiple techniques can be used to render UI, ranging from rendering pixels in a Frame Buffer (Avalonia) to rendering only using platform-provided controls (Xamarin.Forms, MAUI).

While the former provides high flexibility in terms of rendering fidelity and the ability to add new platforms, it has the drawback of not following the platform's native behaviors. For instance, interactions with text boxes have to be re-implemented completely to match the native behavior and have to be updated regularly to follow platform updates. This approach also makes it more difficult to integrate native UI components "in-canvas", such as Map or Browser controls.

The latter, however, provides full fidelity with the underlying platform, making it blend easily with native applications. While this can be interesting for some kinds of applications, designers usually want to have a branded pixel-perfect look and feel that stays consistent across platforms, where drawing primitives are not available.

The Uno Platform sits in the middle, using the power of XAML to provide the ability to custom draw and animate UI, while reusing key parts of the underlying UI Toolkit (such as chrome-less native text boxes) to provide native system interactions support and native accessibility features.

### What is XAML?

XAML stands for **eXtensible Application Markup Language**, and is used to provide a declarative way to define user interfaces. Its ability to provide a clear separation of concerns between the UI definition and application logic using data binding provides a good experience for small to very large applications where integrators can easily create UI without having to deal with C# code.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/feature-flags.md

---
uid: Uno.Development.FeatureFlags
---

# Configuring Uno's behavior globally

Uno provides a set of feature flags that can be set early in an app's startup to control its behavior. Some of these flags are for backward compatibility, some of them provide fine-grained customizability of a particular feature, and some of them allow to toggle between more 'WinUI-like' and more 'native-like' behavior in a particular context.

## Legacy clipping (Android)

Historically, Uno has been relying on the default platform's behavior for clipping, which is quite different from WinUI compositing behavior.

This behavior can be controlled by `Uno.UI.FeatureConfiguration.UIElement.UseLegacyClipping`, which now defaults to false.

If legacy clipping is enabled, clipping is applied on the assigned children bounds instead of the parent bounds.

## ListView scrolling (Android and iOS)

On iOS and Android platforms specifically, `ListView.ScrollIntoView` performs an animated scrolling instead of an instant scrolling than other platforms.

This feature can be toggled with `Uno.UI.FeatureConfiguration.ListViewBase.AnimateScrollIntoView`.
Alternatively, `Uno.UI.Helpers.ListViewHelper` offers two extension methods, `InstantScrollToIndex` and `SmoothScrollToIndex`, to perform a specific type of scrolling irrespective of the flag set.

## WinUI styles default

By default, Uno favors the default WinUI XAML styles over the native styles for Button, Slider, ComboBox, etc...

This can be changed using `Uno.UI.FeatureConfiguration.Style.UseUWPDefaultStyles`.

## Disabling accessibility text scaling (Android and iOS)

By default, Uno automatically enables accessibility text scaling on iOS and Android devices. However, to have more control, the feature flag `Uno.UI.FeatureConfiguration.Font.IgnoreTextScaleFactor` was added to control.

## Giving a maximum text scaling value (Android and iOS)

By default, Android has a limit of 200% for the text scaling which is not the case for iOS.

Use `Uno.UI.FeatureConfiguration.Font.MaximumTextScaleFactor` to control this.

## ComboBox

### Default preferred placement

By default, `ComboBox` popup is placed in such a way that the currently selected item is centered above the `ComboBox`. If you want to adjust this behavior on non-Windows targets, set the `Uno.UI.FeatureConfiguration.ComboBox.DefaultDropDownPreferredPlacement` property.

### Allow popup under translucent status bar

By default, the `ComboBox` popup will not extend under the status bar even if it is set as translucent. If you want to change this behavior, set the `Uno.UI.FeatureConfiguration.ComboBox.AllowPopupUnderTranslucentStatusBar` property to `true`. This property is Android-specific.

## Popups

### Constraining by visible bounds

By default we don't constrain popups by the visible bounds of the application view on Skia renderer targets. This is different from native renderer where popups are automatically padded by the visible bounds, which ensures the popup does not flow below the system UI (e.g. mobile device status bar or navigation bar). The `ConstrainByVisibleBounds` property allows you to control this behavior. Please note that in case the property is set to `false` (which is the default for Skia renderer), you are responsible for ensuring the content of your popups has appropriate padding around its content. This can be achieved using the [`SafeArea` control in Uno Toolkit](xref:Toolkit.Controls.SafeArea).

### Native popups (Android)

On Android, it is possible to use a native popup implementation, which is integrated into the system for `Popup`- and `Flyout`-derived UI. Prior to Uno Platform 3.5, native popups were used by default. On Uno Platform 3.5 or later, we made the managed implementation the default.

If you require native popups for your use case, set the `Uno.UI.FeatureConfiguration.Popup.UseNativePopup` to `true`.

### Light Dismiss Default

In older versions of Uno Platforms, the `Popup.IsLightDismissEnabled` dependency property defaulted to `true`. In WinUI and Uno 4.1 and newer, it correctly defaults to `false`. If your code depended on the old behavior, you can set the `Uno.UI.FeatureConfiguration.Popup.EnableLightDismissByDefault` property to `true` to override this.

### Prevent light dismiss on window deactivation

By default all light-dismissible elements are dismissed when window deactivates. This happens in various situations, including hitting a breakpoint while debugging. Setting the `Popup.PreventLightDismissOnWindowDeactivated` flag to `true` prevents this behavior. We strongly recommend setting this only when debugging.

## MessageDialog

By default, `MessageDialog` in Uno Platform targets displays using `ContentDialog` on WebAssembly and Skia, whereas it uses native dialog UI on Android, iOS, and macOS. The native dialogs are familiar to the users of the target platform, whereas the `ContentDialog` version offers the same UI on all targets. The `WinRTFeatureConfiguration.MessageDialog.UseNativeDialog` flag allows you to either disable or enable the use of native dialog UI. The default value of the flag depends on the target platform and changing the value of the flag on Skia has no effect (only `ContentDialog` version is available there):

| Feature        | Android | iOS | macOS | WASM | Skia |
|----------------|---------|-----|-------|------| --- |
| Default value of `UseNativeDialog`     | `true` | `true` |  `true`   | `false` | `false` |
| Native version available     | ✅ | ✅ |  ✅   | ✅(*) | ❌ |
| `ContentDialog` version available     | ✅ | ✅ |  ✅   | ✅ | ✅ |

(*) Native WebAssembly implementation uses `alert()` and is very limited.

When `ContentDialog` version is used, it uses the default `ContentDialog` style. If you want to customize the UI, you can declare your own `Style` on the application resource level and then set the `StyleOverride` flag to the resource key:

```xml
<Application.Resources>
    <Style x:Key="CustomMessageDialogStyle" TargetType="ContentDialog">
    ...
    </Style>
</Application.Resources>
```

```c#
WinRTFeatureConfiguration.MessageDialog.StyleOverride = "CustomMessageDialogStyle";
```

## ToolTips

By default, `ToolTips` are disabled on all platforms except for WebAssembly and Skia (see [#10791](https://github.com/unoplatform/uno/issues/10791)). To enable them on a specific platform, set the `UseToolTips` configuration flag to `true`. You can add the following in the end of the `App` constructor:

```csharp
Uno.UI.FeatureConfiguration.ToolTip.UseToolTips = true;
```

It is also possible to adjust the delay in milliseconds (`Uno.UI.FeatureConfiguration.ToolTip.ShowDelay` - defaults to `1000`) and show duration in milliseconds (`Uno.UI.FeatureConfiguration.ToolTip.ShowDuration` - defaults to `5000`). This configuration only applies to Uno Platform targets. Windows App SDK (WinUI) will not adhere to this configuration.

## WebView2

### Inspectable (iOS)

To enable inspecting applications using `WebView2` controls from macOS with the Safari Developer Tools, set the `IsInspectable` configuration flag to `true` in your `App.Xaml.cs`:

```csharp
public App()
{
    this.InitializeComponent();
#if __IOS__
    Uno.UI.FeatureConfiguration.WebView2.IsInspectable = true;
#endif
}
```

> [!IMPORTANT]
>
> This feature will only work for security reasons when the application runs in Debug mode.

## `ApplicationData`

On Skia Desktop targets, it is possible to override the default `ApplicationData` folder locations using `WinRTFeatureConfiguration.ApplicationData` properties. For more information, see [related docs here](/articles/features/applicationdata.md#data-location-on-skia-desktop)

## Deprecated NSObjectExtensions.ValidateDispose for iOS

The method `NSObjectExtensions.ValidateDispose` is deprecated in Uno 5.x and will be removed in the next major release.

In order for calls to fail on uses of this method, set the `Uno.UI.FeatureConfiguration.UIElement.FailOnNSObjectExtensionsValidateDispose` flag to `true`.

## Android Settings

### `IsEdgeToEdgeEnabled`

This flag controls the [edge-to-edge UI behavior](https://developer.android.com/develop/ui/views/layout/edge-to-edge) on Android. When set to `true` it makes the system UI (status bar and navigation bar) transparent, and lets the application expand below these overlays. To ensure all UI is still accessible for the user, proper safe area padding/margin needs to be applied. To achieve this, use the [`SafeArea` control in Uno Toolkit](xref:Toolkit.Controls.SafeArea). The default value is `true` for apps targeting .NET 9 or targeting Android SDK 35 and newer, defaults to `false` otherwise. For apps targeting SDK 35+ and running on Android 15 and newer, edge-to-edge is always enforced by the OS, so it cannot be disabled.

```csharp
#if __ANDROID__
var isEdgeToEdge = FeatureConfiguration.AndroidSettings.IsEdgeToEdgeEnabled;
#endif
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.wasm.bootstrap/refs/heads/main/doc/features-deep-linking.md

---
uid: UnoWasmBootstrap.Features.DeepLinking
---

# Support for deep-linking (routes)

Deep-linking enables the path part of the URI to indicate a location that should be navigated to.

> [!TIP]
> This feature is colloquially referred to as _routing_ in the web development world.

## Use in Uno Platform applications

Apps using deep-linking typically parse the URI as part of a robust navigation system. No longer is access to resources on discrete pages complicated by repetitive UI steps. Instead, these areas can be navigated directly from a link in an email, a bookmark, or another website. When planning the capabilities of your application, it is essential to decide whether common scenarios necessitate deep-linking.

If so, consider a navigation [system](xref:Overview.Navigation) that allows mapping route names to specific sectors of UI elements.

## Configure deep-linking

This feature is enabled by default in new projects generated from the `unoapp` template with version 4.9 or later.

Certain cases may require disabling this feature, such as when the application is hosted in a subdirectory of the host. This can be done by removing the `WasmShellWebAppBasePath` property from the `.csproj` file.

For project created from older template, add the following parameter to your project file to enable deep-linking:

```xml
<PropertyGroup>
  <WasmShellWebAppBasePath>/</WasmShellWebAppBasePath>
</PropertyGroup>
```

### Build-time configuration

This parameter can be configured on build by using a command-line parameter as follows:

```bash
dotnet build "-p:WasmShellWebAppBasePath=/"
```

## Behavior

All requests made to the bootstrapper's support files are read from the path specified by the `WasmShellWebAppBasePath` property. Restrictions are not placed on the depth of the path, so an address like `https://example.com/route1/item1` will be supported, assuming that the application is hosted at the root of the host.

One example of such support is done through the [Azure Static WebApps](https://platform.uno/docs/articles/guides/azure-static-webapps.html) support, using navigation fallback:

```json
{
  "navigationFallback": {
    "rewrite": "/index.html",
    "exclude": ["/package_*"]
  }
}
```

### Anchor based navigation

When deep-linking is disabled, [anchor-based navigation](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a#linking_to_an_element_on_the_same_page) remains supported, as it does not impact the path part of the URI.

## See also

- [Azure Static WebApps](xref:Uno.Tutorials.AzureStaticWepApps)
- [Navigation](xref:Overview.Navigation)
- [RouteMap](xref:Reference.Navigation.RouteMap)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.wasm.bootstrap/refs/heads/main/doc/features-idbfs.md

---
uid: UnoWasmBootstrap.Features.idbfs
---

# Support for IDBFS

In order to support emulated filesystem using [IDBFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#filesystem-api-idbfs), add the following to your `.csproj`:

```xml
<PropertyGroup>
  <WasmShellEnableIDBFS>true</WasmShellEnableIDBFS>
</PropertyGroup>
```

Note that this property is a shortcut to this equivalent configuration:

```xml
<ItemGroup>
    <WasmShellExtraEmccFlags Include="-lidbfs.js" />
    <WasmShellEmccExportedRuntimeMethod Include="IDBFS" />
</ItemGroup>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.wasm.bootstrap/refs/heads/main/doc/features-profiling.md

---
uid: Uno.Wasm.Bootstrap.Profiling.Memory
---
# Memory Profiling

Managed Memory profiling is available through the use of the [Xamarin Profiler](https://docs.microsoft.com/en-us/xamarin/tools/profiler) or [`mprof-report`](https://www.mono-project.com/docs/debug+profile/profile/profiler/#analyzing-the-profile-data).

Memory snapshots are supported to enable memory difference analysis and find memory leaks.

## Using the memory profiler

- Add the following to your csproj:

  ```xml
  <PropertyGroup>
    <WasmShellEnableLogProfiler>true</WasmShellEnableLogProfiler>
  </PropertyGroup>
  ```

Once the application is running:

- Use the `Shift+Alt+H` (`Shift+Cmd+H` on macOS) hotkey to create memory snapshots
- Use the `Shift+Alt+P` (`Shift+Cmd+P` on macOS) hotkey to save the profile to a file

With the saved `mlpd` file, you can either:

- Open it with the Xamarin Profiler (which needs to be explicitly installed in the VS 2022 installer)
- Show a memory report using `mprof-report`. The tool can be installed under Ubuntu WSL using `sudo apt install mono-utils`

### Additional profiler configuration

The profiler uses the [official configuration string](https://www.mono-project.com/docs/debug+profile/profile/profiler/#profiler-option-documentation), which can be adjusted using the following options:

```xml
<PropertyGroup>
  <WasmShellEnableLogProfiler>true</WasmShellEnableLogProfiler>
  <WasmShellLogProfilerOptions>log:alloc,output=output.mlpd</WasmShellLogProfilerOptions>
</PropertyGroup>
```

Note that as of .NET 6:

- The support for any timer based profiling is not supported, because of the lack of threading support in .NET
- The support for remote control of the profiler is not supported

## Memory Layout of a WebAssembly app

A WebAssembly app has multiple categories of allocated memory:

- The managed memory usage, which is the smallest portion of the overall used memory. This is the memory directly done by object allocations from managed code. It is the memory reported by `mprof-report` or the Xamarin Profiler. This memory can be queried by using the [`GC.GetTotalMemory`](https://learn.microsoft.com/en-us/dotnet/api/system.gc.gettotalmemory).
- The WebAssembly module memory usage, which is the overall app memory usage as far as WebAssembly is concerned. This is similar to the committed memory in a Windows app. This contains:
  - The runtime's own native memory allocations
  - The Garbage Collector memory, which is [directly impacted](xref:Uno.Development.Performance#webassembly-specifics) by the [MONO_GC_PARAMS parameters](https://github.com/dotnet/runtime/blob/0bfb733c6419e78e55286e0d01c5994a337c486a/docs/design/mono/mono-manpage-1.md#environment-variables). Note that the garbage collector over-allocates WebAssembly memory for performance reasons.
  - All the files located in the `Package_xxxx/managed` folder. Each assembly file is directly loaded in memory by the .NET runtime, regardless of it being used at the app's startup or not. Reducing the assemblies file sizes can be acheived by configuring the [IL Linker](xref:uno.articles.features.illinker).
  
  The WebAssembly memory can be queried using the following JavaScript expression: `globalThis.Module.HEAPU8.length`, which gives the allocated memory in bytes. You can use [`JSImport`](xref:Uno.Wasm.Bootstrap.JSInterop#invoking-javascript-code-from-c) to read it from managed code.
- The javascript memory, which is mostly about the HTML DOM rendering and the browser's own runtime memory. Those two categories can be analyzed using the [browser's own debugging tooling](https://developer.chrome.com/docs/devtools/memory-problems).

## CPU Profiling

To enable the profiling of the WebAssembly code, set te following parameter:

```xml
<WasmShellEnableEmccProfiling>true</WasmShellEnableEmccProfiling>
```

This will ensure that the toolchain keeps the function names so that the browser shows meaningful information in the **Performance** tab.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.wasm.bootstrap/refs/heads/main/doc/features-security.md

---
uid: Uno.Wasm.Bootstrap.Features.Security
---

# Security

## CSP Support

Starting from the bootstrapper 7.0.20, the bootstrapper supports [Content Security Policy (CSP)](https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP) for the web application. Specifically, the bootstrapper is compliant with the `unsafe-eval` CSP feature.

Enabling CSP support can be done in three ways:

- Adding the following block in the `.csproj`:

  ```xml
  <PropertyGroup>
      <WasmShellCSPConfiguration>default-src 'self'; script-src 'self' 'wasm-unsafe-eval'</WasmShellCSPConfiguration>
  </PropertyGroup>
  ```

- Adding the following meta block in the index.html, you have a custom one:

  ```html
  <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self' 'wasm-unsafe-eval'">
  ```

- Providing the following header from the server:

  ```http
  Content-Security-Policy: default-src 'self'; script-src 'self' 'wasm-unsafe-eval'
  ```

> [!IMPORTANT]
> The Uno.Wasm.Bootstrap package uses WebAssembly, it is required to provide the [`wasm-unsafe-eval`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy/script-src#unsafe_webassembly_execution) directive in the CSP configuration.

Enabling CSP without `unsafe-eval` implies that the application will not be able to use JavaScript's `eval()`, and [JSImport/JSExport](xref:Uno.Wasm.Bootstrap.JSInterop) must be used instead.

### Validation

In order to test, browsers support a _report-only_ mode which logs violations and continues.

To enable this mode, use the `Content-Security-Policy-Report-Only` header instead of `Content-Security-Policy`.

### Limitations

Enabling CSP is not compatible with [memory profiling](xref:Uno.Wasm.Bootstrap.Profiling.Memory) and [AOT profile generation](xref:Uno.Wasm.Bootstrap.Runtime.Execution).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.wasm.bootstrap/refs/heads/main/doc/features-simd.md

---
uid: UnoWasmBootstrap.Features.Overview
---

# Support for SIMD

Starting from .NET 7, support for SIMD is available through the following property:

```xml
<PropertyGroup>
    <WasmShellEnableSimd>true</WasmShellEnableSimd>
</PropertyGroup>
```

With .NET 8, SIMD support is enabled by default and can be disabled using:

```xml
<PropertyGroup>
    <WasmShellEnableSimd>false</WasmShellEnableSimd>
</PropertyGroup>
```

The .NET SDK [`WasmEnableSIMD`](https://learn.microsoft.com/en-us/aspnet/core/blazor/webassembly-build-tools-and-aot?view=aspnetcore-8.0#single-instruction-multiple-data-simd) property is also supported.

[WebAssembly Support for SIMD](https://github.com/webassembly/simd) enables faster execution for specialized pieces of code, and .NET increasingly uses those instructions to make applications run faster.

You can take a look at [this article](https://platform.uno/blog/safari-16-4-support-for-webassembly-fixed-width-simd-how-to-use-it-with-c/) for more information.

## Restriction for the use of SIMD

While SIMD is supported by all major browsers by default, some security modes can require disabling it.

For instance, Microsoft Edge's [Enhanced Security mode](https://learn.microsoft.com/en-us/deployedge/microsoft-edge-security-browse-safer) disables the use of SIMD, as well as iOS's [Lockdown mode](https://support.apple.com/en-us/HT212650).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.wasm.bootstrap/refs/heads/main/doc/features-threading.md

---
uid: UnoWasmBootstrap.Features.Threading
---

# Support for WebAssembly Threads

> [!CAUTION]
> Threading support is experimental, and .NET 9 support [has changed the main thread's ability to execute managed code](https://github.com/dotnet/runtime/issues/85592#issuecomment-2031876112). As a result, the support in the Uno Bootstrapper is limited to simple DOM interactions, and is not supported on Uno Platform UI apps.

Starting from .NET 7, experimental support for [WebAssembly threads](https://github.com/WebAssembly/threads/blob/master/proposals/threads/Overview.md) has been included. This support is provided by the bootstrapper 7.0 and later, for interpreter and AOT modes. The following documentation explains how to enable threading.

> [!IMPORTANT]
> Threading support is now supported in most major browsers. You can find out if your target browser supports it on the [WebAssembly roadmap](https://webassembly.org/roadmap).

## Enabling threads

Add the following to your WebAssembly project:

```xml
<PropertyGroup>
    <WasmShellEnableThreads>true</WasmShellEnableThreads>
</PropertyGroup>
```

Threading support can be detected at runtime by using the [`UNO_BOOTSTRAP_MONO_RUNTIME_FEATURES`](features-environment-variables.md) environment variable.

## Controlling the browser thread pool size

By default, the runtime pre-creates a set of 4 WebWorkers available to WebAssembly threads, and the .NET Runtime will reuse the workers as threads stop. This value is used by the `ThreadPool` and `Tasks` subsystems.

To change the number of threads available to the app, use the following:

```xml
<PropertyGroup>
    <WasmShellPThreadsPoolSize>8</WasmShellPThreadsPoolSize>
</PropertyGroup>
```

The maximum number of threads can be determined by the `UNO_BOOTSTRAP_MAX_THREADS` environment variable.

## Restrictions

WebAssembly Threads are using the `SharedArrayBuffer` browser feature, which is disabled in most cases for security reasons.

To enable `SharedArrayBuffer`, your website will need to provide the following headers:

```http
Cross-Origin-Embedder-Policy: require-corp
Cross-Origin-Opener-Policy: same-origin
```

If you're using resources from another origin, that origin should also be serving the following header to accept being loaded by the app:

```http
Cross-Origin-Resource-Policy: cross-origin
```

See [here additional information](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cross-Origin-Resource-Policy) about this header.

You can find [more information about threading on the Chrome Developer blog](https://developer.chrome.com/blog/enabling-shared-array-buffer/).

If you're using [`dotnet serve`](https://github.com/natemcmaster/dotnet-serve) or any other similar server package to serve your application, you can use the following:

```sh
dotnet serve -p 8000 -h "Cross-Origin-Embedder-Policy: require-corp" -h "Cross-Origin-Opener-Policy: same-origin"
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/file-management.md

---
uid: Uno.Features.FileManagement
---

# File Management

File management allows shared reading and writing of files across all Uno Platform targets. This includes the ability to read files from the application package, as well as the ability to read and write files from the file system.

> [!TIP]
> This article covers Uno-specific information for file management. For a full description of the feature and instructions on using it, see [Files, folders, and libraries](https://learn.microsoft.com/windows/uwp/files/).

## Supported features

| Feature             | WinUI     | Android | iOS     | Web (WASM) | macOS   | Linux (Skia) | WPF (Skia) |
|---------------------|-----------|---------|---------|------------|---------|--------------|------------|
| `StorageFile`       | ✔         | ✔       | ✔       | ✔          | ✔       | ✔            | ✔          |
| `StorageFolder`     | ✔         | ✔       | ✔       | ✔          | ✔       | ✔            | ✔          |
| `CachedFileManager` | ✔         | partial | partial | partial    | partial | partial      | partial    |
| `StorageFileHelper` | ✔         | ✔       | ✔       | ✔          | ✔       | ✔            | ✔          |

## Overview

Uno supports some of the APIs from the `Windows.Storage` namespace, such as `Windows.Storage.StorageFile` and `Windows.Storage.StorageFolder` for all platforms.

Both `Windows.Storage` and `System.IO` APIs are available, with some platform specifics defined below. In general, it is best to use `Windows.Storage` APIs when available, as their asynchronous nature allows for transparent interactions with the underlying file system implementations. In addition, `System.IO` cannot work with files that are not owned by the application directly (e.g. files picked by a dialog).

Note that for file and folder metadata only `BasicProperties` are partially supported for now.
`FileAttributes` and all "advanced properties" (`StorageItemContentProperties`) related to the content of the file, including the thumbnail, are not yet supported.

## WebAssembly File System

WebAssembly file system APIs are built using [emscripten's POSIX file system APIs](https://emscripten.org/docs/api_reference/Filesystem-API.html). The persistence is done through the use of browser APIs, such as IndexedDB through [emscripten's IDBFS](https://emscripten.org/docs/api_reference/Filesystem-API.html#filesystem-api-idbfs).

While it is possible to write files in any paths, only some folders are persisted across browser refreshes:

- `ApplicationData.Current.LocalFolder`
- `ApplicationData.Current.RoamingFolder`
- `ApplicationData.Current.SharedLocalFolder`

Note that the initialization of the filesystem is asynchronous. This means that reading a file during `Application.OnLaunched` using `System.IO.File.OpenRead` may fail to find a file that was previously written, because the filesystem is not available yet.

The optimal way to open a file is to use the following:

```csharp
var localFolder = Windows.Storage.ApplicationData.Current.LocalFolder;
var folder = await localFolder.CreateFolderAsync("myFolder", CreationCollisionOption.OpenIfExists);
File.WriteAllText(Path.Combine(folder.Path, "MyFile.txt"), DateTime.Now.ToLongDateString());
```

Note that for WebAssembly in particular, the `await localFolder.CreateFolderAsync` is important to ensure that the file system has properly been initialized from the IDBFS persistence. Any asynchronous operation from StorageFolder awaits for the filesystem's initialization before continuing.

Note that you can view the content of the **IndexedDB** in the Application tab of your browser, in the **Storage / IndexedDB** section.

## Support for `StorageFile.GetFileFromApplicationUriAsync`

Uno Platform supports the ability to get package files using the [`StorageFile.GetFileFromApplicationUriAsync(Uri)`](https://learn.microsoft.com/uwp/api/windows.storage.storagefile.getfilefromapplicationuriasync) method.

Support per platform may vary:

- On WebAssembly targets, the requested file is part of the application package on the remote server and is downloaded on demand to avoid increasing the initial application payload size. After it is requested for the first time, the file is then stored in the browser IndexedDB.
- Otherwise, the file is available directly as it is a part of the installed package.

### General usage instructions

Ensure that a declaration exists in your project file like the following:

```xml
<ItemGroup>
    <Content Include="MyPackageFile.xml" />
</ItemGroup>
```

A URI with the `ms-appx:///` scheme can then be used to read a file's content:

```csharp
var file = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///MyPackageFile.xml"));
var content = await FileIO.ReadTextAsync(file);
```

### Support for Library provided assets

Since Uno Platform 4.6, the `GetFileFromApplicationUriAsync` method supports reading assets provided by `ProjectReference` or `PackageReference` libraries, using the following syntax:

Given a library or package named `MyLibrary01`, the following format can be used to read assets:

```csharp
var file = await Windows.Storage.StorageFile.GetFileFromApplicationUriAsync(new Uri("ms-appx:///MyLibrary01/MyPackageFile.xml"));
var content = await FileIO.ReadTextAsync(file);
```

Uno Platform also provides the ability to determine if an asset or resource exists in the application package by using `StorageFileHelper.ExistsInPackage`:

```csharp
var fileExists = await StorageFileHelper.ExistsInPackage("Assets/Fonts/uno-fluentui-assets.ttf");
```

## Support for `RandomAccessStreamReference.CreateFromUri`

Uno Platform supports the creation of a `RandomAccessStreamReference` from an `Uri` (`RandomAccessStreamReference.CreateFromUri`), but note that on WASM downloading a file from a server often causes issues with [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS).
Make sure the server that hosts the file is configured accordingly.

## Support for `CachedFileManager`

For all targets except WinUI and WebAssembly, the `CachedFileManager` does not provide any functionality, and its methods immediately return. This allows us to easily write code that requires deferring updates on Windows but is shared across all targets.

In the case of WebAssembly, the behavior of `CachedFileManager` depends on whether the app uses the **File System Access API** or **Download picker**. This is described extensively within the [documentation](xref:Uno.Features.WSPickers#webassembly) for storage pickers.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/flashlight.md

---
uid: Uno.Features.Flashlight
---

# Flashlight

> [!TIP]
> This article covers Uno-specific information for Flashlight. For a full description of the feature and instructions on using it, see [Lamp Class](https://learn.microsoft.com/uwp/api/windows.devices.lights.lamp).

* `Lamp` API allows you to turn the phone's camera flashlight on and off

## Supported features

| Feature        |  Windows  | Android |  iOS  |  Web (WASM)  | macOS | Linux (Skia)  | Win 7 (Skia) |
|---------------|-------|-------|-------|-------|-------|-------|-|
| `GetDefaultAsync` | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `IsEnabled`     | ✔ | ✔ | ✔ | ✖ | ✖ | ✖ | ✖ |
| `BrightnessLevel`     | ✔ | ✔ | ✔ | ✖ | ✖ | ✖ | ✖ |

<!-- Add any additional information on platform-specific limitations and constraints -->

## Using `Lamp` with Uno

* The `GetDefaultAsync` method is implemented on all targets and will return `null` where `Lamp` is not supported.
* Make sure to call `Lamp.Dispose()` after use, as implementation on both iOS and Android uses unmanaged resources, and not disposing of them could cause a memory leak. This is in line with WinUI, where the `Lamp` needs to be disposed of as well.
* On **iOS**, in case the device supports the torch, `BrightnessLevel` is fully supported. In case the device has only flash, any non-zero `BrightnessLevel` will result in the full brightness of the flashlight.
* On **Android**, flashlight brightness cannot be controlled, hence any non-zero `BrightnessLevel` results in the full brightness of the flashlight.

## Platform-specific requirements

### Android

For Android, there are two permissions you must configure before using this API in your project. To do that, add the following to `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.FLASHLIGHT" />
<uses-permission android:name="android.permission.CAMERA" />
```

## Example

```csharp
if (await Lamp.GetDefaultAsync() is Lamp lamp)
{
    lamp.IsEnabled = true; // Turn on the flashlight.

    lamp.BrightnessLevel = 0.5; // Set brightness of 50 %.

    lamp.IsEnabled = false; // Turn off the flashlight.

    lamp.Dispose(); // Stop using flashlight and clean up resources.
}
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/fluent-styles.md

---
uid: Uno.Features.FluentStyles
---

# Fluent-styled controls

Uno Platform 3.0 and above supports control styles conforming to the [Fluent design system](https://www.microsoft.com/design/fluent). This article explains how to use them in your app.

## Upgrading existing Uno apps to use Fluent styles

Overall, the Uno Platform uses the same mechanism as WinUI to enable Fluent styles. After installing the `Uno.UI` Nuget version 3.0 or above, Fluent styles are enabled by specifying the `XamlControlsResources` within the application's resources (inside `App.xaml`).

For the UWP head, an additional WinUI 2 Nuget package reference must be added. This follows the same process as UWP because, for the UWP head, the Uno Platform is not used.

The step-by-step process to enable Fluent design styles within an existing Uno Platform solution is as follows:

1. In all platform head projects except UWP update the `Uno.UI` NuGet packages to 3.0 or above.
1. In only the `UWP` head project of your solution, if you have one, install the [WinUI 2 NuGet package](https://www.nuget.org/packages/Microsoft.UI.Xaml). This step is the same as required for WinUI 2 UWP apps.
1. Within the app project, add the `XamlControlsResources` resource dictionary to your application resources inside `App.xaml`. This step is the same as required for WinUI 2 UWP apps.

    ```xml
    <Application>
        <Application.Resources>
            <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
        </Application.Resources>
    </Application>
    ```

    Or, if you have other existing application-scope resources, add `XamlControlsResources` at the top (before other resources) as a merged dictionary:

    ```xml
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                <!-- Other merged dictionaries here -->
            </ResourceDictionary.MergedDictionaries>
            <!-- Other app resources here -->
        </ResourceDictionary>
    </Application.Resources>
    ```

1. In all platform head projects except UWP the Fluent control styles require the Uno Fluent Assets icon font to display correctly. [Follow the instructions here](../uno-fluent-assets.md) to upgrade your app to use this font. This step is required because the Uno Platform uses a cross-platform ready default font within its styles different from UWP's *Segoe MDL2 Assets*.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/focus-management.md

---
uid: Uno.Features.FocusManagement
---

# Focus Management

## Programmatic focus

Support for programmatic focus is fully implemented on all Uno Platform targets and matches the logic provided by WinUI. To use programmatic focus, utilize the `Microsoft.UI.Xaml.Input.FocusManager` class and its static methods. For detailed documentation on its methods check the comments provided by IntelliSense in Visual Studio, see [FocusManager source code](https://github.com/unoplatform/uno/blob/master/src/Uno.UI/UI/Xaml/Input/FocusManager.cs), or the official [WinUI documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.input.focusmanager).

## Specifying visual tree for focus operations

`FocusManager` class is `static`, but can operate in multi-window environment. To handle this correctly, some methods provide overloads allowing the user to specify a `XamlRoot` or `UIElement` the operation should be executed against. The overloads that do not have this capability will throw an exception.

- Use `GetFocusedElement(XamlRoot)` instead of `GetFocusedElement()`.
- Use `TryMoveFocus` overload with `FindNextElementOptions` instance which has `SearchRoot` set to an `UIElement` in the visual tree or `XamlRoot.Content`.
- Use `TryMoveFocusAsync` overload with `FindNextElementOptions` instance which has `SearchRoot` set to an `UIElement` in the visual tree or `XamlRoot.Content`.
- Use `FindNextElement` overload with `FindNextElementOptions` instance which has `SearchRoot` set to an `UIElement` in the visual tree or `XamlRoot.Content`.
- Use the aforementioned `FindNextElement` overload instead of `FindNextFocusableElement`.
- Always provide an element in the visual tree to `FindFirstFocusableElement` and `FindLastFocusableElement`.

> [!NOTE]
> `SearchRoot` in `FindNextElementOptions` is the root from which the next focus candidate to receive navigation focus is identified. Therefore, the methods will behave differently based on which element is used.

## Keyboard focus

Keyboard focus handling support is generally available on all targets except iOS. On iOS you can opt-in to enable experimental support by setting the related flag:

```csharp
#if __IOS__
WinRTFeatureConfiguration.Focus.EnableExperimentalKeyboardFocus = true;
#endif
```

The feature requires additional testing to verify all edge cases on Android and iOS. In a future release, we will switch the experimental support to be enabled by default.

## Disabling initial focus on Page

The focus management logic in WinUI sets initial focus on `Page` that is being loaded (for example, during navigation) if no element in the app is currently focused. This may cause an input element like `TextBox` to get focused automatically. This may not be a desirable behavior, though, as it will cause the virtual keyboard on mobile platforms to open up. To avoid this initial focus, please set `IsTabStop` of the `Page` to `false`:

```xaml
<Page
   ...
   IsTabStop="False">
   ...
</Page>
```

Alternatively, you can set focus explicitly to some other UI element by calling `element.Focus(FocusState.Programmatic)` in the code-behind - ideally in the `Loaded` event handler or in `OnNavigatedTo` override.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/gamepad.md

---
uid: Uno.Features.Gamepad
---

# Gamepad

> [!TIP]
> This article covers Uno-specific information for `Gamepad`. For a full description of the feature and instructions on using it, see [Gamepad Class](https://learn.microsoft.com/uwp/api/windows.gaming.input.gamepad).

* The `Windows.Gaming.Input.Gamepad` class allows working with the connected gamepads.

## Supported features

| Feature             | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
| ------------------- | ------- | ------- | --- | ---------- | ----- | ------------ | ------------ |
| `GetCurrentReading` | ✔       | ✔       | ✔   | ✔          | ✔     | ✖            | ✖            |
| `GamepadAdded`      | ✔       | ✔       | ✔   | ✔          | ✔     | ✖            | ✖            |
| `GamepadRemoved`    | ✔       | ✔       | ✔   | ✔          | ✔     | ✖            | ✖            |
| `Gamepads`          | ✔       | ✔       | ✔   | ✔          | ✔     | ✖            | ✖            |

## Example

### Getting the gamepads list

```csharp
private readonly object myLock = new object();
private HashSet<Gamepad> myGamepads = new HashSet<Gamepad>();

private void GetGamepads()
{
    lock (myLock)
    {
        foreach (var gamepad in Gamepad.Gamepads)
        {
            // Check if the gamepad is already in myGamepads; if it isn't, add it.
            if (!myGamepads.Contains(gamepad))
            {
                myGamepads.Add(gamepad);
            }
        }
    }   
}
```

### Reading current values

```csharp
Gamepad gamepad = myGamepads[0];

GamepadReading reading = gamepad.GetCurrentReading();

// returns a value between 0.0 and 1.0
double leftTrigger = reading.LeftTrigger;  
double rightTrigger = reading.RightTrigger;

// returns a value between -1.0 and +1.0
double leftStickX = reading.LeftThumbstickX;
double leftStickY = reading.LeftThumbstickY;   
double rightStickX = reading.RightThumbstickX; 
double rightStickY = reading.RightThumbstickY;

if (GamepadButtons.A == (reading.Buttons & GamepadButtons.A))
{
    // button A is pressed
}
```

## See Gamepad in action

* To see this API in action, visit the [Uno Gallery](https://gallery.platform.uno/) and look for Gamepad.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-ai-claude.md

---
uid: Uno.GetStarted.AI.Claude
---

# Get Started with Claude Code

This guide will walk you through the setup process for getting started with Claude Code.

## Check your environment

[!include[getting-help](includes/use-uno-check-inline-noheader.md)]

## Setting up Uno Platform MCPs

1. Install [Claude Code](https://code.claude.com/docs/en/overview) from the CLI
1. Register the Uno Platform MCPs:

    ```bash
    claude mcp add --scope user --transport http uno https://mcp.platform.uno/v1
    claude mcp add --scope user --transport stdio "uno-app" -- dotnet dnx -y uno.devserver --mcp-app
    ```

1. Open Claude and run:

    ```bash
    /mcp
    ```

    This will show the Uno Platform MCPs available to the agent.

    > [!IMPORTANT]
    > The `uno-app` MCP [may fail to load](https://github.com/anthropics/claude-code/issues/4384) unless Claude is opened in a folder containing an Uno Platform app.

## Next Steps

Now that you are set up, let's [create your first app](xref:Uno.GettingStarted.CreateAnApp.AI.Claude).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-ai-codex.md

---
uid: Uno.GetStarted.AI.Codex
---

# Get Started with Codex CLI

This guide will walk you through the setup process for getting started with Codex.

## Check your environment

[!include[getting-help](includes/use-uno-check-inline-noheader.md)]

## Setting up Uno Platform MCPs

1. Install [Codex CLI](https://developers.openai.com/codex/cli) using the official commands, for example:

    ```bash
    npm i -g @openai/codex
    # or on macOS
    brew install --cask codex
    ```

1. Register the Uno Platform MCPs:

    ```bash
    codex mcp add "uno" --url "https://mcp.platform.uno/v1"
    codex mcp add "uno-app" -- dotnet dnx -y uno.devserver --mcp-app
    ```

1. Start Codex CLI and type the following:

    ```text
    /mcp
    ```

    This will show the Uno Platform tools available to the agent.

    > [!IMPORTANT]
    > The uno-app MCP may fail to load unless Codex is opened in a folder containing an Uno Platform app.

## Next Steps

Now that you are set up, let's [create your first app](xref:Uno.GettingStarted.CreateAnApp.AI.Codex).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-ai-cursor.md

---
uid: Uno.GetStarted.AI.Cursor
---

# Get Started with Cursor

This guide will walk you through the setup process for getting started with Cursor.

## Check your environment

[!include[getting-help](includes/use-uno-check-inline-noheader.md)]

## Setting up Cursor

Install [Cursor](https://cursor.com/docs).

> [!NOTE]
> The Uno Platform extension is not functional in Cursor at this time.

There is nothing specific to set up for Cursor. You can proceed to the next section to create your first app and use the Uno MCPs.

## Next Steps

Now that you are set up, let's [create your first app](xref:Uno.GettingStarted.CreateAnApp.AI.Cursor).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-ai-gh-copilot-cli.md

---
uid: Uno.GetStarted.AI.CopilotCLI
---

# Get Started with GitHub Copilot CLI

This guide will walk you through the setup process for getting started with GitHub Copilot CLI.

## Check your environment

[!include[getting-help](includes/use-uno-check-inline-noheader.md)]

## Setting up Uno Platform MCPs

To get started with GitHub Copilot CLI:

1. Install [Copilot CLI](https://github.com/features/copilot/cli)
1. Start Copilot CLI
1. Type `/mcp` and register the following:
    1. Unique Name: `uno`
    1. Server Type: HTTP
    1. URL: `https://mcp.platform.uno/v1`
    1. Skip HTTP Headers and leave tools to `*`
1. Type `/mcp` again and register the following (app-specific MCP):
    1. Unique Name: `uno-app`
    1. Server Type: Local
    1. Command: `dotnet dnx -y uno.devserver --mcp-app`
    1. Skip Environment Variables and leave tools with `*`

> [!IMPORTANT]
> The uno-app MCP may fail to load unless Copilot is opened in a folder containing an Uno Platform app.

## Next Steps

Now that you are set up, let's [create your first app](xref:Uno.GettingStarted.CreateAnApp.AI.CopilotCli).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/getting-started/counterapp/get-started-counter-csharp-mvux.md

---
uid: Uno.Workshop.Counter.CSharp.MVUX
---

# Counter App using C# Markup and MVUX

[Download the complete C# Markup + MVUX sample](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Counter/CSharp-MVUX)

[!INCLUDE [Intro](includes/include-intro.md)]

In this tutorial, you will learn how to:

- Create a new Project with Uno Platform using Visual Studio Template Wizard or the **dotnet new** command
- Add elements to the C# file, using [C# Markup](xref:Uno.Extensions.Markup.Overview), to define the layout of the application
- Add code to the C# file to implement the application logic using the [Model-View-Update-eXtended (MVUX)](xref:Uno.Extensions.Mvux.Overview) pattern
- Use data binding to connect the UI to the application logic

To complete this tutorial, you don't need any prior knowledge of the Uno Platform or C#.

[!INCLUDE [VS](includes/include-create.md)]

## [Visual Studio](#tab/vs)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Visual Studio** installed, follow [these instructions](xref:Uno.GetStarted.vs2022).

- Launch **Visual Studio** and click on **Create new project** on the Start Window. Alternatively, if you're already in Visual Studio, click **New, Project** from the **File** menu.

- Type `Uno Platform` in the search box

- Click **Uno Platform App**, then **Next**

- Name the project `Counter` and click **Create**

At this point you'll enter the **Uno Platform Template Wizard**, giving you options to customize the generated application. For this tutorial, we're only going to configure the markup language and the presentation framework.

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVUX**

- Select the **Markup** tab and choose **C# Markup**

Before completing the wizard, take a look through each of the sections and see what other options are available. You can always come back and create a new project with different options later. For more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

- Click **Create** to complete the wizard

The template will create a solution with a single cross-platform project, named `Counter`, ready to run.

### [Rider](#tab/rider)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Visual Studio** installed, follow [these instructions](xref:Uno.GetStarted.Rider).

- Launch **Rider** and click on **New Solution** on the Start Window

- From the left menu, under the **Uno Platform** section, select **Uno Platform App**
  At this point, you'll see options for creating a new Uno app, allowing you to customize the generated application. For this tutorial, we will only configure the presentation framework.

- Name the project `Counter`

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVUX**

- Select the Markup tab and choose **C# Markup**

- Click **Create** to complete the creation
  The template will create a solution with a single cross-platform project, named `Counter`, ready to run.

### [VS Code](#tab/vscode)

> [!NOTE]
> If you don't have the **Uno Platform Extension for VS Code** installed, follow [these instructions](xref:Uno.GetStarted.vscode).

- Launch The Live Wizard by visiting the [Uno Platform Live Wizard](https://new.platform.uno/)

- Name the project `Counter` and click **Start**

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVUX**

- Select the Markup tab and choose **C# Markup**

- Click **Create** to complete the wizard

- Copy the `dotnet new` command and run it from a terminal where you want your solution to be located.

- This will create a new folder called **Counter** containing the new application.

- Next, open the project using Visual Studio Code. In the terminal type the following:

  ```bash
  code ./Counter
  ```

- Visual Studio Code might ask to restore the NuGet packages. Allow it to restore them if asked.

- Once the solution has been loaded, in the status bar at the bottom left of VS Code, `Counter.sln` is selected by default. Select `Counter.csproj` to load the project instead.
  ![Counter.csproj selection in Visual Studio Code](Assets/vscode-csproj-dotnet9.0.png)

## [Command Line](#tab/cli)

> [!NOTE]
> If you don't have the Uno Platform dotnet new templates installed, follow [dotnet new templates for Uno Platform](xref:Uno.GetStarted.dotnet-new).

From the command line, run the following command:

```dotnetcli
dotnet new unoapp -preset blank -presentation mvux -markup csharp -o Counter
```

This will create a new folder called **Counter** containing the new application.

If you want to discover all the options available in the **unoapp** template, run the following command:

```dotnetcli
dotnet new unoapp -h
```

Also, for more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

---

[!INCLUDE [Counter Solution](includes/include-solution.md)]

![Counter Solution](Assets/counter-solution-csharp.png)

[!INCLUDE [Main Window](includes/include-mainwindow.md)]

[!INCLUDE [Main Page - C# Markup](includes/include-mainpage-csharp.md)]

[!INCLUDE [Main Page - Layout](includes/include-mainpage-layout.md)]

[!INCLUDE [Main Page - Image](includes/include-image-csharp.md)]

[!INCLUDE [Main Page - Change Layout](includes/include-mainpage-change-layout.md)]

[!INCLUDE [Main Page - Other Elements](includes/include-elements-csharp.md)]

[!INCLUDE [Main Model](includes/include-mvux.md)]

## Data Binding

As the application uses MVUX, the `MainModel` class is used to generate a bindable ViewModel, `MainViewModel`. We can update the **`MainPage`** to use data binding to connect the UI to the application logic.

- Let's add the **`DataContext`** to our page. To do so, add `.DataContext(new MainViewModel(), (page, vm) => page` before `.Background(...)`. Remember to close the **`DataContext`** expression with a `)` at the end of the code. It should look similar to the code below:

    ```csharp
    this.DataContext(new MainViewModel(), (page, vm) => page
        .Background(ThemeResource.Get<Brush>("ApplicationPageBackgroundThemeBrush"))
        .Content(
            ...
        )
    );
    ```

- Update the **`TextBlock`** by removing its current text content and replacing it with a binding expression for the **`Countable.Count`** property of the **`MainViewModel`**. Modify the existing **`Text`** property with `() => vm.Countable.Count, txt => $"Counter: {txt}"`. The adjusted code is as follows:

    ```csharp
    new TextBlock()
        .Margin(12)
        .HorizontalAlignment(HorizontalAlignment.Center)
        .TextAlignment(Microsoft.UI.Xaml.TextAlignment.Center)
        .Text(() => vm.Countable.Count, txt => $"Counter: {txt}")
    ```

- Update the **`TextBox`** by binding the **`Text`** property to the **`Countable.Step`** property of the **MainViewModel**. The **`Mode`** of the binding is set to **`TwoWay`** so that the **`Countable.Step`** property is updated when the user changes the value in the **`TextBox`**.

    ```csharp
    new TextBox()
        .Margin(12)
        .HorizontalAlignment(HorizontalAlignment.Center)
        .TextAlignment(Microsoft.UI.Xaml.TextAlignment.Center)
        .PlaceholderText("Step Size")
        .Text(x => x.Binding(() => vm.Countable.Step).TwoWay())
    ```

- Update the **`Button`** to add a **`Command`** property that is bound to the **`IncrementCounter`** task of the **`MainViewModel`**.

    ```csharp
    new Button()
        .Margin(12)
        .HorizontalAlignment(HorizontalAlignment.Center)
        .Command(() => vm.IncrementCounter)
        .Content("Increment Counter by Step Size")
    ```

- The final code for **MainPage.cs** should look like this:

    ```csharp
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.DataContext(new MainViewModel(), (page, vm) => page
                .Background(ThemeResource.Get<Brush>("ApplicationPageBackgroundThemeBrush"))
                .Content(
                    new StackPanel()
                        .VerticalAlignment(VerticalAlignment.Center)
                        .Children(
                            new Image()
                                .Margin(12)
                                .HorizontalAlignment(HorizontalAlignment.Center)
                                .Width(150)
                                .Height(150)
                                .Source("ms-appx:///Assets/logo.png"),
                            new TextBox()
                                .Margin(12)
                                .HorizontalAlignment(HorizontalAlignment.Center)
                                .TextAlignment(Microsoft.UI.Xaml.TextAlignment.Center)
                                .PlaceholderText("Step Size")
                                .Text(x => x.Binding(() => vm.Countable.Step).TwoWay()),
                            new TextBlock()
                                .Margin(12)
                                .HorizontalAlignment(HorizontalAlignment.Center)
                                .TextAlignment(Microsoft.UI.Xaml.TextAlignment.Center)
                                .Text(() => vm.Countable.Count, txt => $"Counter: {txt}"),
                            new Button()
                                .Margin(12)
                                .HorizontalAlignment(HorizontalAlignment.Center)
                                .Command(() => vm.IncrementCounter)
                                .Content("Increment Counter by Step Size")
                        )
                )
            );
        }
    }
    ```

[!INCLUDE [Wrap up](includes/include-wrap.md)]

If you want to see the completed application, you can download the source code from [GitHub](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Counter/CSharp-MVUX).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/getting-started/counterapp/get-started-counter-csharp-mvvm.md

---
uid: Uno.Workshop.Counter.CSharp.MVVM
---

# Counter App using C# Markup and MVVM

[Download the complete C# Markup + MVVM sample](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Counter/CSharp-MVVM)  

[!INCLUDE [Intro](includes/include-intro.md)]

In this tutorial you will learn how to:

- Create a new Project with Uno Platform using Visual Studio Template Wizard or the **dotnet new** command
- Add elements to the C# file, using [C# Markup](xref:Uno.Extensions.Markup.Overview), to define the layout of the application
- Add code to the C# file to implement the application logic using the Model-View-ViewModel (MVVM) pattern
- Use data binding to connect the UI to the application logic

To complete this tutorial you don't need any prior knowledge of the Uno Platform or C#.

[!INCLUDE [VS](includes/include-create.md)]

## [Visual Studio](#tab/vs)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Visual Studio** installed, follow [these instructions](xref:Uno.GetStarted.vs2022).

- Launch **Visual Studio** and click on **Create new project** on the Start Window. Alternatively, if you're already in Visual Studio, click **New, Project** from the **File** menu.

- Type `Uno Platform` in the search box

- Click **Uno Platform App**, then **Next**

- Name the project `Counter` and click **Create**

At this point you'll enter the **Uno Platform Template Wizard**, giving you options to customize the generated application. For this tutorial, we're only going to configure the markup language and the presentation framework.

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVVM**

- Select the **Markup** tab and choose **C# Markup**

Before completing the wizard, take a look through each of the sections and see what other options are available. You can always come back and create a new project with different options later. For more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

- Click **Create** to complete the wizard

The template will create a solution with a simple cross-platform project, named `Counter`, ready to run.

### [Rider](#tab/rider)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Rider** installed, follow [these instructions](xref:Uno.GetStarted.Rider).

- Launch **Rider** and click on **New Solution** on the Start Window

- From the left menu, under the **Uno Platform** section, select **Uno Platform App**
  At this point, you'll see options for creating a new Uno app, allowing you to customize the generated application. For this tutorial, we will only configure the presentation framework.

- Name the project `Counter`

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVVM**

- Select the Markup tab and choose **C# Markup**

- Click **Create** to complete the creation
  The template will create a solution with a single cross-platform project, named `Counter`, ready to run.

### [VS Code](#tab/vscode)

> [!NOTE]
> If you don't have the **Uno Platform Extension for VS Code** installed, follow [these instructions](xref:Uno.GetStarted.vscode).

- Launch The Live Wizard by visiting the [Uno Platform Live Wizard](https://new.platform.uno/)

- Name the project `Counter` and click **Start**

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVVM**

- Select the Markup tab and choose **C# Markup**

- Click **Create** to complete the wizard

- Copy the `dotnet new` command and run it from a terminal where you want your solution to be located.

- This will create a new folder called **Counter** containing the new application.

- Next, open the project using Visual Studio Code. In the terminal type the following:

  ```bash
  code ./Counter
  ```

- Visual Studio Code might ask to restore the NuGet packages. Allow it to restore them if asked.

- Once the solution has been loaded, in the status bar at the bottom left of VS Code, `Counter.sln` is selected by default. Select `Counter.csproj` to load the project instead.
  ![Counter.csproj selection in Visual Studio Code](Assets/vscode-csproj-dotnet9.0.png)

## [Command Line](#tab/cli)

> [!NOTE]
> If you don't have the Uno Platform dotnet new templates installed, follow [dotnet new templates for Uno Platform](xref:Uno.GetStarted.dotnet-new).

From the command line, run the following command:

```dotnetcli
dotnet new unoapp -preset blank -presentation mvvm -markup csharp -o Counter
```

This will create a new folder called **Counter** containing the new application.

If you want to discover all the options available in the **unoapp** template, run the following command:

```dotnetcli
dotnet new unoapp -h
```

Also, for more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

---

[!INCLUDE [Counter Solution](includes/include-solution.md)]

[!INCLUDE [Notice](includes/include-vscode-csproj-notice.md)]

[!INCLUDE [Main Window](includes/include-mainwindow.md)]

[!INCLUDE [Main Page - C# Markup](includes/include-mainpage-csharp.md)]

[!INCLUDE [Main Page - Layout](includes/include-mainpage-layout.md)]

[!INCLUDE [Main Page - Image](includes/include-image-csharp.md)]

[!INCLUDE [Main Page - Change Layout](includes/include-mainpage-change-layout.md)]

[!INCLUDE [Main Page - Other Elements](includes/include-elements-csharp.md)]

[!INCLUDE [View Model](includes/include-mvvm.md)]

## Data Binding

Now that we have the **`MainViewModel`** class, we can update the **`MainPage`** to use data binding to connect the UI to the application logic.

- Let's add the **`DataContext`** to our page. To do so, add `.DataContext(new MainViewModel(), (page, vm) => page` before `.Background(...)`. Remember to close the **`DataContext`** expression with a `)` at the end of the code. It should look similar to the code below:

    ```csharp
    this.DataContext(new MainViewModel(), (page, vm) => page
        .Background(ThemeResource.Get<Brush>("ApplicationPageBackgroundThemeBrush"))
        .Content(
            ...
        )
    );
    ```

- Update the **`TextBlock`** by removing its current text content and replacing it with a binding expression for the **`Count`** property of the **`MainViewModel`**. Modify the existing **`Text`** property with `() => vm.Count, txt => $"Counter: {txt}"`. The adjusted code is as follows:

    ```csharp
    new TextBlock()
        .Margin(12)
        .HorizontalAlignment(HorizontalAlignment.Center)
        .TextAlignment(Microsoft.UI.Xaml.TextAlignment.Center)
        .Text(() => vm.Count, txt => $"Counter: {txt}")
    ```

- Update the **`TextBox`** by binding the **`Text`** property to the **`Step`** property of the **`MainViewModel`**. The **`Mode`** of the binding is set to **`TwoWay`** so that the **`Step`** property is updated when the user changes the value in the **`TextBox`**.

    ```csharp
    new TextBox()
        .Margin(12)
        .HorizontalAlignment(HorizontalAlignment.Center)
        .TextAlignment(Microsoft.UI.Xaml.TextAlignment.Center)
        .PlaceholderText("Step Size")
        .Text(x => x.Binding(() => vm.Step).TwoWay())
    ```

- Update the **`Button`** to add a **`Command`** property that is bound to the **`IncrementCommand`** property of the **`MainViewModel`**.

    ```csharp
    new Button()
        .Margin(12)
        .HorizontalAlignment(HorizontalAlignment.Center)
        .Command(() => vm.IncrementCommand)
        .Content("Increment Counter by Step Size")
    ```

- The final code for **MainPage.cs** should look like this:

    ```csharp
    public sealed partial class MainPage : Page
    {
        public MainPage()
        {
            this.DataContext(new MainViewModel(), (page, vm) => page
                .Background(ThemeResource.Get<Brush>("ApplicationPageBackgroundThemeBrush"))
                .Content(
                    new StackPanel()
                        .VerticalAlignment(VerticalAlignment.Center)
                        .Children(
                            new Image()
                                .Margin(12)
                                .HorizontalAlignment(HorizontalAlignment.Center)
                                .Width(150)
                                .Height(150)
                                .Source("ms-appx:///Assets/logo.png"),
                            new TextBox()
                                .Margin(12)
                                .HorizontalAlignment(HorizontalAlignment.Center)
                                .TextAlignment(Microsoft.UI.Xaml.TextAlignment.Center)
                                .PlaceholderText("Step Size")
                                .Text(x => x.Binding(() => vm.Step).TwoWay()),
                            new TextBlock()
                                .Margin(12)
                                .HorizontalAlignment(HorizontalAlignment.Center)
                                .TextAlignment(Microsoft.UI.Xaml.TextAlignment.Center)
                                .Text(() => vm.Count, txt => $"Counter: {txt}"),
                            new Button()
                                .Margin(12)
                                .HorizontalAlignment(HorizontalAlignment.Center)
                                .Command(() => vm.IncrementCommand)
                                .Content("Increment Counter by Step Size")
                        )
                )
            );
        }
    }
    ```

[!INCLUDE [Wrap Up](includes/include-wrap.md)]

If you want to see the completed application, you can download the source code from [GitHub](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Counter/CSharp-MVVM).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/getting-started/counterapp/get-started-counter-xaml-mvux.md

---
uid: Uno.Workshop.Counter.XAML.MVUX
---

# Counter App using XAML and MVUX

[Download the complete XAML + MVUX sample](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Counter/XAML-MVUX)  

[!INCLUDE [Intro](includes/include-intro.md)]

In this tutorial you will learn how to:

- Create a new Project with Uno Platform using Visual Studio Template Wizard or the **dotnet new** command
- Add elements to the XAML file to define the layout of the application
- Add code to the C# file to implement the application logic using the [Model-View-Update-eXtended (MVUX)](xref:Uno.Extensions.Mvux.Overview) pattern
- Use data binding to connect the UI to the application logic

To complete this tutorial you don't need any prior knowledge of the Uno Platform, XAML, or C#.

[!INCLUDE [VS](includes/include-create.md)]

## [Visual Studio](#tab/vs)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Visual Studio** installed, follow [these instructions](xref:Uno.GetStarted.vs2022).

- Launch **Visual Studio** and click on **Create new project** on the Start Window. Alternatively, if you're already in Visual Studio, click **New, Project** from the **File** menu.

- Type `Uno Platform` in the search box

- Click **Uno Platform App**, then **Next**

- Name the project `Counter` and click **Create**

At this point you'll enter the **Uno Platform Template Wizard**, giving you options to customize the generated application. For this tutorial, we're only going to configure the markup language and the presentation framework.

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVUX**

- Select the **Markup** tab and choose **XAML**

Before completing the wizard, take a look through each of the sections and see what other options are available. You can always come back and create a new project with different options later. For more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

- Click **Create** to complete the wizard

The template will create a solution with a single cross-platform project, named `Counter`, ready to run.

### [Rider](#tab/rider)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Rider** installed, follow [these instructions](xref:Uno.GetStarted.Rider).

- Launch **Rider** and click on **New Solution** on the Start Window

- From the left menu, under the **Uno Platform** section, select **Uno Platform App**
  At this point, you'll see options for creating a new Uno app, allowing you to customize the generated application. For this tutorial, we will only configure the presentation framework.

- Name the project `Counter`

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVUX**

- Select the Markup tab and choose **XAML Markup**

- Click **Create** to complete the creation
  The template will create a solution with a single cross-platform project, named `Counter`, ready to run.

### [VS Code](#tab/vscode)

> [!NOTE]
> If you don't have the **Uno Platform Extension for VS Code** installed, follow [these instructions](xref:Uno.GetStarted.vscode).

- Launch The Live Wizard by visiting the [Uno Platform Live Wizard](https://new.platform.uno/)

- Name the project `Counter` and click **Start**

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVUX**

- Select the Markup tab and choose **XAML Markup**

- Click **Create** to complete the wizard

- Copy the `dotnet new` command and run it from a terminal where you want your solution to be located.

- This will create a new folder called **Counter** containing the new application.

- Next, open the project using Visual Studio Code. In the terminal type the following:

  ```bash
  code ./Counter
  ```

- Visual Studio Code might ask to restore the NuGet packages. Allow it to restore them if asked.

- Once the solution has been loaded, in the status bar at the bottom left of VS Code, `Counter.sln` is selected by default. Select `Counter.csproj` to load the project instead.
  ![Counter.csproj selection in Visual Studio Code](Assets/vscode-csproj-dotnet9.0.png)

## [Command Line](#tab/cli)

> [!NOTE]
> If you don't have the Uno Platform dotnet new templates installed, follow [dotnet new templates for Uno Platform](xref:Uno.GetStarted.dotnet-new).

From the command line, run the following command:

```dotnetcli
dotnet new unoapp -preset blank -presentation mvux -markup xaml -o Counter
```

This will create a new folder called **Counter** containing the new application.

If you want to discover all the options available in the **unoapp** template, run the following command:

```dotnetcli
dotnet new unoapp -h
```

Also, for more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

---

[!INCLUDE [Counter Solution](includes/include-solution.md)]

![Counter Solution](Assets/counter-solution-xaml.png)

[!INCLUDE [Main Window](includes/include-mainwindow.md)]

[!INCLUDE [Main Page - XAML](includes/include-mainpage-xaml.md)]

[!INCLUDE [Main Page - Layout](includes/include-mainpage-layout.md)]

[!INCLUDE [Main Page - Image](includes/include-image-xaml.md)]

[!INCLUDE [Main Page - Change Layout](includes/include-mainpage-change-layout.md)]

[!INCLUDE [Main Page - Other Elements](includes/include-elements-xaml.md)]

[!INCLUDE [Main Model](includes/include-mvux.md)]

## Data Binding

As the application uses MVUX, the `MainModel` class is used to generate a bindable ViewModel, `MainViewModel`. We can update the **`MainPage`** to use data binding to connect the UI to the application logic.

- Add a **`DataContext`** element to the **`Page`** element in the **MainPage.xaml** file.

    ```xml
    <Page.DataContext>
        <local:MainViewModel />
    </Page.DataContext>
    ```

- Update the **`TextBlock`** by removing the **`Text`** attribute, replacing it with two **`Run`** elements, and binding the **`Text`** property of the second **`Run`** element to the **`Countable.Count`** property of the **MainViewModel**.

    ```xml
    <TextBlock Margin="12"
               HorizontalAlignment="Center"
               TextAlignment="Center">
        <Run Text="Counter: " /><Run Text="{Binding Countable.Count}" />
    </TextBlock>
    ```

- Update the **`TextBox`** by binding the **`Text`** property to the **`Countable.Step`** property of the **MainViewModel**. The **`Mode`** of the binding is set to **`TwoWay`** so that the **`Countable.Step`** property is updated when the user changes the value in the **`TextBox`**.

    ```xml
    <TextBox Margin="12"
             HorizontalAlignment="Center"
             PlaceholderText="Step Size"
             Text="{Binding Countable.Step, Mode=TwoWay}"
             TextAlignment="Center" />
    ```

- Update the **`Button`** to add a **`Command`** attribute that is bound to the **`IncrementCounter`** task of the **`MainViewModel`**.

    ```xml
    <Button Margin="12"
            HorizontalAlignment="Center"
            Command="{Binding IncrementCounter}"
            Content="Increment Counter by Step Size" />
    ```

The final code for **MainPage.xaml** should look like this:

```xml
<Page x:Class="Counter.MainPage"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:local="using:Counter"
      Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
  <Page.DataContext>
    <local:MainViewModel />
  </Page.DataContext>
  <StackPanel VerticalAlignment="Center">
    <Image Width="150"
           Height="150"
           Margin="12"
           HorizontalAlignment="Center"
           Source="Assets/logo.png" />

    <TextBox Margin="12"
             HorizontalAlignment="Center"
             PlaceholderText="Step Size"
             Text="{Binding Countable.Step, Mode=TwoWay}"
             TextAlignment="Center" />

    <TextBlock Margin="12"
               HorizontalAlignment="Center"
               TextAlignment="Center">
        <Run Text="Counter: " /><Run Text="{Binding Countable.Count}" />
    </TextBlock>

    <Button Margin="12"
            HorizontalAlignment="Center"
            Command="{Binding IncrementCounter}"
            Content="Increment Counter by Step Size" />
  </StackPanel>
</Page>
```

[!INCLUDE [Wrap Up](includes/include-wrap.md)]

If you want to see the completed application, you can download the source code from [GitHub](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Counter/XAML-MVUX).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/getting-started/counterapp/get-started-counter-xaml-mvvm.md

---
uid: Uno.Workshop.Counter.XAML.MVVM
---

# Counter App using XAML and MVVM

[Download the complete XAML + MVVM sample](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Counter/XAML-MVVM)  

[!INCLUDE [Intro](includes/include-intro.md)]

In this tutorial you will learn how to:

- Create a new Project with Uno Platform using Visual Studio Template Wizard or the **dotnet new** command
- Add elements to the XAML file to define the layout of the application
- Add code to the C# file to implement the application logic using the Model-View-ViewModel (MVVM) pattern
- Use data binding to connect the UI to the application logic

To complete this tutorial you don't need any prior knowledge of the Uno Platform, XAML, or C#.

[!INCLUDE [VS](includes/include-create.md)]

## [Visual Studio](#tab/vs)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Visual Studio** installed, follow [these instructions](xref:Uno.GetStarted.vs2022).

- Launch **Visual Studio** and click on **Create new project** on the Start Window. Alternatively, if you're already in Visual Studio, click **New, Project** from the **File** menu.

- Type `Uno Platform` in the search box

- Click **Uno Platform App**, then **Next**

- Name the project `Counter` and click **Create**

At this point you'll enter the **Uno Platform Template Wizard**, giving you options to customize the generated application. For this tutorial, we're only going to configure the markup language and the presentation framework.

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVVM**

- Select the **Markup** tab and choose **XAML**

Before completing the wizard, take a look through each of the sections and see what other options are available. You can always come back and create a new project with different options later. For more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

- Click **Create** to complete the wizard

The template will create a solution with a single cross-platform project, named `Counter`, ready to run.

### [Rider](#tab/rider)

> [!NOTE]
> If you don't have the **Uno Platform Extension for Rider** installed, follow [these instructions](xref:Uno.GetStarted.Rider).

- Launch **Rider** and click on **New Solution** on the Start Window

- From the left menu, under the **Uno Platform** section, select **Uno Platform App**
  At this point, you'll see options for creating a new Uno app, allowing you to customize the generated application. For this tutorial, we will only configure the presentation framework.

- Name the project `Counter`

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVVM**

- Select the Markup tab and choose **XAML Markup**

- Click **Create** to complete the creation
  The template will create a solution with a single cross-platform project, named `Counter`, ready to run.

### [VS Code](#tab/vscode)

> [!NOTE]
> If you don't have the **Uno Platform Extension for VS Code** installed, follow [these instructions](xref:Uno.GetStarted.vscode).

- Launch The Live Wizard by visiting the [Uno Platform Live Wizard](https://new.platform.uno/)

- Name the project `Counter` and click **Start**

- Select **Blank** in **Presets** selection

- Select the **Presentation** tab and choose **MVVM**

- Select the Markup tab and choose **XAML Markup**

- Click **Create** to complete the wizard

- Copy the `dotnet new` command and run it from a terminal where you want your solution to be located.

- This will create a new folder called **Counter** containing the new application.

- Next, open the project using Visual Studio Code. In the terminal type the following:

  ```bash
  code ./Counter
  ```

- Visual Studio Code might ask to restore the NuGet packages. Allow it to restore them if asked.

- Once the solution has been loaded, in the status bar at the bottom left of VS Code, `Counter.sln` is selected by default. Select `Counter.csproj` to load the project instead.
  ![Counter.csproj selection in Visual Studio Code](Assets/vscode-csproj-dotnet9.0.png)

## [Command Line](#tab/cli)

> [!NOTE]
> If you don't have the Uno Platform dotnet new templates installed, follow [dotnet new templates for Uno Platform](xref:Uno.GetStarted.dotnet-new).

From the command line, run the following command:

```dotnetcli
dotnet new unoapp -preset blank -presentation mvvm -markup xaml -o Counter
```

This will create a new folder called **Counter** containing the new application.

If you want to discover all the options available in the **unoapp** template, run the following command:

```dotnetcli
dotnet new unoapp -h
```

Also, for more information on all the template options, see [Using the Uno Platform Template](xref:Uno.GettingStarted.UsingWizard).

---

[!INCLUDE [Counter Solution](includes/include-solution.md)]

![Counter Solution](Assets/counter-solution-xaml.png)

[!INCLUDE [Main Window](includes/include-mainwindow.md)]

[!INCLUDE [Main Page - XAML](includes/include-mainpage-xaml.md)]

[!INCLUDE [Main Page - Layout](includes/include-mainpage-layout.md)]

[!INCLUDE [Main Page - Image](includes/include-image-xaml.md)]

[!INCLUDE [Main Page - Change Layout](includes/include-mainpage-change-layout.md)]

[!INCLUDE [Main Page - Other Elements](includes/include-elements-xaml.md)]

[!INCLUDE [View Model](includes/include-mvvm.md)]

## Data Binding

Now that we have the **`MainViewModel`** class, we can update the **`MainPage`** to use data binding to connect the UI to the application logic.

- Add a **`DataContext`** element to the **`Page`** element in the **MainPage.xaml** file, between the first `StackPanel` and the `Page` element.

    ```xml
    <Page.DataContext>
        <local:MainViewModel />
    </Page.DataContext>
    ```

- Update the **`TextBlock`** by removing the **`Text`** attribute, replacing it with two **`Run`** elements, and binding the **`Text`** property of the second **`Run`** element to the **`Count`** property of the **`MainViewModel`**.

    ```xml
    <TextBlock Margin="12"
               HorizontalAlignment="Center"
               TextAlignment="Center">
        <Run Text="Counter: " /><Run Text="{Binding Count}" />
    </TextBlock>
    ```

- Update the **`TextBox`** by binding the **`Text`** property to the **`Step`** property of the **MainViewModel**. The **`Mode`** of the binding is set to **`TwoWay`** so that the **`Step`** property is updated when the user changes the value in the **`TextBox`**.

    ```xml
    <TextBox Margin="12"
             HorizontalAlignment="Center"
             PlaceholderText="Step Size"
             Text="{Binding Step, Mode=TwoWay}"
             TextAlignment="Center" />
    ```

- Update the **`Button`** by adding a **`Command`** attribute that is bound to the **`IncrementCommand`** property of the **`MainViewModel`**.

    ```xml
    <Button Margin="12"
            HorizontalAlignment="Center"
            Command="{Binding IncrementCommand}"
            Content="Increment Counter by Step Size" />
    ```

The final code for **MainPage.xaml** should look like this:

```xml
<Page x:Class="Counter.MainPage"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:local="using:Counter"
      Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
  <Page.DataContext>
    <local:MainViewModel />
  </Page.DataContext>
  <StackPanel VerticalAlignment="Center">
    <Image Width="150"
           Height="150"
           Margin="12"
           HorizontalAlignment="Center"
           Source="Assets/logo.png" />

    <TextBox Margin="12"
             HorizontalAlignment="Center"
             PlaceholderText="Step Size"
             Text="{Binding Step, Mode=TwoWay}"
             TextAlignment="Center" />

    <TextBlock Margin="12"
               HorizontalAlignment="Center"
               TextAlignment="Center">
        <Run Text="Counter: " /><Run Text="{Binding Count}" />
    </TextBlock>

    <Button Margin="12"
            HorizontalAlignment="Center"
            Command="{Binding IncrementCommand}"
            Content="Increment Counter by Step Size" />
  </StackPanel>
</Page>
```

[!INCLUDE [Wrap Up](includes/include-wrap.md)]

If you want to see the completed application, you can download the source code from [GitHub](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Counter/XAML-MVVM).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/getting-started/counterapp/get-started-counter.md

---
uid: Uno.Workshop.Counter
---

<!-- markdownlint-disable MD001 -->

# Create a Counter App with Uno Platform

The Counter tutorial will walk you through creating a simple cross-platform counter application with Uno Platform.

<p align="center">
  <img src="Assets/counter-app.png" alt="Screenshot of an Uno Platform app showing a counter" />
</p>

There are four variants of the Counter tutorial, combining markup language (XAML or C# Markup) and presentation framework (MVVM or MVUX). Also, you can build the Counter tutorial using our visual designer, Hot Design.

<div class="row">

<div class="col-md-6 col-xs-12">
<a href="get-started-counter-xaml-mvux.md">
<div class="alert alert-info alert-hover">

#### XAML + MVUX

Use XAML for layout and MVUX for state management

</div>
</a>
</div>

<div class="col-md-6 col-xs-12">
<a href="get-started-counter-xaml-mvvm.md">
<div class="alert alert-info alert-hover">

#### XAML + MVVM

Use XAML for layout and MVVM for state management

</div>
</a>
</div>

<div class="col-md-6 col-xs-12">
<a href="get-started-counter-csharp-mvux.md">
<div class="alert alert-info alert-hover">

#### C# Markup + MVUX

Use C# Markup for layout and MVUX for state management

</div>
</a>
</div>

<div class="col-md-6 col-xs-12">
<a href="get-started-counter-csharp-mvvm.md">
<div class="alert alert-info alert-hover">

#### C# Markup + MVVM

Use C# Markup for layout and MVVM for state management

</div>
</a>
</div>

</div>

<!-- Centered last item -->
<div class="row" style="display: flex; justify-content: center; align-items: center;">
<div class="col-md-6 col-xs-12">
<a href="../../studio/Hot Design/hot-design-getstarted-counter-tutorial.md">
<div class="alert alert-info alert-hover">

#### Hot Design

Use a visual designer to design and develop the app

</div>
</a>
</div>
</div>

<br/>

---

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-dotnet-new.md

---
uid: Uno.GetStarted.dotnet-new
---

# dotnet new templates for Uno Platform

The Uno Platform provides a set of command-line templates to create cross-platform applications.

To install the templates, type the following:

```dotnetcli
dotnet new install Uno.Templates
```

To determine all parameters available for a template use `dotnet new [templatename] -h`.

> [!IMPORTANT]
> Installing the templates is done per dotnet CLI version. Meaning that the templates are installed for the version shown by `dotnet --version`. If you tried to use the templates with a version different than the one you used for installing, you'll get "No templates found matching: '<template-name>'." error.
>
> This is common when using `global.json` that alters the .NET CLI/SDK version. Specifically, it's common for the UI Test template.

[!include[use-uno-check](includes/use-uno-check-inline.md)]

## Uno Platform Application

This template can be used to create a multi-platform application for iOS, Android, WebAssembly, Linux, and Win32 Desktop, which uses the new WinUI 3 APIs.

> [!TIP]
> To create a new Uno Platform app and browse all the capabilities of the template, head to our <a target="_blank" href="https://aka.platform.uno/app-wizard">Live Wizard</a> to create a `dotnet new` command line. For a detailed overview of the Uno Platform project wizard and all its options, see the [Wizard guide](xref:Uno.GettingStarted.UsingWizard).

It comes with the **Blank** and **Recommended** presets.

To create a blank template, using minimal dependencies:

```dotnetcli
dotnet new unoapp -preset=blank -o test
```

To create from a recommended template using [Uno.Extensions](xref:Uno.Extensions.Overview):

```dotnetcli
dotnet new unoapp -preset=recommended -o test
```

> [!NOTE]
> Starting with Uno.Sdk 6.0, [Skia rendering](xref:Uno.Development.HowItWorks) is now the default rendering engine in Uno Platform templates for iOS/Android/WebAssembly. If you prefer native rendering instead, you can use the `-renderer native` parameter.

More articles on WinUI 3:

- [WinUI 3, UWP, and Uno Platform.](uwp-vs-winui3.md)
- [Updating from UWP to WinUI 3.](updating-to-winui3.md)

## Uno Platform Blank library

This template can be used to create a blank library. With this type of library, Skia and WebAssembly do not need to be built separately, but cannot be differentiated.

A basic example:

```dotnetcli
dotnet new unolib -o MyUnoLib
```

## Uno Platform MAUI Embedding Class Library

This template can be used to create a .NET MAUI Controls library to embed within your Uno Platform app.

A basic example:

```dotnetcli
dotnet new unomauilib -o MyMauiEmbeddingLibrary
```

## Uno Platform Uno.UITest library

This template creates a project for creating and running UI Tests based on [Uno.UITest](https://github.com/unoplatform/Uno.UITest).

Considering you've created an application with `dotnet new unoapp -o MyApp`, you can then create a UI Tests library with these steps:

- Create a folder name `MyApp\MyApp.UITests`
- In that folder, run `dotnet new unoapp-uitest`

This will automatically add the new project to the existing solution.

For additional information about UI Tests creation, visit the [Uno.UITest](https://github.com/unoplatform/Uno.UITest) documentation.

### Uninstalling the templates

Using a command line or terminal, run the following command:

```dotnetcli
dotnet new uninstall Uno.Templates
```

[!include[getting-help](includes/getting-help.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-explore.md

---
uid: Uno.GetStarted.Explore
---

# Build your app with Uno Platform

## AI Agents

You can start developing with various [**AI Agents**](xref:Uno.BuildYourApp.AI.Agents) to help you build your Uno Platform application faster.

## Hot Reload

Make sure to take a look at our [Hot Reload feature](xref:Uno.Features.HotReload) to enhance your development experience.

## App Solution Architecture

Next, explore the [Uno Platform App solution structure](xref:Uno.Development.AppStructure) to understand how to navigate the projects of your new app.

## Troubleshoot Issues

You may encounter issues while developing your app. Please see the [troubleshooting](xref:Uno.UI.CommonIssues) section.

## Next Steps

Now that you have built your first application, you can head to [our tutorials](xref:Uno.Workshop.Counter) on how to work on your Uno Platform app.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-licensing.md

---
uid: Uno.GetStarted.Licensing
---

# Sign in with Uno Platform

Sign in with your Uno Platform account directly in your favorite IDE (Visual Studio, VS Code, or Rider), to unlock powerful tools like Hot Reload, helping you speed up development. With a single registration, you also get early access to new features and the opportunity to connect with the Uno Platform community to share feedback and network.

## Create your account

1. Go to our website, [platform.uno](https://platform.uno/), and click on the **Sign in** button in the top right corner, or go directly to [platform.uno/my-account](https://platform.uno/my-account).
1. Enter your email address and click on **Register**.
1. On the registration page, fill in your information. Once done, click on **Sign up**.
1. You will receive a confirmation email from `no-reply@platform.uno`. Follow the instructions in the email to activate your account.
1. You should then see the sign-in page. Enter your email and password and click on **Sign in** to access your account details, where you can update information or add more details.

## Sign in to your IDE of choice

After creating your Uno Platform account, follow the steps below to sign in to your preferred IDE:

**I am developing on...**

### [**Visual Studio**](#tab/vs2022)

If you've already set up **Visual Studio** by following the [Get Started on Visual Studio](xref:Uno.GetStarted.vs2022) documentation, sign in as follows:

1. Create a new Uno Platform project by following the [Creating an app with Visual Studio](xref:Uno.GettingStarted.CreateAnApp.VS2022) documentation or open an existing one with Uno.Sdk version 5.5 or higher.

   For existing applications, you should take this opportunity to update to the [latest `Uno.Sdk` version](https://www.nuget.org/packages/Uno.Sdk). See our [migration guide](xref:Uno.Development.MigratingFromPreviousReleases) to upgrade.

2. After your project has finished loading, a notification should appear. Click on the **Sign in / Register** button.

   ![Visual Studio notification](Assets/uno-settings-notification.png)

   > [!TIP]
   > Ensure that the lower left IDE icon shows a check mark and says "Ready" ![A checkmark with a text saying ready](getting-started/wizard/assets/vs2022-ready-statusbar.png). This ensures that the projects have been created, and their dependencies have been restored completely.
   >
   > [!NOTE]
   > If the notification doesn’t appear, access the Studio app by clicking on **Extensions** > **Uno Platform** > **Studio...**.
   >
   > ![Visual Studio Menu](Assets/uno-settings-vs.png)

### [**Visual Studio Code**](#tab/vscode)

If you’ve already set up **Visual Studio Code** by following the [Get Started on VS Code](xref:Uno.GetStarted.vscode) documentation, sign in as follows:

1. Create a new Uno Platform project by following the [Creating an app with VS Code](xref:Uno.GettingStarted.CreateAnApp.VSCode) documentation or open an existing one with Uno.Sdk version 5.5 or higher.

   For existing applications, you should take this opportunity to update to the [latest `Uno.Sdk` version](https://www.nuget.org/packages/Uno.Sdk). See our [migration guide](xref:Uno.Development.MigratingFromPreviousReleases) to upgrade.

1. After your project has finished loading, check the status bar at the bottom left of VS Code. By default, `YourProjectName.sln` is selected. Switch to `YourProjectName.csproj` to load the project instead.

   ![Selecting the proper project in Visual Studio Code](Assets/uno-settings-vsc-select-project.png)

1. Once you've switched to the proper project, a notification should appear. Click the **Sign in / Register** button.

   ![Visual Studio Code notification](Assets/uno-settings-vsc-notification.png)

   > [!NOTE]
   > If the notification doesn’t appear, access the Studio app by selecting **View** > **Command Palette...** and typing `Uno Platform: Open Studio`.
   >
   > ![Visual Studio Code Menu](Assets/uno-settings-vsc.jpeg)

### [**JetBrains Rider**](#tab/rider)

If you’ve already set up **JetBrains Rider** by following the [Get Started on JetBrains Rider](xref:Uno.GetStarted.Rider) documentation, sign in as follows:

1. Create a new Uno Platform project by following the [Create an app with JetBrains Rider](xref:Uno.GettingStarted.CreateAnApp.Rider) documentation or open an existing one with Uno.Sdk version 5.5 or higher.

   For existing applications, you should take this opportunity to update to the [latest `Uno.Sdk` version](https://www.nuget.org/packages/Uno.Sdk). See our [migration guide](xref:Uno.Development.MigratingFromPreviousReleases) to upgrade.

1. After your project has finished loading, a notification should appear. Click on the **Sign in / Register** button.

   ![JetBrains Rider notification](Assets/uno-settings-rider-notification.png)

   > [!NOTE]
   > If the notification doesn’t appear, access the Studio app by selecting **Tools** > **Uno Platform** > **Studio...**.
   >
   > ![JetBrains Rider Menu](Assets/uno-settings-rider.png)

---

### Uno Platform Studio Window

1. In the Uno Platform Studio window, click on **Sign in**. You’ll be redirected to your browser to enter your Uno Platform account credentials.

   ![Uno Platform Studio Window Welcome](Assets/uno-studio-welcome.png)

2. After signing in (or creating your account), return to the Uno Platform Studio window. You’ll now see your account and subscription details displayed. Your subscription type (Community or Pro) determines which products you can access. From the overflow menu (...), you can access additional resources, refresh your account information, or sign out.

   ![Uno Platform Studio Window Main](Assets/uno-studio-main.png)

### Uno Platform Studio Pro 15-Day Trial

The Community edition of **Uno Platform Studio** includes a 15-day trial of **Uno Platform Studio Pro**, which includes **Hot Design<sup>®</sup>**, **Hot Design<sup>®</sup> Agent**, and **Uno MCPs**. If your **Uno Platform Studio Pro** trial has expired, you’ll have the option to extend it directly from the Uno Studio Platform window—or, if you’re ready to upgrade, simply click **Purchase Now**. This will take you to the Uno Platform website, where you can choose your subscription plan and the number of licenses you need.

## Getting a Uno Platform Studio Pro License

**Uno Platform Studio** revolutionizes how developers design, build, and iterate on their applications. When you purchase a **Uno Platform Studio Pro** license, you get full access to purpose-built tools that streamline your workflow:

- **[Hot Design<sup>®</sup>](xref:Uno.HotDesign.Overview)**: The industry-first, runtime visual designer, for cross-platform .NET Applications. Hot Design<sup>®</sup> transforms your running app into a Designer, from any IDE, on any OS, to create polished interfaces with ease. [Get started](xref:Uno.HotDesign.GetStarted.Guide)
  
- **[Hot Design<sup>®</sup> Agent](xref:Uno.HotDesign.Agent)**: An AI-powered assistant designed for rapid UX/UI creation and enhancement within your application. It leverages data contexts and live previews to help developers design, refine, and interact with user interfaces in real time. Built on deep knowledge of Uno Platform and your running app, it simplifies cross-platform .NET design, enabling intuitive and efficient workflows.[Learn more](xref:Uno.HotDesign.Agent)

- **[Uno MCPs](xref:Uno.Features.Uno.MCPs)**: Uno MCP connects AI agents and developers directly to Uno Platform’s complete knowledge base - documentation, APIs, and best practices with structured, semantic access. The App MCP is a local runtime service that allows AI agents and automation tools to intelligently interact with a live Uno Platform application. [Get started](xref:Uno.GetStarted)

- **[Hot Reload](xref:Uno.Features.HotReload)**  
  Reliably update any code in your app and get instant confirmation your changes were applied, with a new Hot Reload Indicator to monitor changes while you develop. [Get started](xref:Uno.HotReload.GetStarted.Guide)

- **[Design-to-Code](xref:Uno.Figma.GetStarted)**
  Generate ready-to-use, well-structured XAML or C# Markup directly from your Figma designs with one click, completely eliminating manual design handoff. [Get started](xref:Uno.Figma.GetStarted)

Check out [Compare Uno Platform Studio Community vs Pro plan](https://platform.uno/select-subscription/) to see what you gain by upgrading.

> [!IMPORTANT]
> Uno Platform itself remains open-source and free under Apache 2.0. The Pro subscription is specifically for Uno Platform Studio features.

![Uno Platform Studio compare](Assets/uno-studio-plans-compare.png)

### Purchase a Pro License

1. Visit [platform.uno/select-subscription](https://platform.uno/select-subscription/) to view subscription options and current pricing.
1. Choose your preferred billing cycle (monthly or yearly).
1. Add how many licenses you want above **Buy Now** Button.
1. Click **Buy Now** on your selected plan.
1. If you don't have a Uno Platform account yet, you'll be prompted to create one during the checkout process.
1. Complete the payment process and receive your license confirmation email.

### Special Pricing

- **Students and Open Source Maintainers**: Contact [info@platform.uno](mailto:info@platform.uno) for special pricing
- **Enterprise/Custom Quotes**: Contact [info@platform.uno](mailto:info@platform.uno) for customized licensing

### Subscription Management

- **Cancellation**: You can cancel your subscription anytime from your [account dashboard](https://platform.uno/my-account)
- **Billing**: Invoices are sent to your registered email address

## Assigning a Uno Platform Studio Pro License

Once you have purchased a Uno Platform Studio Pro subscription, you may need to assign or activate your license:

### Activating Your License After Purchase

1. After purchasing your Pro subscription, you should receive a confirmation email with your license details.

1. Sign in to your IDE following the steps in the "Sign in to your IDE of choice" section above.

1. In the Uno Platform Studio window, click **Refresh** to update your license status.

1. Your Pro features should now be available.

### Checking License Status

If you notice a small snowflake icon next to the Hot Design<sup>®</sup> flame icon when running your Uno app, this indicates that Hot Design<sup>®</sup> is not active:

### Troubleshooting License Issues

1. **License Not Showing**:
   - Open your IDE settings and access Uno Platform Studio again
   - Click the **Refresh** button to update your account status
   - Ensure you're signed in with the correct Uno Platform account

1. **License Assignment** (for team subscriptions):
   - Log in to your Uno Platform account at [platform.uno/my-account](https://platform.uno/my-account)
   - Navigate to the **Subscriptions** section in the left navigation bar (1)
   - Enter the email address of the person you want to grant access to in the text box (2)
   - Click **Assign** to assign the license (3)
   - The recipient will receive a notification email about the license assignment

   ![Active subscription image](./studio/Assets/active-subscription-image.png)

1. **Verification**:
   - After assignment, return to your IDE settings
   - Click **Refresh** in the Uno Platform Studio window
   - You should see a blue checkmark on Hot Design<sup>®</sup>, indicating it's ready to use

### Troubleshooting Common Issues

If you encounter issues during the subscription or licensing process:

1. **Payment Problems**:
   - Verify your payment information is correct
   - Check with your bank if the transaction was blocked
   - Try using a different payment method
   - Contact [info@platform.uno](mailto:info@platform.uno) for payment assistance

1. **License Not Activated**:
   - Check your email (including spam folder) for confirmation
   - Wait up to 15 minutes for license activation
   - Use the **Refresh** button in Uno Platform Studio
   - Sign out and sign in again to your IDE

1. **Uno Platform Studio Pro Trial Expired**:
   - The 15-day trial is automatically included with Community accounts
   - After expiration, upgrade to Pro to continue using Uno Platform Studio Pro features
   - Visit [platform.uno/select-subscription](https://platform.uno/select-subscription/) to upgrade

1. **Support**:
   - Pro support covers Uno Platform Studio features only
   - For general support, visit [GitHub Discussions](https://github.com/unoplatform/uno/discussions) or [Discord](https://www.platform.uno/discord)
   - [Paid support](https://platform.uno/contact/) available for enterprise needs

## Questions

For general questions about Uno Platform, refer to the [general FAQ](xref:Uno.Development.FAQ) or see the [troubleshooting section](xref:Uno.UI.CommonIssues) for common issues and solutions.

If you encounter any issues or need further assistance, join our [Discord server](https://platform.uno/discord), connect with us via [GitHub](https://github.com/unoplatform/uno/discussions), or reach out on our [contact page](https://platform.uno/contact).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-next-steps.md

---
uid: Uno.GetStarted.NextSteps
---

# Next steps

If you have already [completed the initial getting started tutorial](xref:Uno.Workshop.Counter) and you’re now ready to learn more, these resources will help you on your way.

You will find below resources provided by our team, the community and Microsoft.

## Uno Platform provided Workshops / Step-by-step Tutorials / Samples (Free)

- [Simple Calculator Workshop](external/workshops/simple-calc/README.md). A level 100 workshop you can complete in 1 hour. It will guide you through the process of setting up your developer environment and learning essential tools, libraries, and patterns to help you develop your apps with Uno Platform.
- [Tube Player Workshop](external/workshops/tube-player/README.md). A level 200 workshop you can complete in 2 hours. It will guide through the creation of an Uno Platform application that enables the user to search for and stream YouTube videos. You will learn how to easily import Figma designs into your application.
- [Uno Chefs Sample](xref:Uno.Chefs.Overview). A robust sample app showcasing the power of Uno. With Uno Chefs, you’ll explore how to build an interactive recipe app, demonstrating everything from UI customization, navigation, and state management to integrating advanced features like media playback, responsive design, and external APIs. Plus, you can dive deeper into the app’s [Recipe Books](xref:Uno.Recipes.Overview) to see step-by-step guides on how to implement various Uno features and solve real-world problems.

## Community Provided Learning Resources (Free and Paid)

### Syncfusion - Uno Platform Succinctly eBook (Free)

Syncfusion published [Uno Platform Succinctly]( https://www.syncfusion.com/succinctly-free-ebooks/uno-platform-succinctly). A free eBook that will take you from setting up your first Uno Platform project with Syncfusion UI Controls in Visual Studio to a fully functioning single-page application.

### Pluralsight - Uno Platform Fundamentals (Paid)

If you already have a subscription to Pluralsight, you can find our [Uno Platform Fundamentals course](https://www.pluralsight.com/courses/uno-platform-fundamentals). By the end of the course, you will have created your first Uno Platform solution in Visual Studio, and you’ll have the skills and knowledge needed to build multi-platform apps with Uno Platform.

The course covers how to build a user interface in XAML, how to apply the MVVM pattern, how to adapt your user interface to different screen sizes, how to write platform-specific code and how to connect your application to a data source. _If you’re not a Pluralsight subscriber, you can still use the course with a 30-day trial._

### Skye Hoefling – Getting Started with Uno Platform (Free)

Microsoft MVP Skye Hoefling put together [Uno Platform: Getting Started Series](https://www.andrewhoefling.com/Blog/Post/uno-platform-getting-started-series), a compilation of 8 great blogs covering the basics you need to get started with Uno Platform.

1. [Uno Platform Getting Started with New Projects](https://www.andrewhoefling.com/Blog/Post/uno-platform-getting-started-with-new-projects)

2. [Uno Platform View Stack Navigation](https://www.andrewhoefling.com/Blog/Post/uno-platform-view-stack-navigation-uwp-android-ios-wasm)

3. [Uno Platform Tabbed Pages with the Command Bar](https://www.andrewhoefling.com/Blog/Post/uno-platform-tabbed-pages-with-the-command-bar-uwp-ios-android-wasm)

4. [Platform Specific XAML in Uno Platform](https://www.andrewhoefling.com/Blog/Post/platform-specific-xaml-in-uno-platform-ios-android-wasm-uwp)

5. [Platform Specific C# in Uno Platform]( https://www.andrewhoefling.com/Blog/Post/platform-specific-c-sharp-in-uno-platform-ios-android-wasm-uwp)

6. [MVVM and Dependency Injection in Uno Platform]( https://www.andrewhoefling.com/Blog/Post/mvvm-and-dependency-injection-in-uno-platform-ios-android-wasm-uwp)

7. [ViewModelLocator for MVVM applications in Uno Platform]( https://www.andrewhoefling.com/Blog/Post/view-model-locator-for-mvvm-applications-in-uno-platform)

8. [Uno Platform WASM Invoke JavaScript]( https://www.andrewhoefling.com/Blog/Post/uno-platform-wasm-invoke-javascript)

### Building a Todo App with Uno Platform (Free)

[Steven Giesel](https://github.com/linkdotnet) recently explored the ins and outs of Uno Platform and in turn, documented his experience with a great blog series that dives further into What is Uno Platform and how to build a multi-platform Todo App.

- [Part 1 –  Introduction and Environment set up](https://steven-giesel.com/blogPost/b2234ada-0978-4c7b-841e-ca6a255247b0)
- [Part 2 – Requirements & First Features]( https://steven-giesel.com/blogPost/85814db0-3495-492c-8ce1-5c83d708590b)
- [Part 3 – Dialog Component & ViewModel]( https://steven-giesel.com/blogPost/a3179d55-d5be-48ba-b570-ee7d494a8b21)
- [Part 4 – Adding Elements to the Swimlane]( https://steven-giesel.com/blogPost/2d96d970-ef11-48f4-a102-9339fc362a75)
- [Part 5 – Implementing Drag and Drop Behavior]( https://steven-giesel.com/blogPost/2c025ac6-d67f-45ec-a616-009e0285c999)

### Book - Creating Cross-Platform C# Applications with Uno Platform (Packt, Paid)

[Creating Cross-Platform C# Applications with Uno Platform](https://www.packtpub.com/product/creating-cross-platform-c-applications-with-uno-platform/9781801078498) book by Matt Lacey & Marcel Alexander Wagner is a helpful guide packed with tips and practical examples to help you build applications for common scenarios. It’s available on Packt as well as Amazon.

### Book - Getting Started with the Uno Platform and WinUI 3: Hands-On Building of Cross-Platform Desktop, Mobile, and Web Applications That Can Run Anywhere (Apress, Paid)

[Getting Started with the Uno Platform and WinUI 3: Hands-On Building of Cross-Platform Desktop, Mobile, and Web Applications That Can Run Anywhere](https://www.amazon.com/Getting-Started-Platform-WinUI-Hands-ebook/dp/B0BGZCD32H?ref_=ast_author_mpb) book by Skye Hoefling is written for the developer who has zero experience building apps with Xamarin, UWP, WinUI, or the Uno Platform. This book deconstructs those complex concepts into tangible building blocks so that productivity gains are immediately recognized.

### Raspberry Pi Applications with Uno Platform (Free)

If you are looking to bring your cross-platform apps to Raspberry Pi with Uno Platform, Peter Gallagher wrote an [article to help you get started](https://www.petecodes.co.uk/developing-uwp-apps-for-the-raspberry-pi-with-uno-platform/) or try our [getting started with Raspberry Pi documentation](xref:Uno.RaspberryPi.Intro).

### XAML Fundamentals for Web and Mobile (Free)

Any WinUI/XAML material is a great starting point, as all we do is take that over the Uno Platform bridge. To that point, one Uno Platform contributor and Microsoft MVP, Nick Randolph, has been revitalizing older XAML resources on his [.NET Travels blog](https://nicksnettravels.builttoroam.com/xaml-basics/). Uno Platform will be continuing the series on our blog.

## Microsoft docs and blogs on Uno Platform (Free)

- WinUI Documentation - Basic (2 posts) [Build a Hello World app using C# and WinUI 3 / Windows App SDK](https://learn.microsoft.com/windows/apps/how-tos/hello-world-winui3) leads you through setup of a very basic WinUI Application. The second blog post [How to target multiple platforms with your WinUI 3 app](https://learn.microsoft.com/windows/apps/how-tos/hello-world-winui3) walks you through taking that same Hello World application cross-platform using Uno PLatform.
- WinUI Documentation - Advanced (2 posts) [Tutorial: Create a simple photo viewer with WinUI 3](https://learn.microsoft.com/windows/apps/get-started/simple-photo-viewer-winui3?tabs=cs) leads you through creation of a  WinUI-based Photo Viewing Application. The second blog post [Tutorial: Build a simple photo viewer that targets multiple platforms](https://learn.microsoft.com/windows/apps/get-started/uno-simple-photo-viewer) walks you through taking the Photo Viewing application cross-platform using Uno PLatform.
- WinUI Team Blog [Building cross-platform apps with WinUI and Uno]( https://blogs.windows.com/windowsdeveloper/2021/03/11/build-cross-platform-applications-with-winui-and-uno-platform/). This tutorial walks you through building a simple same-codebase app which uses WinUI InfoBar control and runs on Windows 10, WebAssembly and Android.
- Here are two articles that will help developers [Getting started with the Surface Duo]( https://devblogs.microsoft.com/surface-duo/tag/uno-platform/).
- The Uno Platform brings Microsoft's WinUI framework to Android, iOS, macOS, Linux, WebAssembly and Embedded Devices. The wealth of [official Microsoft documentation on the WinUI framework](https://learn.microsoft.com/windows/apps/winui/winui3/) is a great place to learn, particularly if you've never used WinUI or XAML before.

## Learn by collaborating with others

### Uno Team Community Support

If you have a question about Uno Platform that others might benefit from, post it on [Uno Platform GitHub discussions](https://github.com/unoplatform/uno/discussions) or If you think you've encountered a bug (e.g. something works on WinAppSDK but not on another platform), [check for an existing issue on GitHub]( https://github.com/unoplatform/uno/issues) and create one if none exists. We don't like bugs, but we do like bug reports!

For more chat-like troubleshooting, visit the Uno Platform team and community on our [Discord Server](https://platform.uno/discord). Both have our engineering team monitoring discussions and answering questions.

## Some additional resources

- [Performance tips and tricks](xref:Uno.Development.Performance)
- The [Uno Platform YouTube](https://www.youtube.com/c/UnoPlatform) channel is also a great source for learning. On top of publishing tutorials and demos, we also have weekly live coding sessions that tackle different areas of Uno Platform.
- The [Uno Platform blog](http://platform.uno/blog) is frequently active, publishing articles weekly on a wide array of topics and varying complexity.
- The [Uno Gallery and Playground](https://github.com/unoplatform/uno.Playground) showcases many of the UI controls supported by Uno.
- For those who wish to learn from real-life code, you can use the [Ch9 sample app]( https://github.com/unoplatform/Uno.Ch9) (source code and real-world app) it uses the publicly available video feed from Microsoft's Channel 9 for content.
- With [Uno Calculator](https://calculator.platform.uno/) we took Microsoft's open-sourced Windows 10 Calculator, ported it to C#, and put it on Android, iOS, WebAssembly, macOS, and Linux. [Check out all the code here.](https://github.com/unoplatform/calculator)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-rider.md

---
uid: Uno.GetStarted.Rider
---

# Get Started on JetBrains Rider

## Prerequisites

- [**Rider Version 2024.2+**](https://aka.platform.uno/rider-version-2024-2) or [**Previous Rider Version 2024.1**](https://aka.platform.uno/rider-version-2024-1)
- [**Rider Xamarin Android Support**](https://plugins.jetbrains.com/plugin/12056-rider-xamarin-android-support/) plugin from Rider in **Settings** / **Plugins**

## Check your environment

[!include[use-uno-check](includes/use-uno-check-inline-noheader.md)]

## Supported Platforms

|                       | **Rider for Windows** | **Rider for Mac**  | **Rider for Linux** |
|-----------------------|-----------------------|--------------------|---------------------|
| Windows (WinUI)       | ✔️                   | ❌                 | ❌                 |
| Android               | ✔️                   | ✔️                 | ✔️                |
| iOS                   | ❌                   | ✔️                 | ❌                 |
| Wasm                  | ✔️†                  | ✔️†                | ✔️†                |
| Skia Desktop          | ✔️                   | ✔️                 | ✔️                |

<details>
    <summary>† Notes (Click to expand)</summary>

- **WebAssembly**: debugging from the IDE is not available yet on Rider. You can use the [Chromium in-browser debugger](xref:UnoWasmBootstrap.Features.Debugger#how-to-use-the-browser-debugger) instead.

</details>

## Install the Uno Platform plugin

In Rider, in the **Settings**, **Plugins** menu, open the **Marketplace** tab, then search for **Uno Platform**:

![Visual Studio Installer - .NET desktop development workload](Assets/ide-rider-plugin-search.png)

Then click the install button.

## Platform-specific setup

You may need to follow additional directions, depending on your development environment.

### Android & iOS

For assistance configuring Android or iOS emulators, see the [Android & iOS emulator troubleshooting guide](xref:Uno.UI.CommonIssues.MobileDebugging).

### Linux

[!include[linux-setup](includes/additional-linux-setup-inline.md)]

---

## Next Steps

You're all set! You can create your [first Uno Platform app](xref:Uno.GettingStarted.CreateAnApp.Rider).

> [!IMPORTANT]
> Project templates from Uno Platform 5.3 or later are needed to use Rider. See our [migration guide](xref:Uno.Development.MigratingFromPreviousReleases) to upgrade.
>
> [!IMPORTANT]
> Depending on the version of Rider you will want to use, here are some additional information that you will want to know:
>
> - **Current Rider (2024.2 and above)**: For the current Rider version, the Uno Platform plugin supports creating Uno Platform projects using the "New Solution" dialog.
>
> - **Previous Rider (2024.1)**: The Uno Plugin for previous versions of Rider (2024.1) does not support creating Uno Platform projects using the "New Solution" dialog, even if the Uno Platform project template appears. In this case, creating an Uno Platform project is done [using dotnet new](xref:Uno.GetStarted.dotnet-new) and the <a target="_blank" href="https://aka.platform.uno/app-wizard">Uno Platform Live Wizard</a>.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-vs-2022.md

---
uid: Uno.GetStarted.vs2022
---
# Get Started on Visual Studio

This getting started will guide you through setting up your environment to create Uno Platform applications using C#, .NET and Copilot with Visual Studio 2022/2026.

> [!TIP]
> If you want to use another environment or IDE, see our [general getting started](get-started.md).

## Install Visual Studio with Workloads

To create Uno Platform applications you will need [**Visual Studio 2022 (17.9+) or later**](https://visualstudio.microsoft.com/vs/):

1. **ASP.NET and web development** workload installed (for WebAssembly development)

    ![Visual Studio Installer - ASP.NET and web development workload](Assets/quick-start/vs-install-web.png)

1. **.NET Multi-platform App UI development** workload installed (for iOS, Android development).

    ![Visual Studio Installer - .NET Multi-platform App UI development workload](Assets/quick-start/vs-install-dotnet-mobile.png)

1. **.NET desktop development** workload installed (for Skia-based targets development)

    ![Visual Studio Installer - .NET desktop development workload](Assets/quick-start/vs-install-dotnet.png)

> [!NOTE]
> If you intend to do Linux development with WSL, make sure to select **.NET Debugging with WSL** in the **Individual components** section.
> [!IMPORTANT]
> Uno Platform 5.0 and later [does not support Xamarin projects anymore](xref:Uno.Development.MigratingToUno5). To build Xamarin-based projects in Visual Studio, in Visual Studio's installer `Individual components` tab, search for Xamarin and select `Xamarin` and `Xamarin Remoted Simulator`. See [this section on migrating Xamarin projects](migrating-from-xamarin-to-net6.md) to .NET 6.

## Check your environment

[!include[use-uno-check](includes/use-uno-check-inline-windows-noheader.md)]

## Install the Uno Platform Extension

1. Launch Visual Studio 2022/2026, then click `Continue without code`. Click `Extensions` -> `Manage Extensions` from the Menu Bar.  

    ![Visual Studio - "Extensions" drop-down selecting "Manage Extensions"](Assets/tutorial01/manage-extensions.png)  

2. In the Extension Manager expand the **Online** node and search for `Uno`, install the `Uno Platform` extension or download it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=unoplatform.uno-platform-addin-2022), then restart Visual Studio.  

    ![Extension Manager - Uno Platform extension](Assets/tutorial01/uno-extensions.PNG)

> [!NOTE]
> The Uno Platform extension provides all the tooling needed to enable AI agents from Visual Studio, VS Code, Claude Code, GitHub Copilot CLI, Codex, and more.
>
> **Uno MCP** provides structured, semantic access to Uno Platform’s complete knowledge base—covering documentation, APIs, and best practices—empowering AI agents and developers with the intelligence they need to build better experiences. Meanwhile, **App MCP** brings intelligent automation to life by enabling AI agents to interact directly with live Uno Platform applications, creating a seamless bridge between design, development, and execution.
>
> Uno Platform's MCP tools are available when you [sign in to your Uno Platform account](xref:Uno.GetStarted.Licensing). For more information, see [Using the Uno Platform MCPs](xref:Uno.Features.Uno.MCPs).

## Additional Setup for Android & iOS

For assistance configuring Android or iOS emulators, see the [Android & iOS emulator troubleshooting guide](xref:Uno.UI.CommonIssues.MobileDebugging).

## Additional Setup for Windows Subsystem for Linux (WSL)

It is possible to build and debug Skia Desktop projects under WSL if you choose to do so.

To setup your environment for WSL:

- Install [WSL Ubuntu 22.04 or later](https://learn.microsoft.com/windows/wsl/install-win10)
- Install the prerequisites for Linux mentioned below, in your installed distribution using the Ubuntu shell

> [!NOTE]
> Running Uno Platform apps using WSL makes use of [WSLg's support for Wayland](https://github.com/microsoft/wslg#install-instructions-existing-wsl-install). In general, running `wsl --update`, then optionally rebooting the Windows machine can get you started.

## Additional Setup for Skia Desktop projects

### WSL

[!include[linux-setup](includes/additional-linux-setup-inline.md)]

---

## Next Steps

You're all set to create your [first Uno Platform app](xref:Uno.GettingStarted.CreateAnApp.VS2022)!

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-vscode-devkit.md

---
uid: Uno.GetStarted.vscode.DevKit
---

# How to switch to C# Dev Kit Mode

> [!NOTE]
> Due to the [unavailability](https://github.com/microsoft/vscode-dotnettools/issues/765) of the **C# Dev Kit extension** on [OpenVSX](https://open-vsx.org), users of VSCodium, Ona... are always on the OmniSharp mode. Visit [this guide](xref:Uno.GetStarted.vscode.OmniSharp) if you need to use Omnisharp with VSCode.

## Ensure you are using either .NET 8 (or later) or Uno.WinUI 5.0.116 (or later)

C# Dev Kit requires Uno Platform extension 0.12 or later. The extension itself need .NET 8 (or later) or your projects need to use Uno Platform 5.0.116 (or later).

### .NET 8

From a terminal (external or inside VS Code) type:

```dotnetcli
dotnet --version
```

If the version listed is older than `8.0.100` then, inside VS Code, press `F1` and select `Run Uno-Check to setup this environment for Uno Platform` to update your system. Quit and restart VS Code afterward so the new version of `dotnet` can be used by the extensions.

If you have version `8.0.100` (or later) then there's no need to update your version of .NET or Uno.

### Uno.WinUI 5.0.116 or later

The latest versions of Uno.WinUI ship with an additional MSBuild task, so running .NET 8 is not required.

To see which version of Uno.WinUI you're currently using, open the `Directory.Packages.props` file at the root of your project and look for `Uno.WinUI`, e.g.

```xml
<PackageVersion Include="Uno.WinUI" Version="5.0.116" />
```

If you have version 5.0.116 (or later), then there's no need to update your version of .NET or Uno to use VS Code.

If you need to update you can use a tool like [`dotnet outdated`](https://github.com/dotnet-outdated/dotnet-outdated) to update your dependencies to the latest available. Also see [Migrating from previous releases](xref:Uno.Development.MigratingFromPreviousReleases) for additional information about updating your project(s).

## Disable OmniSharp

If you used the OmniSharp mode then you need to disable the `preferCSharpExtension` setting.

* Open the VS Code Settings using `Ctrl` + `,` (or `⌘` + `,` on a Mac)
* Search for `preferCSharpExtension`
    ![preferCSharpExtension](Assets/quick-start/vs-code-preferCSharpExtension.png)
* Disable it (checkbox)

> [!NOTE]
> You do not have to disable `useOmnisharp` as C# Dev Kit will ignore it if `preferCSharpExtension` is not set.

## Reload the window

Press `F1`, select `Developer: Reload Window` and select it. VS Code will reload itself and restart its extensions.

## Validation

You can verify that the **Uno Platform** extension is working by looking at the **Uno Platform** logs inside the **Output** pane by using `Ctrl` + `Shift` + `U` (`Shift` + `⌘` + `,` on a Mac). After reloading the window you should see a line with `[Info] Running in Dev Kit mode` inside the logs.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-vscode-omnisharp.md

---
uid: Uno.GetStarted.vscode.OmniSharp
---

# How to switch to OmniSharp Mode

## Enable OmniSharp mode

* Open the VS Code Settings using `Ctrl` + `,` (or `⌘` + `,` on a Mac)
* Search for `useOmnisharp`
    ![useOmnisharp](Assets/quick-start/vs-code-useOmniSharp.png)
* Enable it (checkbox)
* Search for `preferCSharpExtension`
    ![preferCSharpExtension](Assets/quick-start/vs-code-preferCSharpExtension.png)
* Enable it (checkbox)

## Reload the window

Press `F1` and select `Developer: Reload Window`. VS Code will reload itself and restart its extensions.

## Validation

You can verify that the **Uno Platform** extension is working by looking at the **Uno Platform** logs inside the **Output** pane by using `Ctrl` + `Shift` + `U` (`Shift` + `⌘` + `,` on a Mac). After reloading the window you should see a line with `[Info] Running in OmniSharp mode` inside the logs.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-vscode.md

---
uid: Uno.GetStarted.vscode
---

# Get Started on VS Code

This guide will walk you through the setup process for building apps with Uno Platform under Windows, Linux, or macOS.

See these sections for information about using Uno Platform with:

- [Codespaces](features/working-with-codespaces.md)
- [Ona](features/working-with-gitpod.md)

## Prerequisites

- [**Visual Studio Code**](https://code.visualstudio.com/)
- The [Uno Platform Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=unoplatform.vscode) Extension
- For Linux, install [OpenJDK 17](https://learn.microsoft.com/java/openjdk/install#install-on-ubuntu) for Android development.

## Check your environment

[!include[getting-help](includes/use-uno-check-inline-noheader.md)]

## Configure VS Code

If you are new to VS Code or to developing C# applications with VS Code take the time to follow the next steps.

1. Open VS Code
1. If this is not a new installation, then try to update it. Press `F1` and type `Code: Check for Updates...` and select it. A notification will tell you if an update is available.
1. Configure VS Code to start from the command-line using the `code` command. This can be configured by following [these instructions](https://code.visualstudio.com/docs/editor/command-line#_launching-from-command-line).
1. Install the **Uno Platform** extension. Press `F1` and type `Extensions: Install Extensions`, search the marketplace for **Uno Platform** and click the **Install** button.

> [!NOTE]
> The Uno Platform extension provides all the tooling needed to enable AI agents from Visual Studio, VS Code, Claude Code, GitHub Copilot CLI, Codex, and more.
>
> **Uno MCP** provides structured, semantic access to Uno Platform’s complete knowledge base—covering documentation, APIs, and best practices—empowering AI agents and developers with the intelligence they need to build better experiences. Meanwhile, **App MCP** brings intelligent automation to life by enabling AI agents to interact directly with live Uno Platform applications, creating a seamless bridge between design, development, and execution.
>
> Uno Platform's MCP tools are available when you [sign in to your Uno Platform account](xref:Uno.GetStarted.Licensing). For more information, see [Using the Uno Platform MCPs](xref:Uno.Features.Uno.MCPs).

## Platform-specific setup

You may need to follow additional directions, depending on your development environment.

### Android & iOS

For assistance configuring Android or iOS emulators, see the [Android & iOS emulator troubleshooting guide](xref:Uno.UI.CommonIssues.MobileDebugging).

### Linux

[!include[linux-setup](includes/additional-linux-setup-inline.md)]

## OmniSharp Legacy Mode

Starting **Uno Platform extension** version 0.12, running in VS Code automatically uses the [C# Dev Kit extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) `ms-dotnettools.csdevkit`.

If you are using Ona, any [Open VSX environment](https://open-vsx.org) or earlier versions of the Uno Platform extension, you will be automatically using the [C# extension](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csharp) `ms-dotnettools.csharp` with OmniSharp enabled.

To switch between C# Dev Kit and OmniSharp:

- [Switch to C# Dev Kit Mode](xref:Uno.GetStarted.vscode.DevKit)
- [Switch to OmniSharp Mode](xref:Uno.GetStarted.vscode.OmniSharp)

---

## Next Steps

You're all set to create your [first Uno Platform app](xref:Uno.GettingStarted.CreateAnApp.VSCode)!

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started-wizard.md

---
uid: Uno.GetStarted.Wizard
---

<!-- TITLE SECTION -->
<div style="display: flex; justify-content: center; align-items: center; text-align: center;">
  <h1>Welcome to Uno Platform! Important Next Steps</h1>
</div>

<!-- COUNTER - HOT DESIGN TUTORIAL - SECTION -->
<p style="text-align: center;">
  Create a simple cross-platform Counter application (Time to complete &lt; 5 min):
</p>

<!-- markdownlint-disable MD001 -->

<!-- Centered first item -->
<div style="display: flex; justify-content: center; align-items: center;">
<div class="col-md-6 col-xs-12">
<a href="studio/Hot Design/hot-design-getstarted-counter-tutorial.md">
<div class="alert alert-info alert-hover">

#### Hot Design®

Use Hot Design®, Uno Platform's visual designer, to design and develop the app.

</div>
</a>
</div>
</div>

<p align="center">
  <img src="Assets/getting-started-hot-design.png" alt="Welcome-Hot Design-Counter" style="width:auto; max-width:90%; height:auto;" />
</p>

<br/>

<!-- COUNTER - OTHER VARIANTS TUTORIALS - SECTION -->

<p style="text-align: center;">
    Prefer to start from code? Choose one of the 4 variants of the Counter tutorial, combining markup language (XAML or C# Markup) and presentation framework (MVVM or MVUX).
</p>

<br/>

<div class="row">

<div class="col-md-6 col-xs-12">
<a href="getting-started/counterapp/get-started-counter-xaml-mvux.md">
<div class="alert alert-info alert-hover">

#### XAML + MVUX

Use XAML for layout and MVUX for state management

</div>
</a>
</div>

<div class="col-md-6 col-xs-12">
<a href="getting-started/counterapp/get-started-counter-xaml-mvvm.md">
<div class="alert alert-info alert-hover">

#### XAML + MVVM

Use XAML for layout and MVVM for state management

</div>
</a>
</div>

<div class="col-md-6 col-xs-12">
<a href="getting-started/counterapp/get-started-counter-csharp-mvux.md">
<div class="alert alert-info alert-hover">

#### C# Markup + MVUX

Use C# Markup for layout and MVUX for state management

</div>
</a>
</div>

<div class="col-md-6 col-xs-12">
<a href="getting-started/counterapp/get-started-counter-csharp-mvvm.md">
<div class="alert alert-info alert-hover">

#### C# Markup + MVVM

Use C# Markup for layout and MVVM for state management

</div>
</a>
</div>

</div>

<br/>

<!-- GETTING HELP SECTION -->

[!include[getting-help](includes/getting-help.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/get-started.md

---
uid: Uno.GetStarted
---

## Quick Start

1. Install and run <a href="https://aka.platform.uno/uno-check#install-and-run-uno-check" target="_blank">Uno.Check</a> to set up all the required pre-requisites
2. Download the Uno Platform extension for your IDE:

   <!-- markdownlint-disable MD001 MD009 -->

   <div class="row">

   <!-- Visual Studio -->
   <div class="col-md-4 col-xs-12 ">
   <a href="https://aka.platform.uno/vs-extension-marketplace" target="_blank">
   <div class="alert alert-info alert-hover">

   #### Visual Studio 2022/2026

   Get the VSIX from the marketplace
   </div>
   </a>
   </div>

   <!-- Code -->
   <div class="col-md-4 col-xs-12 ">
   <a href="https://aka.platform.uno/vscode-extension-marketplace" target="_blank">
   <div class="alert alert-info alert-hover">

   #### Visual Studio Code

   Install the VSIX from the marketplace
   </div>
   </a>
   </div>

   <!-- Rider -->
   <div class="col-md-4 col-xs-12 ">
   <a href="https://aka.platform.uno/rider-extension-marketplace" target="_blank">
   <div class="alert alert-info alert-hover">

   #### JetBrains Rider

   Get the extension from the marketplace
   </div>
   </a>
   </div>

   </div> <!-- row -->

## Get Started

Uno Platform allows you to create single-codebase, cross-platform applications that run on iOS, Android, Web, macOS, Linux and Windows. You'll be creating cross-platform .NET applications with XAML and/or C# in no time.

The following sections will guide you through your development environment (including AI agents), a simple Hello World app, and more advanced tutorials.

To set up your development environment, first select the operating system you're developing on.

**I am developing on...**

# [**Windows**](#tab/windows)

**Choose the IDE or Agent you want to use:**

- [Visual Studio 2022/2026 with Copilot](xref:Uno.GetStarted.vs2022)
- [VS Code with Copilot, Codespaces and Ona](xref:Uno.GetStarted.vscode)
- [Rider](xref:Uno.GetStarted.Rider)
- [Claude Code](xref:Uno.GetStarted.AI.Claude)
- [Codex CLI](xref:Uno.GetStarted.AI.Codex)
- [GitHub Copilot CLI](xref:Uno.GetStarted.AI.CopilotCLI)
- [Cursor](xref:Uno.GetStarted.AI.Cursor)
- [Google Antigravity](xref:Uno.GetStarted.AI.GoogleAntigravity)

To help you choose the appropriate IDE or Agent, the following table shows the compatibility of different development environments with various target platforms:

|                                    | [**Visual Studio**](xref:Uno.GetStarted.vs2022) | [**VS Code**](xref:Uno.GetStarted.vscode) | [**Codespaces**](xref:Uno.GetStarted.vscode) | [**Rider**](xref:Uno.GetStarted.Rider) | [**Claude Code**](xref:Uno.GetStarted.AI.Claude) | [**Codex**](xref:Uno.GetStarted.AI.Codex) | [**GitHub Copilot CLI**](xref:Uno.GetStarted.AI.CopilotCLI) | [**Cursor**](xref:Uno.GetStarted.AI.Cursor) | [**Google Antigravity**](xref:Uno.GetStarted.AI.GoogleAntigravity) |
|------------------------------------|-------------------------------------------------|--------------------------------------------|-------------------------------------------------------|--------------------------------------------------|--------------------------------------------------|-------------------------------------------|-------------------------------------------------------------|---------------------------------------------|--------------------------------------------------------------|
| Desktop (Skia)¹                    | ✔️                                              | ✔️                                         | ✔️                                                   | ✔️                                              | ✔️                                               | ✔️                                        | ✔️                                                         | ✔️                                          | ✔️                                                       |
| Android                            | ✔️                                              | ✔️⁵                                         | ❌                                                   | ✔️                                              | ⏳⁵                                              | ⏳⁵                                       | ⏳⁵                                                        | ⏳⁵                                         | ⏳⁵                                                    |
| iOS                                | ✔️²                                             | ✔️³                                        | ❌                                                   | ❌                                              | ❌                                               | ❌                                        | ❌                                                         | ❌                                          | ❌                                                       |
| Web (WebAssembly)                  | ✔️                                              | ✔️                                         | ✔️                                                   | ✔️⁴                                             | ✔️                                               | ✔️                                        | ✔️                                                         | ✔️                                          | ✔️                                                       |
| WinAppSDK                          | ✔️                                              | ⏳⁵                                         | ❌                                                   | ✔️                                              | ⏳⁵                                              | ⏳⁵                                       | ⏳⁵                                                        | ⏳⁵                                         | ⏳⁵                                                    |

**Notes:**

1. Desktop binaries do run on Windows, Linux, and macOS
2. You will need to be connected to a Mac to run and debug iOS apps from Windows
3. You will need to be connected to a Mac using [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)
4. [WebAssembly debugging](https://youtrack.jetbrains.com/issue/RIDER-103346/Uno-Platform-for-WebAssembly-debugger-support) is not yet supported
5. Agent support is coming soon

# [**macOS**](#tab/macos)

You can use **Visual Studio Code** or **JetBrains Rider**, to build Uno Platform applications on macOS. See the support matrix below for supported target platforms.

**Choose the IDE or Agent you want to use:**

- [VS Code with Copilot, Codespaces and Ona](xref:Uno.GetStarted.vscode)
- [Rider](xref:Uno.GetStarted.Rider)
- [Claude Code](xref:Uno.GetStarted.AI.Claude)
- [Codex CLI](xref:Uno.GetStarted.AI.Codex)
- [GitHub Copilot CLI](xref:Uno.GetStarted.AI.CopilotCLI)
- [Cursor](xref:Uno.GetStarted.AI.Cursor)
- [Google Antigravity](xref:Uno.GetStarted.AI.GoogleAntigravity)

To help you choose the appropriate IDE or Agent, the following table shows the compatibility of different development environments with various target platforms:

|                                    | [**VS Code**](xref:Uno.GetStarted.vscode) | [**Codespaces**](xref:Uno.GetStarted.vscode) | [**Rider**](xref:Uno.GetStarted.Rider) | [**Claude Code**](xref:Uno.GetStarted.AI.Claude) | [**Codex**](xref:Uno.GetStarted.AI.Codex) | [**GitHub Copilot CLI**](xref:Uno.GetStarted.AI.CopilotCLI) | [**Cursor**](xref:Uno.GetStarted.AI.Cursor) | [**Google Antigravity**](xref:Uno.GetStarted.AI.GoogleAntigravity) |
|------------------------------------|------------------------------------------|-------------------------------------------------------|--------------------------------------------------|--------------------------------------------------|-------------------------------------------|-------------------------------------------------------------|---------------------------------------------|--------------------------------------------------------------|
| Desktop (Skia)¹                    | ✔️                                       | ✔️                                                   | ✔️                                               | ✔️                                               | ✔️                                        | ✔️                                                         | ✔️                                          | ✔️                                                       |
| Android                            | ✔️²                                      | ❌                                                   | ✔️                                               | ⏳²                                              | ⏳²                                       | ⏳²                                                        | ⏳²                                         | ⏳²                                                    |
| iOS                                | ✔️                                       | ❌                                                   | ✔️                                               | ✔️                                               | ✔️                                        | ✔️                                                         | ✔️                                          | ✔️                                                       |
| Web (WebAssembly)                  | ✔️                                       | ✔️                                                   | ✔️                                               | ✔️                                               | ✔️                                        | ✔️                                                         | ✔️                                          | ✔️                                                       |
| WinAppSDK                          | ❌                                       | ❌                                                   | ❌                                               | ❌                                               | ❌                                        | ❌                                                         | ❌                                          | ❌                                                       |

**Notes:**

1. Desktop binaries do run on Windows, Linux, and macOS
2. Agent support is coming soon

The latest macOS release and Xcode version are required to develop with Uno Platform for iOS targets. If you have older Mac hardware that does not support the latest release of macOS, see the section for [Developing on older Mac hardware](xref:Uno.UI.CommonIssues.Ios#developing-on-older-mac-hardware).

# [**Linux**](#tab/linux)

 You can use either **JetBrains Rider** or **Visual Studio Code** to build Uno Platform applications on Linux. See the support matrix below for supported target platforms.

**Choose the IDE or Agent you want to use:**

- [Visual Studio Code with Copilot, Codespaces and Ona](xref:Uno.GetStarted.vscode)
- [Rider](xref:Uno.GetStarted.Rider)
- [Claude Code](xref:Uno.GetStarted.AI.Claude)
- [Codex CLI](xref:Uno.GetStarted.AI.Codex)
- [GitHub Copilot CLI](xref:Uno.GetStarted.AI.CopilotCLI)
- [Cursor](xref:Uno.GetStarted.AI.Cursor)
- [Google Antigravity](xref:Uno.GetStarted.AI.GoogleAntigravity)

To help you choose the appropriate IDE or Agent, the following table shows the compatibility of different development environments with various target platforms:

|                                    | [**VS Code**](xref:Uno.GetStarted.vscode) | [**Codespaces**](xref:Uno.GetStarted.vscode) | [**Rider**](xref:Uno.GetStarted.Rider) | [**Claude Code**](xref:Uno.GetStarted.AI.Claude) | [**Codex**](xref:Uno.GetStarted.AI.Codex) | [**GitHub Copilot CLI**](xref:Uno.GetStarted.AI.CopilotCLI) | [**Cursor**](xref:Uno.GetStarted.AI.Cursor) | [**Google Antigravity**](xref:Uno.GetStarted.AI.GoogleAntigravity) |
|------------------------------------|------------------------------------------|-------------------------------------------------------|--------------------------------------------------|--------------------------------------------------|-------------------------------------------|-------------------------------------------------------------|---------------------------------------------|--------------------------------------------------------------|
| Desktop (Skia)¹                    | ✔️                                        | ✔️                                                     | ✔️                                            | ✔️                                               | ✔️                                        | ✔️                                                         | ✔️                                          | ✔️                                                       |
| Web (WebAssembly)                  | ✔️                                        | ✔️                                                     | ✔️²                                           | ✔️                                               | ✔️                                        | ✔️                                                         | ✔️                                          | ✔️                                                       |
| Android                            | ✔️³                                       | ❌                                                     | ✔️                                            | ⏳³                                              | ⏳³                                       | ⏳³                                                        | ⏳³                                         | ⏳³                                                    |
| iOS                                | ❌                                        | ❌                                                     | ❌                                            | ❌                                               | ❌                                        | ❌                                                         | ❌                                          | ❌                                                       |
| WinAppSDK                          | ❌                                        | ❌                                                     | ❌                                            | ❌                                               | ❌                                        | ❌                                                         | ❌                                          | ❌                                                       |

**Notes:**

1. Desktop binaries do run on Windows, Linux, and macOS
2. [WebAssembly debugging](https://youtrack.jetbrains.com/issue/RIDER-103346/Uno-Platform-for-WebAssembly-debugger-support) is not yet supported
3. Agent support is coming soon

---

## Supported Agents Features

Choosing the right agent for your development depends on your needs and environments. The following table summarizes the features supported by various agents for Uno Platform development:

| Agent                | Version      | Tools | Prompts | Hot Reload | mcp.json      | Platforms | Comments |
|----------------------|--------------|-------|---------|------------|----------------|-----------|----------|
| VS 2022 Copilot      | 17.14.16     | ✅    | ❌     | ⏳¹        | ✅        | iOS, Android, Desktop, Web ||
| VS 2026 Copilot      | 18.0.0 Pre 1 | ✅    | ❌     | ⏳¹        | ✅         | iOS, Android, Desktop, Web ||
| VS Code Copilot      | 1.105.1      | ✅    | ✅     | ✅         | ✅       | iOS, Android, Desktop, Web ||
| GitHub Copilot CLI   | 0.0.349      | ✅    | ❌     | ✅         | ❌         | Desktop, Web | |
| Cursor               | 2.0.34       | ✅    | ✅     | ✅         | ✅        | Desktop, Web ||
| Google Antigravity   | Preview      | ✅    | ❌    | ✅         | ❌        | Desktop, Web | Requires `--force-roots-fallback` |
| Rider                | 2025.2       | ❌    | ❌     | ❌         | ❌         | ❌ |[Support coming soon](https://youtrack.jetbrains.com/issue/JUNIE-461/MCP-Remote-Server-Support)|
| Codex CLI            | 0.50.0       | ✅    | ❌     | ✅         | ❌      | Desktop, Web | [mcp.json](https://github.com/openai/codex/issues/2628)|
| Claude Code          | 2.0.25       | ✅    | ✅     | ✅         | ✅        | Desktop, Web | |

**Notes:**

1. VS Hot Reload support in agents is coming soon

## Questions

For questions about Uno Platform, refer to the [general FAQ](xref:Uno.Development.FAQ) or see the [troubleshooting section](xref:Uno.UI.CommonIssues) for common issues and their solutions.

## Next Steps

Choose the IDE or Agent to Learn more about:

- [Visual Studio](xref:Uno.GetStarted.vs2022)
- [VS Code, Codespaces and Ona](xref:Uno.GetStarted.vscode)
- [Rider](xref:Uno.GetStarted.Rider)
- [Claude Code](xref:Uno.GetStarted.AI.Claude)
- [Codex](xref:Uno.GetStarted.AI.Codex)
- [GitHub Copilot CLI](xref:Uno.GetStarted.AI.CopilotCLI)
- [Cursor](xref:Uno.GetStarted.AI.Cursor)
- [Google Antigravity](xref:Uno.GetStarted.AI.GoogleAntigravity)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/getting-started/getting-started-tests.md

---
uid: Uno.Authoring.Tests
---
# How-To: Creating an application with tests

This tutorial will guide you through the process of creating an [Uno application along with tests](xref:Uno.GettingStarted.UsingWizard#10-testing).

> [!NOTE]
> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted).
  
## 1. Exploring the Solution

The generated solution will contain:

* *MyProjectName* - for application logic, and other constructs like view models and services, as well as the pages, controls, and other views that make up the UI of the application.
* *MyProjectName.Tests* and *MyProjectName.UI.Tests* - for writing unit and UI tests respectively.

![The structure of the generated solution](Assets/ProjectStructure-Tests-min.png)

## 2. Running the Application

* Select a target from the drop-down as pictured below

    ![A screenshot of the generated targets](Assets/GeneratedTargets-min.png)

* Click the "play" button, or press F5 to start debugging. The project will be compiled and deployed based on the target platform. For more detailed instructions specific to each platform, refer to the [Debug the App](xref:Uno.GettingStarted.CreateAnApp.VS2022#debug-the-app) documentation.

## 3. Running the Unit Tests

* In the Solution Explorer within Visual Studio, navigate to the *Tests* folder, and right-click on `MyProjectName.Tests`.

* From the context menu that appears, select *Run Tests*.

   The application will be compiled and the test cases will run.

> [!TIP]
> If the 'Run Tests' menu item doesn't exist, you need to Rebuild the solution to get Visual Studio to detect the available tests.

## 4. Running the UI tests

UI Tests are using the [Uno.UITest nuget package](xref:Uno.UITest.GetStarted), see the documentation for more information on how to create more UI Tests.

* As demonstrated on step 2, select the **MyProjectName (WebAssembly)** target from the drop-down.

* Press Ctrl + F5 to start the WASM project without debugging.

* Once the application is compiled, it will launch inside your default browser. Take note of the URL which should look something like this: https://localhost:5000/Main

* In the Solution Explorer, go to the *Tests* folder, open the `MyProjectName.UI.Tests` project, and locate the Constants.cs file.

* Open *Constants.cs* and update the WebAssemblyDefaultUri constant.

    It should appear similar to this:

    ```cs
    public readonly static string WebAssemblyDefaultUri = "https://localhost:5000/";
    ```

* Go back to the Solution Explorer, navigate to the *Tests* folder, right-click on the `MyProjectName.UI.Tests` project, and then select *Run Tests*.

    ![Test Explorer in VS](Assets/TestExplorer-min.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.toolkit.ui/refs/heads/main/doc/getting-started.md

---
uid: Toolkit.GettingStarted
---
# Getting Started with Uno Toolkit

## Uno Toolkit Library

The Uno Toolkit library is available as NuGet packages that can be added to any new or existing Uno solution.

This article is a guide for installing the base Uno Toolkit library, additional steps are needed when installing the Toolkit support libraries for Uno Material and Uno Cupertino. Most controls within the base Uno Toolkit library are not designed to be used without an underlying design system installed. Refer to the following guides for Material/Cupertino support:

- [Getting Started with Material for Toolkit](xref:Toolkit.GettingStarted.Material)
- [Getting Started with Cupertino for Toolkit](xref:Toolkit.GettingStarted.Cupertino)

> [!Video https://www.youtube-nocookie.com/embed/sDmyWJaQp4Q]

### Installation

### Creating a new project with Uno Toolkit

#### [**Wizard**](#tab/wizard)

1. Follow the steps in the [Getting Started with Visual Studio](xref:Uno.GettingStarted.CreateAnApp.VS2022#create-the-app) instructions to launch the Uno Platform Template Wizard.
2. Select `Toolkit` under the `Features` section.

    ![Toolkit selection in the Uno Platform Template Wizard](assets/toolkit-wizard.png)

#### [**CLI**](#tab/cli)

1. Install the [`dotnet new` CLI templates](xref:Uno.GetStarted.dotnet-new) with:

    ```bash
    dotnet new install Uno.Templates
    ```

2. Create a new application with:

    ```bash
    dotnet new unoapp -o ToolkitApp -toolkit
    ```

---

### Installing Uno Toolkit in an existing project

Depending on the type of project template that the Uno Platform application was created with, follow the instructions below to install Uno Toolkit.

#### [**Single Project Template**](#tab/singleproj)

1. Edit your project file (`PROJECT_NAME.csproj`) and add `Toolkit` to the list of `UnoFeatures`:

    ```xml
    <UnoFeatures>Toolkit</UnoFeatures>
    ```

2. Initialize `ToolkitResources` in the `App.xaml`:

    ```xml
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>

                <!-- Code omitted of brevity -->

                <ToolkitResources xmlns="using:Uno.Toolkit.UI" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
    ```

#### [**Multi-Head Project Template (Legacy)**](#tab/multihead)

1. In the Solution Explorer panel, right-click on your app's **App Code Library** project (`PROJECT_NAME.csproj`) and select `Manage NuGet Packages...`
2. Install the [`Uno.Toolkit.WinUI`](https://www.nuget.org/packages/Uno.Toolkit.WinUI)
3. Add the `ToolkitResources` to `AppResources.xaml`:

    ```xml
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>

            <ToolkitResources xmlns="using:Uno.Toolkit.UI" />

        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
    ```

#### [**Shared Project (.shproj) Template (Legacy)**](#tab/shproj)

1. In the Solution Explorer panel, right-click on your solution name and select `Manage NuGet Packages for Solution ...`. Choose either:
     - The [`Uno.Toolkit.UI`](https://www.nuget.org/packages/Uno.Toolkit.UI/) package when targetting Xamarin/UWP
     - The [`Uno.Toolkit.WinUI`](https://www.nuget.org/packages/Uno.Toolkit.WinUI) package when targetting net6.0+/WinUI

2. Select the following projects for installation:
    - `PROJECT_NAME.Wasm.csproj`
    - `PROJECT_NAME.Mobile.csproj` (or `PROJECT_NAME.iOS.csproj`, `PROJECT_NAME.Droid.csproj`, and `PROJECT_NAME.macOS.csproj` if you have an existing project)
    - `PROJECT_NAME.Skia.Gtk.csproj`
    - `PROJECT_NAME.Skia.WPF.csproj`
    - `PROJECT_NAME.Windows.csproj` (or `PROJECT_NAME.UWP.csproj` for existing projects)
3. Add the following resources inside `App.xaml`:

    ```xml
    <Application ...>
        <Application.Resources>
            <ResourceDictionary>
                <ResourceDictionary.MergedDictionaries>

                    <!-- Load WinUI resources -->
                    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />

                    <ToolkitResources xmlns="using:Uno.Toolkit.UI" />

                    <!-- Load custom application resources -->
                    <!-- ... -->

                </ResourceDictionary.MergedDictionaries>
            </ResourceDictionary>
        </Application.Resources>
    </Application>
    ```

---

> [!NOTE]
> If you are using the [Uno.Toolkit.WinUI.Material](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material) or [Uno.Toolkit.WinUI.Cupertino](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Cupertino) NuGet packages, follow the steps in the [Getting Started with Material for Toolkit](xref:Toolkit.GettingStarted.Material) or [Getting Started with Cupertino for Toolkit](xref:Toolkit.GettingStarted.Cupertino) guides instead as they already include the base Uno Toolkit library.

## Using C# Markup

The Uno Toolkit library also has support for C# Markup through a [Uno.Toolkit.WinUI.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Markup) NuGet Package.

To get started with Uno Toolkit in your C# Markup application, add the `Uno.Toolkit.WinUI.Markup` NuGet package to your application project and add the following code to your `App.cs`:

```csharp
using Uno.Toolkit.UI.Markup;

this.Build(r => r.UseToolkit());
```

> [!NOTE]
> If you are using the [Uno.Toolkit.WinUI.Material.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material.Markup) NuGet package, follow the steps in the [Using C# Markup for the Material Toolkit](xref:Toolkit.GettingStarted.Material#using-c-markup) guide instead as it includes the base Uno Toolkit Markup library.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/git-conventional-commits.md

---
uid: Uno.Contributing.ConventionalCommits
---

# Conventional Commits

Uno uses the [Conventional Commits format](https://www.conventionalcommits.org/en/v1.0.0/#summary) for all changes to the source repository. If you submit a PR, the CI build won't pass until all commits satisfy the format. This format embeds semantic information in each commit that's used to automatically generate release notes.

The Conventional Commits format is as follows:

```text
<type>([optional scope]): <description>

[optional body]

[optional footer(s)]
```

## Type

Only certain _types_ are permitted, with the most common being:

- `fix:` a commit that fixes a bug in Uno.
- `feat:` a commit that adds new functionality to Uno.
- `docs:` a commit that adds or improves Uno's documentation.
- `test:` a commit that adds unit tests.
- `perf:` a commit that improves performance, without functional changes.
- `chore:` a catch-all type for any other commits. For instance, if you're implementing a single feature and it makes sense to divide the work into multiple commits, you should mark one commit as `feat` and the rest as `chore`.

## Scope

 The _scope_ optionally provides extra context. If you're fixing a `ListView` bug, for example, you might use `fix(listview)`.

 One scope with special meaning is `reg`, short for regression. This is used for fixes for bugs that weren't present in the most recent stable release.

## Breaking changes

Breaking changes are indicated by putting `BREAKING CHANGE:` at the start of the message body, for any commit type. Optionally they may be emphasized by appending a `!` after the type and scope. The message body should provide appropriate guidance for developers affected by the breaking change.

## Fixing up commits

If you already made commits and they don't meet the Conventional Commits specification, you have a couple of options:

- if there's only one commit to redo, the easiest option is to use `git commit --amend` with no staged changes, which will allow you to edit the commit message.
- if you have multiple commits to reformat, you'll probably need to do an [interactive rebase](https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History) and use the `reword` option.

## Examples

### A commit fixing a bug

```text
fix(webview): Fixed video display in WebView on Android: the control was forced to use software rendering.

This feature is now opt-in instead.
```

### A commit adding a new feature

```text
feat(imageBrush): [iOS][macOS] Add support of WriteableBitmap
```

### A commit introducing a breaking change

```text
fix(resourcedictionary)!: Make ResourceDictionary.Lookup() internal, use correct lookup

BREAKING CHANGE: This method isn't part of the public .NET contract on WinUI. Use item indexing or TryGetValue() instead.
```

### A commit with no special meaning

```text
chore: Fix XAML parsing sample
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/gyrometer.md

---
uid: Uno.Features.Gyrometer
---

# Gyrometer

> [!TIP]
> This article covers Uno-specific information for Gyrometer. For a full description of the feature and instructions on using it, see [Gyrometer Class](https://learn.microsoft.com/uwp/api/windows.devices.sensors.gyrometer).

* The `Windows.Devices.Sensors.Gyrometer` class allows measuring angular velocity applied on the device.

## Supported features

| Feature          | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `GetDefault`     | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `ReadingChanged` | ✔       | ✔       | ✔   | ✔          | ✖     | ✖            | ✖            |
| `ReportInterval` | ✔       | ✔       | ✔   | ✔          | ✖     | ✖            | ✖            |

## Using Gyrometer with Uno

* The `GetDefault` method is available on all targets and will return `null` on those which do not support `Gyrometer` or devices that do not have such a sensor.
* Ensure to unsubscribe from the `ReadingChanged` event when you no longer need the readings, so that the sensor is no longer active to avoid unnecessary battery consumption.
* `ReportInterval` property on WASM is currently not supported directly. Uno uses an approximation in the form of raising the `ReadingChanged` event, only when enough time has passed since the last report. The event is raised a bit more often to make sure the gap caused by the filter is not too large, but this is in line with the behavior of Windows' `Gyrometer`.

## Example

### Capturing sensor readings

```csharp
var gyrometer = Gyrometer.GetDefault();
gyrometer.ReadingChanged += Gyrometer_ReadingChanged;

private async void Gyrometer_ReadingChanged(Gyrometer sender, GyrometerReadingChangedEventArgs args)
{
    // If you want to update the UI in some way, ensure the Dispatcher is used,
    // as the ReadingChanged event handler does not run on the UI thread.
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        AngularVelocityX = args.Reading.AngularVelocityX;
        AngularVelocityY = args.Reading.AngularVelocityY;
        AngularVelocityZ = args.Reading.AngularVelocityZ;
        Timestamp = args.Reading.Timestamp.ToString("R");
    });
}
```

### Unsubscribing from the readings

```csharp
gyrometer.ReadingChanged -= Gyrometer_ReadingChanged;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/hardware-back-button.md

---
uid: Uno.Features.HardwareBackButton
---

# Handling hardware back button

Some devices provide a hardware back button to handle navigation within applications. `SystemNavigationManager` provides this functionality for Uno Platform applications.

## Listening to hardware back button

The `BackRequested` event of the `SystemNavigationManager` is triggered whenever the user presses the hardware back button. To subscribe to it, first get an instance of `SystemNavigationManager` via the `GetForCurrentView` method:

```csharp
var manager = SystemNavigationManager.GetForCurrentView();
manager.BackRequested += OnBackRequested;
```

The event handler should check whether the application can handle the back button press (e.g. if it is possible to navigate back within the app's UI), and in such case perform the in-app navigation and mark the event args as `Handled`:

```csharp
private void OnBackRequested(object sender, BackRequestedEventArgs e)
{
    if (this.Frame.CanGoBack)
    {
        this.Frame.GoBack();
        e.Handled = true; // Indicates that the back request has been handled
    }
}
```

> [!NOTE]
> On Android 16+ (API level 36+), the behavior differs. See the [Android 16+ behavior](#android-16-behavior) section below for details.

When `Handled` is set to `true`, the OS will not continue processing the request. If not set or set to `false`, the OS will navigate away from the application.

Make sure to unsubscribe from the event when no longer needed.

## Android 16+ behavior

Starting with Android 16 (API level 36), the back navigation behavior has changed due to the [predictive back gesture](https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture) feature. On these versions, the `Handled` property is ignored, and the subscription state of the `BackRequested` event determines whether the app handles back navigation:

- **When subscribed**: The app is assumed to handle back navigation. Back button presses are consumed by the app.
- **When unsubscribed**: The system handles back navigation (e.g., exits the app or navigates back in the task stack).

### Best practices for Android 16+

To ensure proper behavior on Android 16+, subscribe to `BackRequested` only when your app can handle back navigation, and unsubscribe when it cannot. A common pattern is to subscribe on `Loaded` and unsubscribe on `Unloaded`:

```csharp
public MyPage()
{
    InitializeComponent();

    Loaded += OnLoaded;
    Unloaded += OnUnloaded;
}

private void OnLoaded(object sender, RoutedEventArgs e)
{
    SystemNavigationManager.GetForCurrentView().BackRequested += OnBackRequested;
}

private void OnUnloaded(object sender, RoutedEventArgs e)
{
    SystemNavigationManager.GetForCurrentView().BackRequested -= OnBackRequested;
}

private void OnBackRequested(object sender, BackRequestedEventArgs e)
{
    if (this.Frame.CanGoBack)
    {
        this.Frame.GoBack();
        // The subscription itself indicates the app handles back navigation.
        // So setting e.Handled has no effect and is ignored.
    }
}
```

> [!NOTE]
> On Android versions prior to 16, the `Handled` property continues to work as expected. Setting it to `true` prevents the OS from processing the back request, while `false` allows the OS to handle it.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/studio/Hot Reload/hot-reload-overview.md

---
uid: Uno.Platform.Studio.HotReload.Overview
---

[!include[working-with-xaml-hot-reload](../../features/working-with-xaml-hot-reload.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/hotswap-app-language.md

---
uid: Uno.Tutorials.ChangeAppLanguage
---

# How to change app language at runtime

This guide will walk you through the necessary steps for changing app language at runtime.

> [!TIP]
> The complete source code that goes along with this guide is available in the [unoplatform/Uno.Samples](https://github.com/unoplatform/Uno.Samples) GitHub repository - [RuntimeCultureSwitching sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/LocalizationSamples/RuntimeCultureSwitching)

## Prerequisites

Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted).

## Steps to change application language at runtime

> [!NOTE]
> This guide is an extension of ["How to use localization"](localization.md), and will build on top the sample from that guide.
> Make sure you have completed the previous guide or downloaded the [full localization sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/LocalizationSamples/Localization), before continuing.

1. Add two new pages to the `Localization.Shared` project by:
    Right-click on `Localization.Shared` > Add > New Item ... > Visual C# > XAML > Blank Page
    And, name them `Page1` and `LanguageSettings`
1. Add some content to the two new pages:

    * `Page1.xaml`:

        ```xml
        <Page x:Class="UnoLocalization.Page1"
              xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
              xmlns:toolkit="using:Uno.UI.Toolkit">

            <StackPanel toolkit:VisibleBoundsPadding.PaddingMask="Top">
                <TextBlock x:Uid="Page1_Title" Text="Page one" FontSize="30" />

                <Button x:Uid="Page1_GoBack" Content="Go back" Click="GoBack" />
            </StackPanel>
        </Page>
        ```

    * `Page1.xaml.cs`:

        ```csharp
        private void GoBack(object sender, RoutedEventArgs e) => Frame.GoBack();
        ```

    * `LanguageSettings.xaml`:

        ```xml
        <Page x:Class="UnoLocalization.LanguageSettings"
              xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
              xmlns:toolkit="using:Uno.UI.Toolkit">

            <StackPanel toolkit:VisibleBoundsPadding.PaddingMask="Top">
                <TextBlock x:Uid="LanguageSettings_Title" Text="Language Settings" FontSize="30" />

                <Button Content="English" Click="SetAppLanguage" Tag="en" />
                <Button Content="Français" Click="SetAppLanguage" Tag="fr" />

                <Button x:Uid="LanguageSettings_GoBack"
                        Content="Go back"
                        Click="GoBack"
                        Margin="0,12,0,0"/>
            </StackPanel>
        </Page>
        ```

    * `LanguageSettings.xaml.cs`:

        ```csharp
        private void SetAppLanguage(object sender, RoutedEventArgs e)
        {
            if ((sender as Button)?.Tag is string tag)
            {
                // Change the app language
                Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride = tag;

                // Clear the back-navigation stack, and send the user to MainPage
                // This is done because any loaded pages (MainPage(in back-stack) and LanguageSettings (current active page))
                // will stay in the previous language until reloaded.
                Frame.BackStack.Clear();
                Frame.Navigate(typeof(MainPage));
            }
        }

        private void GoBack(object sender, RoutedEventArgs e) => Frame.GoBack();
        ```

1. Add two new buttons to `MainPage` for navigation:
    * `MainPage.xaml`:

        ```xml
        <StackPanel toolkit:VisibleBoundsPadding.PaddingMask="Top">
            <TextBlock x:Uid="MainPage_IntroText" Text="Hello, world!" Margin="20" FontSize="30" />
            <TextBlock x:Name="CodeBehindText" Text="This text will be replaced" />

            <Button x:Uid="MainPage_GotoNextPage" Content="Next Page" Click="GotoNextPage" />
            <Button x:Uid="MainPage_GotoLanguageSettings" Content="Language Settings" Click="GotoLanguageSettings" />
        </StackPanel>
        ```

    * `MainPage.xaml.cs`:

        ```csharp
        private void GotoNextPage(object sender, RoutedEventArgs e) => Frame.Navigate(typeof(Page1));
        private void GotoLanguageSettings(object sender, RoutedEventArgs e) => Frame.Navigate(typeof(LanguageSettings));
        ```

1. Add a new folder `fr` under the Strings folder by: Right-click on String > Add > New Folder

1. Add a new resource file `Resources.resw` under the `fr` folder by: Right-click on `fr` > Add > New Item ... > Visual C# > Xaml > Resources File

1. Add the localization strings for the new elements:
    Open both `Strings\en\Resources.resw` and `Strings\fr\Resources.resw`, and add these:

    |Name|Value in `en\Resources.resw`|Value in `fr\Resources.resw`|
    |-|-|-|
    |MainPage_GotoNextPage.Content|`Next Page`|`Page suivante`|
    |MainPage_GotoLanguageSettings.Content|`Language Settings`|`Paramètres de langue`|
    |Page1_Title.Text|`Page in english`|`Page en français`|
    |Page1_GoBack.Content|`Go back`|`Retourner`|
    |LanguageSettings_Title.Text|`Language Settings`|`Paramètres de langue`|
    |LanguageSettings_GoBack.Content|`Go back`|`Retourner`|

## Get the complete code

See the completed sample on GitHub: [RuntimeCultureSwitching](https://github.com/unoplatform/Uno.Samples/tree/master/UI/LocalizationSamples/RuntimeCultureSwitching)

## Additional Resources

* [Globalization and localization](https://learn.microsoft.com/windows/uwp/design/globalizing/globalizing-portal)

---

[!include[getting-help](../includes/getting-help.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/how-to-add-platforms-existing-project.md

---
uid: Uno.Guides.AddAdditionalPlatforms
---

# Adding Platforms to an Existing Project

If you have an existing Uno Platform project, and you have not selected all the platforms you need when creating the project, this guide will show you how to add new ones.

Considering that your project is called `MyProject`, and you want to add the `desktop` target support:

1. In a separate temporary folder, create a new project using the **Visual Studio** or `dotnet new` templates, using `MyProject` for its name.
1. Unselect all platforms except `Desktop` in the platforms selection dialog.
1. Make sure to select the template preset and features.
1. Once the project has been created, navigate to the new folder `MyProject`.
1. Copy `Platforms/Desktop` folder to the existing project structure, at the same level as the other platform folders.
1. In your `.csproj`, add the `net9.0-desktop` target framework to the `TargetFrameworks` property.
1. Save your solution.

Your new platform project is now ready to be compiled.

You can repeat a similar process for `net9.0-ios`, `net9.0-android`, `net9.0-browserwasm`, and `net9.0-windows10.0.xxxxx`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/how-to-add-uno-to-an-existing-solution.md

---
uid: Uno.Guides.AddUnoToExistingSolution
---

# Adding an Uno Platform Project to an existing solution

As of Uno 6.0, the Uno Platform solution templates [do not support being included in an existing solution](https://github.com/unoplatform/uno.templates/issues/641). This known issue can still be worked around by a few manual steps.

In order to add an Uno Platform project to an existing solution:

1. In a separate temporary folder, create a new project using the **Visual Studio** or `dotnet new` templates, using `MyProject` for its name.
1. Copy the generated individual project folders to your solution folder (`MyProject`, `MyProject.Server`, etc...)
1. For the `global.json` file:

    - If your solution already contains a `global.json` file, merge the `msbuild-sdks` section:

      ```json
      "msbuild-sdks": {
        "Uno.Sdk": "6.0.146"
      },
      ```

    - If not, copy the entire `global.json` and place it next to your existing sln.

1. For the `Directory.Build.Props` file, Uno Platform templates use [NuGet Central Package Management](https://learn.microsoft.com/en-us/nuget/consume-packages/central-package-management) (CPM) by default, which might conflict with your existing solution.

    1. If your solution uses CPM, you'll only need to copy the `ImplicitUsings` and `Nullable` properties in your `MyProject.csproj`
    1. If your solution does not use CPM:

        - If you want to start using CPM, you can migrate to use it entirely and copy the contents of Uno's `Directory.Packages.props` to your own version of that file.
        - If you don't want to use CPM, search for each `PackageReference` in each of Uno's projects and add the versions found in Uno's `Directory.Packages.props`, if any, as it depends on the options chosen when creating the projects.

1. The other files `.vsconfig`, `.editorconfig` and `.gitignore` are completely optional and can be copied to your solution as needed.
1. Finally, manually add the projects to your solution using right-click on the root, click **Add**, then **Existing Project**

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/how-to-create-control-libraries.md

---
uid: Guide.HowTo.Create-Control-Library
---
# How to Create Control Libraries

Uno Platform, like WinUI/WinAppSDK, supports Control Libraries. Control Libraries are a way to reuse UI components across multiple projects, either inside the solution or by using NuGet to distribute to other projects.

Creating such a library will make UI Controls compatible with all Uno Platform targets as well as WinUI.

> [!NOTE]
> Control libraries are different from "normal" libraries as they reference WinAppSDK, Uno.WinUI or Uno.UI. Those libraries are special because they have explicit dependencies on platform-specific features. "Normal" libraries (e.g. Newtonsoft.Json) do not need any special treatment to work with Uno.

You can find the [full ControlLibrary sample code](https://github.com/unoplatform/Uno.Samples/blob/master/UI/ControlLibrary) for this how-to in our samples repository.

## Create a Control Library

1. In your solution, create a new **Uno Platform Library**, name it `XamlControlLibrary`
1. In your app's existing Class Library project, add a reference to your new library.

## Create the Control

1. Right-click on the project library, then **Add**, **New Item**
1. In the **Uno Platform** section of **C# Items**, select **Templated Control**, name it `MyTemplatedControl`
1. Right click on the project library again, then **Add**, **New Folder**, call it `Themes` (case sentitive)
1. Right click on the `Themes` folder, then **Add**, **New Item**
1. In the **Uno Platform** section of **C# Items**, select **Resource Dictionary**, name it `Generic.xaml` (case sensitive)
1. In the new created file, paste the following:

   ```xml
   <ResourceDictionary
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:XamlControlLibrary">

        <Style TargetType="local:MyTemplatedControl">
            <Setter Property="Template">
                <Setter.Value>
                    <ControlTemplate TargetType="local:MyTemplatedControl">
                        <Grid>
                            <TextBlock Text="My templated control !" />
                        </Grid>
                    </ControlTemplate>
                </Setter.Value>
            </Setter>
        </Style>

    </ResourceDictionary>
   ```

## Use the control

1. In your application's `MainPage.xaml`, add the following namespace `xmlns:myControlLib="using:XamlControlLibrary"` in the `Page` element
2. Add the following code somewhere in the page:

   ```xml
   <myControlLib:MyTemplatedControl />
   ```

## Moving the control style in a separate resource dictionary

Placing XAML styles in different files can be useful to make the XAML more readable and easier to browse.

Considering the example above:

1. Right click on the project library again, then **Add**, **New Folder**, call it `Styles` (case sentitive)
1. Right click on the `Styles` folder, then **Add**, **New Item**
1. In the **Uno Platform** section of **C# Items**, select **Resource Dictionary**, name it `MyControlStyles.xaml` (case sensitive)
1. Move the contents of the `Generic.xaml` file into `MyControlStyles.xaml` to be:

    ```xml
    <ResourceDictionary
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:XamlControlLibrary">

        <Style TargetType="local:MyTemplatedControl">
            <Setter Property="Template">
                <Setter.Value>
                    <ControlTemplate TargetType="local:MyTemplatedControl">
                        <Grid>
                            <TextBlock Text="My templated control !" />
                        </Grid>
                    </ControlTemplate>
                </Setter.Value>
            </Setter>
        </Style>

    </ResourceDictionary>
    ```

1. Finally, change the `Generic.xaml` file contents to be:

    ```xml
    <ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation">
        <ResourceDictionary.MergedDictionaries>
            <ResourceDictionary Source="ms-appx:///XamlControlLibrary/Styles/MyControlStyles.xaml" />
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
    ```

    > [!NOTE]
    > The path to `MyControlStyles.xaml` in `Generic.xaml` is containing the current project's assembly name. If you rename your project, you'll also need to change the path in the `Generic.xaml` file.

In a Control Class Library, [conditional XAML](xref:Uno.Development.PlatformSpecificXaml) and [platform-specific C#](xref:Uno.Development.PlatformSpecificCSharp) can be used.

## Library assets

WinUI 3 and Uno Platform (4.6 and later) Libraries support the inclusion of content assets to be used with [`StorageFile.GetFileFromApplicationUriAsync`](../features/file-management.md#support-for-storagefilegetfilefromapplicationuriasync), as well as with the `ms-appx:///[libraryname]/[assetname_file_name]` format.

> [!IMPORTANT]
> When using library assets with non-WinAppSDK targets, the library name should also be lower cased.

Library assets can be of any type.

Library assets are supported in two configurations:

- `ProjectReference`, where the library project is included in the solution with the application that uses it
- `PackageReference`, where the library project is being packaged as a NuGet package, and used in a separate solution, from a NuGet feed.

In both cases, for the build system to include the assets files, the following property must be set in the library's `.csproj`:

```xml
<PropertyGroup>
    <GenerateLibraryLayout>true</GenerateLibraryLayout>
</PropertyGroup>
```

> [!IMPORTANT]
> WinAppSDK [does not support assets](https://github.com/microsoft/microsoft-ui-xaml/issues/6429) if the application is using the MSIX package mode. To use the unpackaged mode, [see this article](../features/winapp-sdk-specifics.md#unpackaged-application-support).

## Considerations for the Skia Renderer

When creating a library that is compatible with the Skia Renderer, it is generally best to only use the `net9.0` and `net9.0-windows10.xxx` targets frameworks.

For more information, see the [Skia renderer](xref:uno.features.renderer.skia) documentation.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/how-to-host-a-webassembly-app.md

---
uid: Uno.Development.HostWebAssemblyApp
---

# Hosting a WebAssembly App

- WASM Web Server Configuration
  - [Azure Static WebApps](guides/azure-static-webapps.md)
  - [Nginx](#nginx)
  - [Apache](#apache)

Regardless of the web server (or reverse proxy) software used, the support the following Content (MIME) types are always needed:

- `application/wasm`
- `application/octet-stream`
- `application/font-woff`

The output of the webassembly build is generally immutable and can be cached indefinitely, with some notable exceptions:

- `_framework/blazor.boot.json`
- `_framework/dotnet.js`
- `index.html`
- Other files at the root of the output package

These files should be refreshed regularly in order to avoid app files inconsistencies.

## Nginx

Below contains a performance tuned version of *nginx* fitting WebAssembly deployments. The MIME types have been extended on top of the base *nginx* MIME types with WASM support.

```nginx
user nginx;

pid /var/run/nginx.pid;

##################################################################################
# nginx.conf Performance Tuning: https://github.com/denji/nginx-tuning
##################################################################################

# you must set worker processes based on your CPU cores, nginx does not benefit from setting more than that
worker_processes auto; #some last versions calculate it automatically

# number of file descriptors used for nginx
# the limit for the maximum FDs on the server is usually set by the OS.
# if you don't set FD's then OS settings will be used which is by default 2000
worker_rlimit_nofile 100000;

# only log critical errors
error_log /var/log/nginx/error.log crit;

# provides the configuration file context in which the directives that affect connection processing are specified.
events {
  # determines how much clients will be served per worker
  # max clients = worker_connections * worker_processes
  # max clients is also limited by the number of socket connections available on the system (~64k)
  worker_connections 4000;

  # optmized to serve many clients with each thread, essential for linux -- for testing environment
  use epoll;

  # accept as many connections as possible, may flood worker connections if set too low -- for testing environment
  multi_accept on;
}

http {
  include /etc/nginx/mime.types;
  default_type application/octet-stream;

  types {
    application/wasm wasm;
    application/octet-stream clr;
    application/octet-stream pdb;
    application/font-woff woff;
    application/font-woff woff2;
  }

  log_format main '$remote_addr - $remote_user [$time_local] "$request" '
  '$status $body_bytes_sent "$http_referer" '
  '"$http_user_agent" "$http_x_forwarded_for"';

  # cache informations about FDs, frequently accessed files
  # can boost performance, but you need to test those values
  open_file_cache max=200000 inactive=20s;
  open_file_cache_valid 30s;
  open_file_cache_min_uses 2;
  open_file_cache_errors on;

  # to boost I/O on HDD we can disable access logs
  access_log off;

  # copies data between one FD and other from within the kernel
  # faster then read() + write()
  sendfile on;

  # Send headers in one piece, it's better then sending them one by one
  tcp_nopush on;

  # don't buffer data sent, good for small data bursts in real time
  tcp_nodelay on;

  # reduce the data that needs to be sent over network
  gzip on;
  gzip_min_length 10240;
  gzip_proxied expired no-cache no-store private auth;
  gzip_types text/plain text/css text/xml text/javascript application/x-javascript application/json application/xml application/wasm application/octet-stream;
  gzip_disable msie6;

  # allow the server to close connection on non responding client, this will free up memory
  reset_timedout_connection on;

  # request timed out -- default 60
  client_body_timeout 10;

  # if client stop responding, free up memory -- default 60
  send_timeout 2;

  # server will close connection after this time -- default 75
  keepalive_timeout 30;

  # number of requests client can make over keep-alive -- for testing environment
  keepalive_requests 100000;

  #########################################
  # Just For Security Reason
  #########################################

  # Security reasons, turn off nginx versions
  server_tokens off;

  # #########################################
  # # NGINX Simple DDoS Defense
  # #########################################

  # limit the number of connections per single IP
  limit_conn_zone $binary_remote_addr zone=conn_limit_per_ip:10m;

  # limit the number of requests for a given session
  limit_req_zone $binary_remote_addr zone=req_limit_per_ip:10m rate=5r/s;

  # zone which we want to limit by upper values, we want limit whole server
  server {
    limit_conn conn_limit_per_ip 10;
    limit_req zone=req_limit_per_ip burst=10 nodelay;
  }

  # if the request body size is more than the buffer size, then the entire (or partial)
  # request body is written into a temporary file
  client_body_buffer_size 128k;

  # headerbuffer size for the request header from client -- for testing environment
  client_header_buffer_size 3m;

  # maximum number and size of buffers for large headers to read from client request
  large_client_header_buffers 4 256k;

  # read timeout for the request body from client -- for testing environment
  # client_body_timeout   3m;

  # how long to wait for the client to send a request header -- for testing environment
  client_header_timeout 3m;

  include /etc/nginx/conf.d/*.conf;
}
```

In order to enable the fallback routes in Nginx, you can use the following location rule in the configuration file:

```nginx
location ~ ^\/(?!(package_)) {
    try_files $uri $uri/ /index.html;
}
```

Additionally, in order to properly handle the caching of the WASM application by the browser, the Cache-control header should be set as follow:

```nginx
location ~ ^\/(?!(package_)) {
    try_files $uri $uri/ /index.html;
    add_header Cache-Control "must-revalidate, max-age=3600";
}

location ~ ^\/package_ {
    try_files $uri $uri/ =404;
    add_header Cache-Control "public, immutable, max-age=31536000";
}
```

If you have *brotli* enabled via [`ngx-brotli` module](https://github.com/google/ngx_brotli), you can add the following block for extra compression performance.

```nginx
brotli_static on;
brotli on;
brotli_types text/plain text/css application/json application/javascript application/x-javascript text/javascript;
brotli_comp_level 4;
```

## Apache

For *Apache*, please use the [`AddType` directive](https://httpd.apache.org/docs/2.4/mod/mod_mime.html#addtype) to add WASM support to the root of your apache config, likely located at either `/etc/apache2/apache2.conf` or `/etc/httpd.d/conf/httpd.conf`. Then, restart your *Apache* web server or *Apache* container (if you running with Docker).

```apache
AddType application/wasm .wasm
AddType application/octet-stream .clr
AddType application/octet-stream .dat
AddType application/octet-stream .pdb
AddType application/font-woff .woff
AddType application/font-woff .woff2
```

## IIS

Windows Server IIS is supported, and needs some manual installation steps to be ready for Uno Platform WebAssembly apps.

Here are some steps:

- Install the [URL Rewriter module](https://learn.microsoft.com/iis/extensions/url-rewrite-module/url-rewrite-module-configuration-reference)
- Add an application to the local web site in IIS and set its physical path to: `...\MyApp\MyApp.Wasm\bin\Debug\netstandard2.0\dist` or `...\MyApp\MyApp.Wasm\bin\Debug\net5.0\dist`
- Add MIME type `application/octet-stream .clr` to IIS.
- Add MIME type `application/wasm .wasm` to IIS.
- Add MIME type `application/octet-stream .dat` to IIS.
- Add MIME type `application/woff2 .woff2` to IIS
- Add MIME type `application/pdb .pdb` to IIS

Run `http:localhost/Myapp` for testing

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/how-uno-works.md

---
uid: Uno.Development.HowItWorks
---

# How Uno Platform Works

How does Uno Platform make the same application code run on all platforms?

## Uno Platform at Runtime

The [`Uno.WinUI` NuGet package](https://www.nuget.org/packages/Uno.WinUI/) and [`Uno.WinRT` NuGet package](xref:uno.features.uno.winrt) implement the entire WinUI and WinRT API surface across platforms. This includes:

- Namespaces like `Microsoft.UI` and related UI APIs
- The support for cross-platform non-UI APIs, such as file system access, devices and sensors, pickers, etc...

> [!NOTE]
> As the API surface is very large, some parts are included but not implemented. These features are marked with the [`Uno.NotImplementedAttribute`] attribute, and a code analyzer is included with the Uno.WinUI package will generate a warning for any such features that are referenced. You can see a complete list of supported APIs in the [implemented views documentation](implemented-views.md).

## Rendering the UI

As a developer, you write your UI using the standard WinUI-based XAML. Under the hood, Uno Platform maps this visual tree to the appropriate rendering mechanism for each platform.

For every platform, the public API - panels, control templates, measurement and arranging, etc - is the same. However, it's sometimes useful to know what's going on at render-time, for example when [embedding native views inside XAML views](xref:Uno.Development.NativeViews) on a platform-specific basis.

Uno Platform provides two rendering modes, Skia and Native. The first one uses Skia to draw all the App pixels on the screen, while the second one uses the native platform APIs to render on the screen.

Skia is the default renderer in the **Blank** and **Recommended** Uno Platform project template presets.

### Skia Rendering

Available on iOS, Android, macOS, Windows, Linux and WebAssembly, based on the [Skia](https://skia.org) drawing library, the Skia Renderer is a cross-platform unified rendering component of Uno Platform which provides a single UI experience across all supported platforms.

The whole UI Visual Tree is drawn on an hardware accelerated canvas, using Metal, OpenGL, and WebGL where applicable. Unlike Native rendering, Skia doesn’t rely on platform UI components.

The Skia Rendering backend has a very cheap cost for creating UI elements, which makes it very efficient for large user interfaces.

For more information, see our documentation on the [Skia renderer](xref:uno.features.renderer.skia).

### Native Rendering

The native rendering is our oldest rendering backend, which uses the native components and APIs to render the UI.

Each platform has its own set of platform interactions, listed below, allowing for deep integration of native components into the visual tree. Each `UIElement` has a corresponding native element (`div` on WebAssembly, `UIView` on iOS, `ViewGroup` on Android).

This renderer uses the native input controls of the platforms, providing the best access to accessibility and IME features.

For more information, see our documentation on the [Native renderer](xref:uno.features.renderer.native).

## Windows using WinAppSDK

On Windows (the `net10.0-windows10.0.xxxxx` target framework) using [Windows App SDK](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/), the application isn't using Uno Platform at all. It's compiled just like a single-platform WinUI application, using Microsoft's own tooling.

## Uno Platform at Build Time

### Binaries

Uno Platform applications use [.NET 9 or later](https://learn.microsoft.com/dotnet/core/introduction) and run on all major platforms:

- **Mobile/Desktop**: via .NET for Mobile
- **Web**: via .NET for WebAssembly
- **Linux/macOS**: via standard .NET runtime

### XAML Processing

- XAML is parsed at build time using a Roslyn source generator.
- It’s compiled to C# to improve runtime performance.
- This is fully transparent to developers.

### Assets & Resources

- Images and other assets are transformed and copied to each platform’s expected structure.
- String resources (`.resw`) are converted into platform-specific formats.
- Learn more in [Working with Assets](xref:Uno.Features.Assets).

## Summary

Uno Platform enables a single codebase to target all major platforms by:

- Reproducing the WinUI API surface with `Uno.WinUI`
- Mapping XAML UI to native or Skia-based rendering pipelines
- Using .NET and MSBuild to compile apps for specific targets
- Automating asset, XAML, and resource handling for cross-platform compatibility

Whether you're building for mobile, desktop, or web, Uno Platform gives the flexibility to choose native or Skia rendering to best match the app's needs.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/howto-consume-webservices.md

---
uid: Uno.Development.ConsumeWebApi
---

# How to consume a web API

This how-to will walk you through the process of creating a multi-platform application that leverages web services. Specifically you will be:

* Creating a simple Uno application.
* Registering for The Cat API web service.
* Building a number of data models that utilize JSON serialization.
* Building a web service base class that supports REST service operations and then building a number of services that are derived from it.
* Using the services in a view-model.
* Build a XAML UI that utilizes the view-model.
* Test the application in Windows and WASM.

Throughout the how-to, there will be notes on recommended practices and tips that highlight resources for additional learning.

> [!TIP]
> The complete source code that goes along with this tutorial is available in the [unoplatform/Uno.Samples](https://github.com/unoplatform/Uno.Samples) GitHub repository - [TheCatApiClient](https://github.com/unoplatform/Uno.Samples/tree/master/UI/TheCatApiClient)
>
> [!TIP]
> For a step-by-step guide to installing the prerequisites, see [Getting started on Visual Studio](xref:Uno.GetStarted.vs2022)

## Task 1 - Create a simple Uno application

In this task, you will create a simple Single Page App with the Uno Platform. This app - **TheCatApiClient** - will be used to demonstrate an approach to consuming REST web services using the **HttpClient** class.

1. Open Visual Studio and click on **Create a new project**.

    ![Visual Studio new project dialog](Assets/tutorial01/newproject1.PNG)
1. In the **Search for Templates** search box, enter **Uno**

    ![Visual Studio new project dialog searching for Uno](Assets/tutorial01/newproject2.PNG)

1. In the filtered list of templates, select **Uno Platform App** and then click **Next**.

1. In the **Configure your new project** window, set the **Project name** to **TheCatApiClient**, choose where you would like to save your project, and click the **Create** button.

    ![Configure your new project dialog](Assets/how-to-webservice/newproject3.PNG)

    > [!IMPORTANT]
    > The C# and XAML snippets in this tutorial require that the solution is named **TheCatApiClient**. Using a different name will result in build errors when you copy code from this tutorial into the solution.

1. Select the **Blank** preset. Then, click the **Create** button. Wait for the projects to be created and their dependencies to be restored.

    ![Select startup type in the Uno platform template wizard](Assets/tutorial01/vsix-new-project-options.png)

1. In the **Solution Explorer**, to update the Uno NuGet packages to the latest version, right-click on the Solution file **Solution 'TheCatApiClient'** and select **Manage NuGet Packages for Solution...** from the context menu.

    The **Manage Packages for Solution** page will open.

1. At the top-right of the **Manage Packages for Solution** page, in the **Package source** dropdown, ensure that **nuget.org** or **NuGet official package source** is selected.

1. At the top-left of the page, to browse the available packages, click **Browse**.

1. In the **Search** field, enter **System.Text.Json** and select **System.Text.Json**.

    > [!TIP]
    > The **System.Text.Json** package provides functionality for serializing to and deserializing from JavaScript Object Notation (JSON). You can learn more about how to serialize and deserialize here: [How to serialize and deserialize (marshal and unmarshal) JSON in .NET](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json-how-to)

1. In the right pane of the **Manage Packages for Solution** page, select every project and click **Install**.

    ![Install System.Text.Json nuget package](Assets/how-to-webservice/json-install.png)

1. To workaround a Visual studio issue regarding the XAML editor, you'll need to close any opened file in the editor, then close the solution or Visual Studio, then re-open it.

1. To test the Windows version of the application, in the **Solution Explorer**,  right-click the **TheCatApiClient.Windows** project and click **Set as Startup Project**

1. To launch the application, under the **Debug** menu, click **Start Debugging** or use the shortcut key, commonly **F5**.

    ![The Cat API Client app running cross-platform](Assets/how-to-webservice/TheCatApiClient-UWP.png)

    The following image shows the sample app running on the Android Simulator, IPhone Simulator and as a WASM app in the browser.

    ![The Cat API Client app running cross-platform](Assets/how-to-webservice/crosplat-start.png)

You have now created a sample application that will be extended in later tasks.

## Task 2 - Sign up for API key

In order to demonstrate how to consume a web service, there needs to be a web service available. In this tutorial you will build a simple client that leverages [The Cat API](https://thecatapi.com/). The website for this service describes it as:

> A public service API all about Cats, free to use when making your fancy new App, Website or Service.

In order to use this service, you need to sign up for a free API key.

1. In a browser, navigate to The Cat API sign-up page: [https://thecatapi.com/signup](https://thecatapi.com/signup)

1. Complete the sign-up form and click **sign-up**.

    You will receive an email with your API key - you will need the key later.

1. Review the API authentication information: [https://docs.thecatapi.com/authentication](https://docs.thecatapi.com/authentication).

    Notice that there are two options for passing the API key - the preferred method using a Request Header, the approach we will use in the code, and passing it as a Query Parameter. The Query Parameter approach makes it very easy to query the API via a browser.

1. To test the API and your API key, open the following URL in a browser (replace the `{YOUR-API-KEY}` value with your key):

    ```http
    https://api.thecatapi.com/v1/breeds/search?q=sib&api_key={YOUR-API-KEY}
    ```

    e.g.

    ```http
    https://api.thecatapi.com/v1/breeds/search?q=sib&api_key=B1D218CC-0D2D-4B3E-89EA-EEC373EB3CA5
    ```

    This simple breed search query will return some JSON data that describes the Siberian cat breed:

    ```json
    [
        {
            "weight":
            {
                "imperial": "8 - 16",
                "metric": "4 - 7"
            },
            "id": "sibe",
            "name": "Siberian",
            "cfa_url": "http://cfa.org/Breeds/BreedsSthruT/Siberian.aspx",
            "vetstreet_url": "http://www.vetstreet.com/cats/siberian",
            "vcahospitals_url": "https://vcahospitals.com/know-your-pet/cat-breeds/siberian",
            "temperament": "Curious, Intelligent, Loyal, Sweet, Agile, Playful, Affectionate",
            "origin": "Russia",
            "country_codes": "RU",
            "country_code": "RU",
            "description": "The Siberians dog like temperament and affection makes the ideal lap cat and will live quite happily indoors. Very agile and powerful, the Siberian cat can easily leap and reach high places, including the tops of refrigerators and even doors. ",
            "life_span": "12 - 15",
            "indoor": 0,
            "lap": 1,
            "alt_names": "Moscow Semi-longhair, HairSiberian Forest Cat",
            "adaptability": 5,
            "affection_level": 5,
            "child_friendly": 4,
            "dog_friendly": 5,
            "energy_level": 5,
            "grooming": 2,
            "health_issues": 2,
            "intelligence": 5,
            "shedding_level": 3,
            "social_needs": 4,
            "stranger_friendly": 3,
            "vocalisation": 1,
            "experimental": 0,
            "hairless": 0,
            "natural": 1,
            "rare": 0,
            "rex": 0,
            "suppressed_tail": 0,
            "short_legs": 0,
            "wikipedia_url": "https://en.wikipedia.org/wiki/Siberian_(cat)",
            "hypoallergenic": 1
        }
    ]
    ```

    > [!TIP]
    > You can learn more about the breed search API here - [GET/breeds/search](https://docs.thecatapi.com/api-reference/breeds/breeds-search).

Now you have signed up for the API, you are ready to start implementing the API client by creating a data model.

## Task 3 - Create API model

The primary objective of this tutorial is to demonstrate how to implement a REST web service client that runs in each project head. To achieve that, you won't create a client that fully uses **TheCatApi** - it will focus on breed searches and favorites. The app will also use simplified models (fewer fields) where possible.

1. To create a folder for the models, in the **Solution Explorer**, right-click the **TheCatApiClient** project, select **Add**, click **New Folder**, and then name the new folder **Models**.

1. To add a folder for the data types, right-click the **Models** folder you just created, select **Add**, click **New Folder**, and then name the new folder **DataModels**.

1. To add a folder for the view model types, right-click the **Models** folder, select **Add**, click **New Folder**, and then name the new folder **ViewModels**.

1. Examine the JSON returned from the breed search you executed earlier:

    ```json
    [
        {
            "weight":
            {
                "imperial": "8 - 16",
                "metric": "4 - 7"
            },
            "id": "sibe",
            "name": "Siberian",
            "cfa_url": "http://cfa.org/Breeds/BreedsSthruT/Siberian.aspx",
            "vetstreet_url": "http://www.vetstreet.com/cats/siberian",
            "vcahospitals_url": "https://vcahospitals.com/know-your-pet/cat-breeds/siberian",
            "temperament": "Curious, Intelligent, Loyal, Sweet, Agile, Playful, Affectionate",
            "origin": "Russia",
            "country_codes": "RU",
            "country_code": "RU",
            "description": "The Siberians dog like temperament and affection makes the ideal lap cat and will live quite happily indoors. Very agile and powerful, the Siberian cat can easily leap and reach high places, including the tops of refrigerators and even doors. ",
            "life_span": "12 - 15",
            "indoor": 0,
            "lap": 1,
            "alt_names": "Moscow Semi-longhair, HairSiberian Forest Cat",
            "adaptability": 5,
            "affection_level": 5,
            "child_friendly": 4,
            "dog_friendly": 5,
            "energy_level": 5,
            "grooming": 2,
            "health_issues": 2,
            "intelligence": 5,
            "shedding_level": 3,
            "social_needs": 4,
            "stranger_friendly": 3,
            "vocalisation": 1,
            "experimental": 0,
            "hairless": 0,
            "natural": 1,
            "rare": 0,
            "rex": 0,
            "suppressed_tail": 0,
            "short_legs": 0,
            "wikipedia_url": "https://en.wikipedia.org/wiki/Siberian_(cat)",
            "hypoallergenic": 1
        }
    ]
    ```

    That is a lot of fields - you will use a simpler data model in this tutorial.

1. To create a simple model that represents the breed search results, right-click the **DataModels** folder, select **Add** and click **Class...**

1. On the **Add New Item** dialog, in the **Name** field, enter **Breed.cs**

1. In the editor, replace the content of the **Breed.cs** class with the following:

    ```csharp
    using System;
    using System.Text.Json.Serialization;

    namespace TheCatApiClient.Models.DataModels
    {
        public partial class Breed
        {
            [JsonPropertyName("id")]
            public string Id { get; set; }

            [JsonPropertyName("name")]
            public string Name { get; set; }

            [JsonPropertyName("temperament")]
            public string Temperament { get; set; }

            [JsonPropertyName("origin")]
            public string Origin { get; set; }

            [JsonPropertyName("description")]
            public string Description { get; set; }

            [JsonPropertyName("wikipedia_url")]
            public Uri WikipediaUrl { get; set; }
        }
    }
    ```

    > [!TIP]
    > This class is using the **JsonPropertyNameAttribute** from the **System.Text.Json** package to map the lowercase JSON property names to the [PascalCase](https://techterms.com/definition/pascalcase) convention used in C#. To learn more about **System.Text.Json**, you can review the documentation here - [How to serialize and deserialize (marshal and unmarshal) JSON in .NET](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json-how-to).

You have now created a simple data model that can be used to deserialize the JSON returned by the breed search API. Next, you will create a service that interacts with the web service API.

## Task 4 - Create simple GET service for breed search

In this task, you will create a number of classes that demonstrate how to use the **HttpClient** class to interact with a web service. Along the way, you will see some patterns that may assist in the reuse of the code in additional projects.

1. To create a folder for the web services, in the **Solution Explorer**, right-click the **TheCatApiClient** project, select **Add**, click **New Folder**, and then name the new folder **WebServices**.

1. To add a base class for all the web services, right-click the **WebServices** folder, select **Add** and click **Class...**

1. On the **Add New Item** dialog, in the **Name** field, enter **WebApiBase.cs**

1. In the editor, replace the content of the **WebApiBase.cs** class with the following:

    ```csharp
    using System.Collections.Generic;
    using System.Net.Http;
    using System.Threading.Tasks;
    using Uno.Extensions.Specialized;

    namespace TheCatApiClient.WebServices
    {
        public abstract class WebApiBase
        {
            // Insert variables below here

            // Insert static constructor below here

            // Insert CreateRequestMessage method below here

            // Insert GetAsync method below here

            // Insert DeleteAsync method below here

            // Insert PostAsync method below here

            // Insert PutAsync method below here
        }
    }
    ```

    This defines the structure of the class **WebApiBase**. It is defined as an abstract class with the intention that every web service API class inherits from it.

1. To add the member variable for an **HttpClient**, locate the comment **// Insert variables below here** and replace it with the following code:

    ```csharp
    // Insert variables below here
    protected static HttpClient _client;
    ```

    Notice that the **_client** variable is declared as **static**. This means there will only be one instance of the **HttpClient** shared by every instance of **WebApiBase** as **HttpClient** is intended to be instantiated once and re-used throughout the life of an application.

    > [!TIP]
    > You can review the Microsoft remarks on **HttpClient** here - [HttpClient Remarks](https://learn.microsoft.com/dotnet/api/system.net.http.httpclient#remarks).

1. To initialize the static **_client** variable, locate the comment **// Insert static constructor below here** and replace it with the following code:

    ```csharp
    // Insert static constructor below here
    static WebApiBase()
    {
        _client = new HttpClient();
    }
    ```

    To facilitate the re-use of the single **HttpClient** instance, you will use instances of the **HttpRequestMessage** class to represent each request, rather than directly setting the **BaseAddress** and **DefaultRequestHeader** properties on the single **HttpClient** instance. This provides a thread-safe, reusable way of making multiple requests with the single **HttpClient** instance.

1. To simplify the creation of an **HttpRequestMessage** instance, locate the comment **// Insert CreateRequestMessage method below here** and replace it with the following code:

    ```csharp
    // Insert CreateRequestMessage method below here
    private HttpRequestMessage CreateRequestMessage(HttpMethod method, string url, Dictionary<string, string> headers = null)
    {
        var httpRequestMessage = new HttpRequestMessage(method, url);
        if (headers != null && headers.Any())
        {
            foreach (var header in headers)
            {
                httpRequestMessage.Headers.Add(header.Key, header.Value);
            }
        }

        return httpRequestMessage;
    }
    ```

    Notice that this method expects the **HttpMethod** to represent a GET, DELETE, UPDATE, or POST operation, the string URL, and an optional dictionary of headers. In this initial implementation of the **WebApiBase** class, you will consume this from the **GetAsync** method you are about to implement.

    > [!NOTE]
    > You will use the header dictionary to supply the authentication key you created earlier.

1. To implement a method that will retrieve a string from a web API, locate the comment **// Insert GetAsync method below here** and replace it with the following code:

    ```csharp
    // Insert GetAsync method below here
    protected async Task<string> GetAsync(string url, Dictionary<string, string> headers = null)
    {
        using (var request = CreateRequestMessage(HttpMethod.Get, url, headers))
        using (var response = await _client.SendAsync(request))
        {
            if (response.IsSuccessStatusCode)
            {
                return await response.Content.ReadAsStringAsync();
            }

            return null;
        }
    }
    ```

    Notice that this asynchronous method uses the **CreateRequestMessage** you just created. As the returned **HttpRequestMessage** object implements the **IDisposable** interface, the **request** variable is defined within a `using` statement that obtains the resource, executes the statements that you specify, and then automatically disposes of the **HttpRequestMessage** instance.

    The remainder of the method uses the single **HttpClient** instance to send the **request** and `await` a response. If the response is successful, the response content is read and returned as a string. If, for some reason, the response does not indicate success, a `null` is returned.

    > [!IMPORTANT]
    > As implementing adequate error handling would add many lines of code, more robust error handling is omitted for clarity. If you are interested in learning more about the considerations for handling errors with **HttpClient**, review the following blog post - [HttpClient - Error handling, a test-driven approach](https://josef.codes/httpclient-error-handling-a-test-driven-approach/).

1. You will implement the remaining methods of the **WebApiBase** class in a later task. The current implementation should look similar to:

    ```csharp
    using System.Collections.Generic;
    using System.Net.Http;
    using System.Threading.Tasks;
    using Uno.Extensions.Specialized;

    namespace TheCatApiClient.WebServices
    {
        public abstract class WebApiBase
        {
            // Insert variables below here
            protected static HttpClient _client;

            // Insert static constructor below here
            static WebApiBase()
            {
                _client = new HttpClient();
            }

            // Insert CreateRequestMessage method below here
            private HttpRequestMessage CreateRequestMessage(HttpMethod method, string url, Dictionary<string, string> headers = null)
            {
                var httpRequestMessage = new HttpRequestMessage(method, url);
                if (headers != null && headers.Any())
                {
                    foreach (var header in headers)
                    {
                        httpRequestMessage.Headers.Add(header.Key, header.Value);
                    }
                }

                return httpRequestMessage;
            }

            // Insert GetAsync method below here
            protected async Task<string> GetAsync(string url, Dictionary<string, string> headers = null)
            {
                using (var request = CreateRequestMessage(HttpMethod.Get, url, headers))
                using (var response = await _client.SendAsync(request))
                {
                    if (response.IsSuccessStatusCode)
                    {
                        return await response.Content.ReadAsStringAsync();
                    }

                    return null;
                }
            }

            // Insert DeleteAsync method below here

            // Insert PostAsync method below here

            // Insert PutAsync method below here
        }
    }
    ```

    You will now implement the Breed Search API service. This service will inherit from **WebApiBase** and have a single method named **Search** that expects a search string.

1. To add a class for the Breed Search API service, in the **TheCatApiClient** project, right-click the **WebServices** folder, select **Add** and click **Class...**

1. On the **Add New Item** dialog, in the **Name** field, enter **BreedSearchApi.cs**

1. In the editor, replace the content of the **BreedSearchApi.cs** class with the following:

    ```csharp
    using System.Collections.Generic;
    using System.Net;
    using System.Text.Json;
    using System.Threading.Tasks;
    using TheCatApiClient.Models.DataModels;

    namespace TheCatApiClient.WebServices
    {
        public class BreedSearchApi : WebApiBase
        {
            public async Task<IEnumerable<Breed>> Search(string search)
            {
                var result = await this.GetAsync(
                    $"https://api.thecatapi.com/v1/breeds/search?q={WebUtility.HtmlEncode(search)}",
                    new Dictionary<string, string> {
                        {"accept", "application/json" },
                        {"x-api-key", "{YOUR-API-KEY}"}
                    });

                if (result != null)
                {
                    return JsonSerializer.Deserialize<IEnumerable<Breed>>(result);
                }

                return new List<Breed>();
            }
        }
    }
    ```

    As most of the complexity for working with a web service is encapsulated in the **WebApiBase** class, this service is straightforward.

    First, you will note that the method is asynchronous. You will then notice the use of string interpolation and the **WebUtility.HtmlEncode** method to construct the API url. Also note how the request headers are supplied to the call - the **accept** header advises the API that the client expects JSON, and the **x-api-key** specifies your API key.

    > [!IMPORTANT]
    > Replace the `{YOUR-API-KEY}` value with the API key you were sent when you registered with TheCatApi.

Once the result is returned, it is null-checked and, if not-null, the JSON is deserialized into an enumerable collection of **Breed** instances using the data model you created earlier. If the result is null, then an empty list is returned.

At this point, you have implemented a simple breed search service. Now, it is time to create the view and view-model that will allow a user to enter a search term and display the results.

## Task 5 - Create a base view model

In this sample application, you will be adopting the Model-View-ViewModel (MVVM) pattern, which helps to cleanly separate business and presentation logic. In this task, you will be creating the base view model that will be used in the following task to create the view model for the main page.

> [!TIP]
> If you want to learn more about MVVM, review the [The Model-View-ViewModel Pattern documentation](https://learn.microsoft.com/xamarin/xamarin-forms/enterprise-application-patterns/mvvm).

1. To add a base view-model class, in the **TheCatApiClient** project, right-click the **Models\ViewModels** folder, select **Add** and click **Class...**

1. On the **Add New Item** dialog, in the **Name** field, enter **DispatchedBindableBase.cs**

    > [!TIP]
    > Although this sample only has a single view-model, it is a good practice to collect common code such as an **INotifyPropertyChanged** implementation and UI thread dispatch into a base class. Doing so will ease the addition of new view-models as needed and reduce code duplication.

1. In the editor, replace the content of the **DispatchedBindableBase.cs** class with the following:

    ```csharp
    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Runtime.CompilerServices;
    using System.Threading.Tasks;
    using Microsoft.UI.Dispatching;

    namespace TheCatApiClient.Models.ViewModels
    {
        public abstract class DispatchedBindableBase : INotifyPropertyChanged
        {
            // Insert the event and property below here

            // Insert SetProperty below here

            // Insert RaisePropertyChanged below here

            // Insert DispatchAsync below here
        }
    }
    ```

    Notice that the class will implement **INotifyPropertyChanged** - this will allow view-models to notify bound controls when the property values have changed.

1. To the add a property and event, locate the comment **// Insert the event and property below here** and replace it with the following code:

    ```csharp
    // Insert the event and property below here
    public event PropertyChangedEventHandler PropertyChanged;
    protected DispatcherQueue Dispatcher => DispatcherQueue.GetForCurrentThread();
    ```

    The **PropertyChanged** event declaration satisfies the **INotifyPropertyChanged** interface contract, but isn't particularly helpful alone - you will add methods that make it easier to use shortly.

    The **Dispatcher** property is used later to ensure property updates are performed on the UI thread - an essential detail for updating controls in multi-tasking applications.

    > [!TIP]
    > You can learn more about the UI Thread and multi-tasking here - [Keep the UI thread responsive](https://learn.microsoft.com/windows/uwp/debug-test-perf/keep-the-ui-thread-responsive)

1. To add the method that will be used to set a property value and raise the property changed event, locate the comment **// Insert SetProperty below here** and replace it with the following code:

    ```csharp
    // Insert SetProperty below here
    protected virtual bool SetProperty<T>(ref T backingVariable, T value, [CallerMemberName] string propertyName = null)
    {
        if (EqualityComparer<T>.Default.Equals(backingVariable, value)) return false;

        backingVariable = value;
        RaisePropertyChanged(propertyName);

        return true;
    }
    ```

    There can be a bit to unpack here. First, this is a generic method that allows any type to be used, as indicated by the use of `<T>`, so it can be used for all properties.

    Then, looking at parameters, the **backingVariable** is passed by reference, allowing this method to change the value for the caller as well as locally. Next, the **value** is supplied. Finally, the **propertyName** parameter is defined. At first glance, this appears to be an optional parameter with a default value of null. However the compiler notes the presence of the **CallerMemberName** attribute and assigns the name of the calling method to the property (in the case of a property setter method, the name of the property).

    The method body then compares the incoming value with the current property value, and returns false if they are equal. This prevents a situation where a property is updated, which updates a control via binding, which then sets the same property with the same value again. Without this guard, the code would continue to loop.

    The **value** is then assigned to the **backingVariable** (updating the variable in the caller). The property changed event is raised (you will add that next) and a true value is returned.

    > [!TIP]
    > You can learn more about **CallerMemberNameAttribute** here - [Reserved attributes: Determine caller information](https://learn.microsoft.com/dotnet/csharp/language-reference/attributes/caller-information).

1. To add the method that will actually raise the property changed event, locate the comment **// Insert RaisePropertyChanged below here** and replace it with the following code:

    ```csharp
    // Insert RaisePropertyChanged below here
    protected void RaisePropertyChanged([CallerMemberName] string propertyName = null)
    {
    #pragma warning disable CS4014 // Because this call is not awaited, execution of the current method continues before the call is completed
        DispatchAsync(() => PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName)));
    #pragma warning restore CS4014 // Because this call is not awaited, execution of the current method continues before the call is completed
    }
    ```

    This method uses a helper method (added next) to ensure the event is raised on the UI thread. As the code does not await this execution, the compiler would usually display a warning with the assumption that this is a mistake. As it is intentional, the code includes `#pragma` directives that temporarily disable that warning.

    > [!TIP]
    > If you want to learn more about lambda expressions, review the document here - [Lambda expressions](https://learn.microsoft.com/dotnet/csharp/language-reference/operators/lambda-expressions)

1. To add a helper method that will ensure a callback is executed on the UI thread, locate the comment **// Insert Dispatch below here** and replace it with the following code:

    ```csharp
    // Insert DispatchAsync below here
    protected async Task DispatchAsync(DispatcherQueueHandler callback)
    {
        var hasThreadAccess =
    #if __WASM__
        true;
    #else
        Dispatcher.HasThreadAccess;
    #endif

        if (hasThreadAccess)
        {
            callback.Invoke();
        }
        else
        {
            var completion = new TaskCompletionSource();
            Dispatcher.TryEnqueue(() =>
            {
                callback();
                completion.SetResult();
            });
            await completion.Task; 
        }
    }
    ```

    > [!NOTE]
    > As **WASM** is currently single-threaded, the **Uno.WASM** implementation of `DispatcherQueue.HasThreadAccess` always returns `false` by default. This default has been chosen to prevent live-locking for certain frameworks that expect a multi-threaded environment. This app overrides that default WASM behavior here via conditional compilation and always invokes the callback directly on WASM.

    In XAML applications, control bindings should only be updated on the UI thread, therefore this code uses the value of **hasThreadAccess** to determine if the callback can be directly invoked. If not, the **DispatcherQueue.TryEnqueue** method is used to execute the callback on the UI Thread. This method is used when setting properties and whenever bound collections are updated, to ensure the collection views (such as GridView, ListView, etc.) are updated.

1. Once complete the base class will look similar to the following:

    ```csharp
    using System;
    using System.Collections.Generic;
    using System.ComponentModel;
    using System.Runtime.CompilerServices;
    using System.Threading.Tasks;
    using Microsoft.UI.Dispatching;

    namespace TheCatApiClient.Models.ViewModels
    {
        public abstract class DispatchedBindableBase : INotifyPropertyChanged
        {
            // Insert variables below here
            protected DispatcherQueue Dispatcher => DispatcherQueue.GetForCurrentThread();

            // Insert variables below here
            public event PropertyChangedEventHandler PropertyChanged;

            // Insert SetProperty below here
            protected virtual bool SetProperty<T>(ref T backingVariable, T value, [CallerMemberName] string propertyName = null)
            {
                if (EqualityComparer<T>.Default.Equals(backingVariable, value)) return false;

                backingVariable = value;
                RaisePropertyChanged(propertyName);

                return true;
            }

            // Insert RaisePropertyChanged below here
            protected void RaisePropertyChanged([CallerMemberName] string propertyName = null)
            {
    #pragma warning disable CS4014 // Because this call is not awaited, execution of the current method continues before the call is completed
                DispatchAsync(() => PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(propertyName)));
    #pragma warning restore CS4014 // Because this call is not awaited, execution of the current method continues before the call is completed
            }

        // Insert DispatchAsync below here
        protected async Task DispatchAsync(DispatcherQueueHandler callback)
        {
            var hasThreadAccess =
        #if __WASM__
            true;
        #else
            Dispatcher.HasThreadAccess;
        #endif

            if (hasThreadAccess)
            {
                callback.Invoke();
            }
            else
            {
                var completion = new TaskCompletionSource();
                Dispatcher.TryEnqueue(() =>
                {
                    callback();
                    completion.SetResult();
                });
                await completion.Task; 
            }
        }
    }
    ```

## Task 6 - Build the search UI view model

In this task, you will build the view-model that implements a simple breed search feature using the base class and web service client you just implemented.

1. In the **TheCatApiClient** project, right-click the **Models\ViewModels** folder, select **Add** and click **Class...**

1. On the **Add New Item** dialog, in the **Name** field, enter **MainViewModel.cs**

1. In the editor, replace the content of the **MainViewModel.cs** class with the following:

    ```csharp
    using System.Collections.ObjectModel;
    using System.Linq;
    using TheCatApiClient.Models.DataModels;
    using TheCatApiClient.WebServices;
    using Uno.Extensions.Specialized;

    namespace TheCatApiClient.Models.ViewModels
    {
        public class MainViewModel : DispatchedBindableBase
        {
            // Insert member variables below here

            // Insert properties below here

            // Insert constructor below here

            // Insert SearchBreeds below here

            // Insert Favorites below here
        }
    }
    ```

    This **MainViewModel** class inherits from the base class you just created.

1. To add the member variables, locate the comment **// Insert variables below here** and replace it with the following code:

    ```csharp
    // Insert variables below here
    private bool _isBusy;
    private string _searchTerm = string.Empty;
    private ObservableCollection<Breed> _searchResults = new ObservableCollection<Breed>();
    private BreedSearchApi _breedSearchApi = new BreedSearchApi();
    ```

    The **_searchTerm** variable is the backing variable for the property that will hold the user-entered search term.

    The **_searchResults** variable is the backing variable for the property that will hold the search results. As it is an **ObservableCollection**, any changes to the collection will update the UI.

    The final variable, **_breedSearchApi**, holds a reference to an instance of the **BreedSearchApi** you created earlier.

    > [!TIP]
    > You can learn more about **ObservableCollection** and its events here - [ObservableCollection<T> Class](https://learn.microsoft.com/dotnet/api/system.collections.objectmodel.observablecollection-1)

1. To add the properties that will be used in XAML bindings, locate the comment **// Insert properties below here** and replace it with the following code:

    ```csharp
    // Insert properties below here
    public bool IsBusy
    {
        get => _isBusy;
        set => SetProperty(ref _isBusy, value);
    }

    public string SearchTerm
    {
        get => _searchTerm;
        set => SetProperty(ref _searchTerm, value);
    }

    public ObservableCollection<Breed> SearchResults
    {
        get => _searchResults;
        set => SetProperty(ref _searchResults, value);
    }
    ```

    These properties use the backing variables you added earlier, and utilize the **SetProperty** inherited from **BaseViewModel** to raise property changed notifications to ensure the UI is updated when the values change.

1. To add the method that is invoked when the user wishes to search for breeds, locate the comment **// Insert SearchBreeds below here** and replace it with the following code:

    ```csharp
    // Insert SearchBreeds below here
    public async Task SearchBreeds()
    {
        if (!string.IsNullOrWhiteSpace(SearchTerm))
        {
            try
            {
                IsBusy = true;
                var result = await _breedSearchApi.Search(SearchTerm).ConfigureAwait(false);
                if (result.Any())
                {
                    SearchResults = new ObservableCollection<Breed>(result);
                }
            }
            finally
            {
                IsBusy = false;
            }
        }
    }
    ```

    As much of the complexity of interacting with the breed search API is encapsulated, this method is pretty straightforward. Notice that it first ensures the **SearchTerm** is not empty, and then sets the **IsBusy** property to `true`. **IsBusy** is used to toggle a data loading indicator in the view. Notice the use of `try {} finally {}` to ensure the **IsBusy** property is always set back to false even if an exception is thrown. Of course, in production you would also be handling the exception more gracefully...

    The **result** variable is then assigned the return value from the asynchronous call to the **Search** method you implemented earlier. Remember that it will contain either an empty `List<Breed>` or a populated `IEnumerable<Breed>` containing the search results. The `ConfigureAwait(false)` call configures the task so that continuation after the await does not have to be run in the caller context, therefore avoiding any possible deadlocks. This means that the code that follows may not execute on the UI thread. Fortunately, the base view model ensures that property updates are dispatched to the UI thread.

    Next, if results are present, the **SearchResults** collection is replaced. Finally, the **IsBusy** property is set to `false`.

1. You will implement the remaining methods of the **MainViewModel** class in a later task. The current implementation should look similar to:

    ```csharp
    using System.Linq;
    using TheCatApiClient.Models.DataModels;
    using TheCatApiClient.WebServices;
    using Uno.Extensions.Specialized;

    namespace TheCatApiClient.Models.ViewModels
    {
        public class MainViewModel : BaseViewModel
        {
            // Insert member variables below here
            private bool _isBusy;
            private string _searchTerm = string.Empty;
            private ObservableCollection<Breed> _searchResults = new ObservableCollection<Breed>();
            private BreedSearchApi _breedSearchApi = new BreedSearchApi();

            // Insert properties below here
            public bool IsBusy
            {
                get => _isBusy;
                set => SetProperty(ref _isBusy, value);
            }

            public string SearchTerm
            {
                get => _searchTerm;
                set => SetProperty(ref _searchTerm, value);
            }

            public ObservableCollection<Breed> SearchResults
            {
                get => _searchResults;
                set => SetProperty(ref _searchResults, value);
            }

            // Insert constructor below here
            public MainViewModel()
            {
            }

            // Insert SearchBreeds below here
            public async Task SearchBreeds()
            {
                if (!string.IsNullOrWhiteSpace(SearchTerm))
                {
                    try
                    {
                        IsBusy = true;
                        var result = await _breedSearchApi.Search(SearchTerm).ConfigureAwait(false);
                        if (result.Any())
                        {
                            SearchResults = new ObservableCollection<Breed>(result);
                        }
                    }
                    finally
                    {
                        IsBusy = false;
                    }
                }
            }
            // Insert Favorites below here
        }
    }
    ```

You have now built the view-model for the Main Page. Next, it is time to build the XAML for the view.

## Task 7 - Add breed search to the main view

In this task you will create the XAML for the UI and implement the bindings for the **MainViewModel**. When the Windows version of the app is running, the UI will look similar to this:

![Windows app Search UI preview](Assets/how-to-webservice/uwp-ui-preview.png)

1. In the **Solution Explorer**, in the **TheCatApiClient** project, open the **MainPage.xaml** file.

1. If the **MainPage.xaml** file has opened in the **Design** view, switch to the **XAML** view.

1. Replace the contents of the **MainPage.xaml** file with the following:

    ```xml
    <Page
        x:Class="TheCatApiClient.MainPage"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:TheCatApiClient"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:viewmodels="using:TheCatApiClient.Models.ViewModels"
        xmlns:datamodels="using:TheCatApiClient.Models.DataModels"
        xmlns:toolkit="using:Uno.UI.Toolkit"
        mc:Ignorable="d"
        Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

        <Page.DataContext>
            <viewmodels:MainViewModel x:Name="ViewModel" />
        </Page.DataContext>

        <Grid toolkit:VisibleBoundsPadding.PaddingMask="All">
            <Grid Padding="12">
                <Grid.RowDefinitions>
                    <RowDefinition Height="Auto"/>
                    <RowDefinition Height="Auto"/>
                    <RowDefinition/>
                    <RowDefinition Height="Auto"/>
                    <RowDefinition/>
                </Grid.RowDefinitions>
                <!-- ROW 0 - Title -->
                <TextBlock Text="The Cat API Client" Style="{StaticResource HeaderTextBlockStyle}" />

                <!-- ROW 1 - Search Box -->

                <!-- ROW 2 - Search Results -->

                <!-- ROW 3 - Favorites Title -->
                <TextBlock Grid.Row="3" Text="Favorites" Style="{StaticResource SubheaderTextBlockStyle}" />

                <!-- ROW 4 - Favorites -->

                <!-- Busy Overlay -->

            </Grid>
        </Grid>
    </Page>
    ```

    This page utilizes a simple grid layout with 6 rows to separate the various areas of the UI and will define an overlay that will appear when the app is busy retrieving data from the service.

    Notice that the XAML includes namespace definitions for the **ViewModels** and **DataModels**, as well as the **Uno.UI.Toolkit**:

    ```xml
    <Page
        ...
        xmlns:viewmodels="using:TheCatApiClient.Models.ViewModels"
        xmlns:datamodels="using:TheCatApiClient.Models.DataModels"
        xmlns:toolkit="using:Uno.UI.Toolkit"
        ...
    >
    ```

    The Uno UI toolkit is added so that **toolkit:VisibleBoundsPadding** can be added - this ensures that the UI will adapt appropriately when the app is running on a device that has a "notch", etc.

    Also note how the view-model **MainViewModel** is instantiated and assigned as the **DataContext**. The view-model can then be referred to as **ViewModel** in the `x:Bind` expressions you will add shortly.

    ```xml
    <Page.DataContext>
        <viewmodels:MainViewModel x:Name="ViewModel" />
    </Page.DataContext>
    ```

1. To add the search box, locate the `<!-- ROW 1 - Search Box -->` comment and replace it with the following:

    ```xml
    <!-- ROW 1 - Search Box -->
    <AutoSuggestBox Grid.Row="1" PlaceholderText="Search for breed" QueryIcon="Find"
                    Name="BreedSearchBox"
                    Width="300" Margin="4,20" HorizontalAlignment="Left"
                    Text="{x:Bind ViewModel.SearchTerm, Mode=TwoWay}"
                    QuerySubmitted="BreedSearchBox_QuerySubmitted" />
    ```

    Notice that the **Text** property is bound to the **ViewModel.SearchTerm**. This value is updated when the search button is pressed, so it will be available when the **QuerySubmitted** event is raised.

1. To add the search results control, locate the `<!-- ROW 2 - Search Results -->` comment and replace it with the following:

    ```xml
    <!-- ROW 2 - Search Results -->
    <GridView Grid.Row="2" ItemsSource="{x:Bind ViewModel.SearchResults, Mode=OneWay}" Margin="4"
            SelectionMode="None">
        <GridView.ItemTemplate>
            <DataTemplate x:DataType="datamodels:Breed">
                <StackPanel Width="300" Padding="4">
                    <TextBlock Text="{x:Bind Name}" Style="{StaticResource TitleTextBlockStyle}"/>
                    <TextBlock Text="{x:Bind Description}" Style="{StaticResource BodyTextBlockStyle}" TextWrapping="WrapWholeWords"
                            Height="70" TextTrimming="CharacterEllipsis"/>
                </StackPanel>

            </DataTemplate>
        </GridView.ItemTemplate>
    </GridView>
    ```

    Notice that the **ItemsSource** property is bound to **ViewModel.SearchResults** and will be updated when the breed service search returns results.

    The **DataTemplate** used for each of the search result items is strongly-typed using `x:DataType="datamodels:Breed"`. This allows the two **TextBlock** controls to use `x:Bind` to reference the **Name** and **Description** propertied from the **Breed** class.

    You will add the favorites implementation in a later task.

1. To add an overlay for the UI that will be displayed when the service is retrieving data, locate the `<!-- Busy Overlay -->` comment and replace it with the following:

    ```xml
    <!-- Busy Overlay -->
    <Grid Background="Gray" Opacity="0.75" Visibility="{x:Bind ViewModel.IsBusy, Mode=OneWay}"
        Grid.Row="1" Grid.RowSpan="4">
        <TextBlock Text="Downloading data..." Style="{StaticResource TitleTextBlockStyle}" VerticalAlignment="Center" HorizontalAlignment="Center"/>
    </Grid>
    ```

    Notice that this grid is displayed from row 1 and spans 4 rows. As this grid is defined last, it will appear on top of the other controls, block click/touch interactions with the underlying controls as well showing a semi-opaque message that the app is **Downloading data**.

    ![Windows app Search UI preview](Assets/how-to-webservice/uwp-ui-busy.png)

    > [!NOTE]
    > You would typically use a **ProgressRing** here, but in an effort to keep the UI as simple as possible, this approach was taken.

1. When you have completed adding the XAML, it should look similar to this.

    ```xml
    <Page
        x:Class="TheCatApiClient.MainPage"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:TheCatApiClient"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:viewmodels="using:TheCatApiClient.Models.ViewModels"
        xmlns:datamodels="using:TheCatApiClient.Models.DataModels"
        xmlns:toolkit="using:Uno.UI.Toolkit"
        mc:Ignorable="d"
        Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

        <Page.DataContext>
            <viewmodels:MainViewModel x:Name="ViewModel" />
        </Page.DataContext>

        <Grid Margin="12">
            <Grid.RowDefinitions>
                <RowDefinition Height="Auto"/>
                <RowDefinition Height="Auto"/>
                <RowDefinition/>
                <RowDefinition Height="Auto"/>
                <RowDefinition/>
            </Grid.RowDefinitions>
            <!-- ROW 0 - Title -->
            <TextBlock Text="The Cat API Client" Style="{StaticResource HeaderTextBlockStyle}" />

            <!-- ROW 1 - Search Box -->
            <AutoSuggestBox Grid.Row="1" PlaceholderText="Search for breed" QueryIcon="Find"
                            Name="BreedSearchBox"
                            Width="300" Margin="4,20" HorizontalAlignment="Left"
                            Text="{x:Bind ViewModel.SearchTerm, Mode=TwoWay}"
                            QuerySubmitted="BreedSearchBox_QuerySubmitted" />

            <!-- ROW 2 - Search Results -->
            <GridView Grid.Row="2" ItemsSource="{x:Bind ViewModel.SearchResults, Mode=OneWay}" Margin="4"
                  SelectionMode="None">
                <GridView.ItemTemplate>
                    <DataTemplate x:DataType="datamodels:Breed">
                        <StackPanel Width="300" Padding="4">
                            <TextBlock Text="{x:Bind Name}" Style="{StaticResource TitleTextBlockStyle}"/>
                            <TextBlock Text="{x:Bind Description}" Style="{StaticResource BodyTextBlockStyle}" TextWrapping="WrapWholeWords"
                                   Height="70" TextTrimming="CharacterEllipsis"/>
                        </StackPanel>

                    </DataTemplate>
                </GridView.ItemTemplate>
            </GridView>

            <!-- ROW 3 - Favorites Title -->
            <TextBlock Grid.Row="3" Text="Favorites" Style="{StaticResource SubheaderTextBlockStyle}" />

            <!-- ROW 4 - Favorites -->

            <!-- Busy Overlay -->
            <Grid Background="Gray" Opacity="0.75" Visibility="{x:Bind ViewModel.IsBusy, Mode=OneWay}"
                Grid.Row="1" Grid.RowSpan="4">
                <TextBlock Text="Downloading data..." Style="{StaticResource TitleTextBlockStyle}" VerticalAlignment="Center" HorizontalAlignment="Center"/>
            </Grid>
        </Grid>
    </Page>
    ```

1. To add the code-behind handler for the **QuerySubmitted** event, switch to the code view by either opening **MainPage.xaml.cs** or by pressing the default keyboard shortcut **F7**.

1. Locate the **MainPage** constructor and add the following code beneath it:

    ```csharp
    private async void BreedSearchBox_QuerySubmitted(AutoSuggestBox sender, AutoSuggestBoxQuerySubmittedEventArgs args)
    {
        await ViewModel.SearchBreeds();
    }

    // Insert favorites below here
    ```

    This method simply calls the **SearchBreeds** method on the view-model.

1. You have now completed the implementation of a simple web service client. To run the application, press **F5**.

1. In the application, in the **Search for breed** search box, enter **S** and click the search icon.

    The **Downloading data...** UI should be shown and then the results should be populated. You should be able to scroll the results and select one (nothing will happen yet).

    ![Windows app Search UI preview](Assets/how-to-webservice/uwp-ui-preview.png)

1. When you have finished testing the Windows app, close it.

1. To test the app in Wasm, in the **Solution Explorer**, right-click the **TheCatApiClient.Wasm** project and select **Set as Startup project**.

1. To run the application, press **F5**.

    Visual Studio will open a browser and display the application.

1. In the application, in the **Search for breed** search box, enter **S** and click the search icon.

    The **Downloading data...** UI should be shown and then the results should be populated. You should be able to scroll the results and select one (nothing will happen yet).

    ![WebAssembly Search UI preview](Assets/how-to-webservice/wasm-ui-preview.png)

    Here is how the app looks running in the iPhone and Android simulators:

    ![Application running on iPhone and Android simulators](Assets/how-to-webservice/app-running-simulators.png)

Congratulations - you now have a cross-platform application that interacts with a web service using an HTTP GET operation. If you are interested in seeing how to implement additional operations, continue with the next tasks.

## Task 8 - Add new services to support favorites

In the previous tasks, you created a web service client and UI that performs a simple cat breed search. In this task you will add a service that leverages the favorites API. We will build a UI that will add a picture of a selected breed to your favorites when you click it in the search results, and will remove it from the favorites when you click it in the favorites list.

To achieve this, the **WebApiBase** class will updated be to include additional operations that support HTTP Post, Delete and Put verbs. You will then add two more services:

* **ImageApi** - returns a list of images for a given breed.
* **FavoritesApi** - supports adding and deleting an image from your favorites.

To support these services, 4 more data models will be added:

* **CatImage** - represents the results returned from the **GetByBreed** operation of the **ImageApi**.
* **Favorite** - represents the results returned from the **Get** and **GetAll** operations of the **FavoritesApi**.
* **FavoriteImage** - represents the image returned as part of a **Favorite** from the **FavoritesApi**.
* **Response** - represents a general result returned by the **Add** and **Delete** operations of the **FavoritesApi**.

You will start by adding the data models.

1. To create a simple model that represents the cat image search results, right-click the **DataModels** folder, select **Add** and click **Class...**

1. On the **Add New Item** dialog, in the **Name** field, enter **CatImage.cs**

1. In the editor, replace the content of the **CatImage.cs** class with the following:

    ```csharp
    using System;
    using System.Text.Json.Serialization;

    namespace TheCatApiClient.Models.DataModels
    {
        public partial class CatImage
        {
            [JsonPropertyName("id")]
            public string Id { get; set; }

            [JsonPropertyName("height")]
            public int Height { get; set; }

            [JsonPropertyName("url")]
            public string Url { get; set; }

            [JsonPropertyName("width")]
            public int Width { get; set; }
        }
    }
    ```

1. Repeat the above and add the **Favorite.cs** class, replacing the content with the following:

    ```csharp
    using System;
    using System.Text.Json.Serialization;

    namespace TheCatApiClient.Models.DataModels
    {
        public partial class Favorite
        {
            [JsonPropertyName("created_at")]
            public DateTime CreatedAt { get; set; }

            [JsonPropertyName("id")]
            public int Id { get; set; }

            [JsonPropertyName("image")]
            public FavoriteImage Image { get; set; }

            [JsonPropertyName("image_id")]
            public string ImageId { get; set; }

            [JsonPropertyName("sub_id")]
            public string SubId { get; set; }

            [JsonPropertyName("user_id")]
            public string UserId { get; set; }
        }
    }
    ```

1. Repeat the above and add the **FavoriteImage.cs** class, replacing the content with the following:

    ```csharp
    using System;
    using System.Text.Json.Serialization;

    namespace TheCatApiClient.Models.DataModels
    {
        public partial class FavoriteImage
        {
            [JsonPropertyName("id")]
            public string Id { get; set; }

            [JsonPropertyName("url")]
            public string Url { get; set; }
        }
    }
    ```

1. Repeat the above and add the **Response.cs** class, replacing the content with the following:

    ```csharp
    using System;
    using System.Text.Json.Serialization;

    namespace TheCatApiClient.Models.DataModels
    {
        public partial class Response
        {

            [JsonPropertyName("id")]
            public int Id { get; set; }

            [JsonPropertyName("message")]
            public string Message { get; set; }
        }
    }
    ```

1. To extend the **WebApiBase** class, open the **WebApiBase.cs** file in the editor.

1. To add support for the delete operation, locate the comment **// Insert DeleteAsync method below here** and replace it with the following code:

    ```csharp
    // Insert DeleteAsync method below here
    protected async Task<string> DeleteAsync(string url, Dictionary<string, string> headers = null)
    {
        using (var request = CreateRequestMessage(HttpMethod.Delete, url, headers))
        using (var response = await _client.SendAsync(request))
        {
            if (response.IsSuccessStatusCode)
            {
                return await response.Content.ReadAsStringAsync();
            }

            return null;
        }
    }
    ```

    The code is very similar to the **GetAsync** method added earlier, just using `HttpMethod.Delete`.

1. To add support for the post operation, locate the comment **// Insert PostAsync method below here** and replace it with the following code:

    ```csharp
    // Insert PostAsync method below here
    protected async Task<string> PostAsync(string url, string payload, Dictionary<string, string> headers = null)
    {
        using (var request = CreateRequestMessage(HttpMethod.Post, url, headers))
        {
            request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
            using (var response = await _client.SendAsync(request))
            {
                if (response.IsSuccessStatusCode)
                {
                    return await response.Content.ReadAsStringAsync();
                }

                return null;
            }
        }
    }
    ```

    The change for this method is the use of `HttpMethod.Post` and the addition of the **payload** parameter, which is added to the request as **StringContent**. Callers of this method will submit JSON as the payload - notice the encoding and MIME type specification.

1. To add support for the put operation, locate the comment **// Insert PutAsync method below here** and replace it with the following code:

    ```csharp
    // Insert PutAsync method below here
    protected async Task<string> PutAsync(string url, string payload, Dictionary<string, string> headers = null)
    {
        using (var request = CreateRequestMessage(HttpMethod.Put, url, headers))
        {
            request.Content = new StringContent(payload, Encoding.UTF8, "application/json");
            using (var response = await _client.SendAsync(request))
            {
                if (response.IsSuccessStatusCode)
                {
                    return await response.Content.ReadAsStringAsync();
                }

                return null;
            }
        }
    }
    ```

    Put is very similar to post. It is included here for completeness although we don't use it in this tutorial.

    Now you will add the additional services. The first service you will add is the **ImageApi**. If you recall, if the user clicks on a breed, this service will be used to retrieve a list of images of that breed.

1. To add a class for the Image API service, in the **TheCatApiClient** project, right-click the **WebServices** folder, select **Add** and click **Class...**

1. On the **Add New Item** dialog, in the **Name** field, enter **ImageApi.cs**

1. In the editor, replace the content of the **ImageApi.cs** class with the following:

    ```csharp
    using System.Collections.Generic;
    using System.Net;
    using System.Text.Json;
    using System.Threading.Tasks;
    using TheCatApiClient.Models.DataModels;

    namespace TheCatApiClient.WebServices
    {
        public class ImageApi : WebApiBase
        {
            private Dictionary<string, string> _defaultHeaders = new Dictionary<string, string> {
                {"accept", "application/json" },
                {"x-api-key", "{YOUR-API-KEY}"}
            };

            public async Task<IEnumerable<CatImage>> GetByBreed(string breedId)
            {
                var result = await this.GetAsync(
                    $"https://api.thecatapi.com/v1/images/search?breed_id={WebUtility.HtmlEncode(breedId)}",
                    _defaultHeaders);

                if (result != null)
                {
                    return JsonSerializer.Deserialize<IEnumerable<CatImage>>(result);
                }

                return new List<CatImage>();
            }

            public async Task<CatImage> GetById(string imageId)
            {
                var result = await this.GetAsync(
                    $"https://api.thecatapi.com/v1/images/{WebUtility.HtmlEncode(imageId)}",
                    _defaultHeaders);

                if (result != null)
                {
                    return JsonSerializer.Deserialize<CatImage>(result);
                }

                return null;
            }
        }
    }
    ```

    Notice that the default headers including your API key have been moved to **_defaultHeaders** to ease reuse.

    This service implements two methods - **GetByBreed** which returns back all images for a breed and **GetById**, which returns a specific image. They each utilize the **WebApiBase.GetAsync** method you used earlier.

    > [!TIP]
    > You can review the images service documentation here - [/images](https://docs.thecatapi.com/api-reference/images/)

1. To add a class for the Favorites API service, in the **TheCatApiClient** project, right-click the **WebServices** folder, select **Add** and click **Class...**

1. On the **Add New Item** dialog, in the **Name** field, enter **ImageApi.cs**

1. In the editor, replace the content of the **ImageApi.cs** class with the following:

    ```csharp
    using System.Collections.Generic;
    using System.Text.Json;
    using System.Threading.Tasks;
    using TheCatApiClient.Models.DataModels;

    namespace TheCatApiClient.WebServices
    {
        public class FavoritesApi : WebApiBase
        {
            private Dictionary<string, string> _defaultHeaders = new Dictionary<string, string> {
                {"accept", "application/json" },
                {"x-api-key", "{YOUR-API-KEY}"}
            };

            // Insert GetAll and Get below here

            // Insert Add below here

            // Insert Delete below here
            }
        }
    }
    ```

1. To add support for retrieving all of your favorites, or a specific favorite, locate the comment **// Insert GetAll and Get below here** and replace it with the following code:

    ```csharp
    // Insert GetAll and Get below here
    public async Task<IEnumerable<Favorite>> GetAll()
    {
        var result = await this.GetAsync(
            $"https://api.thecatapi.com/v1/favourites",
            _defaultHeaders);

        if (result != null)
        {
            return JsonSerializer.Deserialize<IEnumerable<Favorite>>(result);
        }

        return new List<Favorite>();
    }

    public async Task<Favorite> Get(int id)
    {
        var result = await this.GetAsync(
            $"https://api.thecatapi.com/v1/favourites/{id}",
            _defaultHeaders);

        if (result != null)
        {
            return JsonSerializer.Deserialize<Favorite>(result);
        }

        return null;
    }
    ```

    These methods are very similar to the methods you implemented earlier - **GetAll** returns a collection of the users **Favorite** instances, whereas **Get** returns a single **Favorite** by its ID.

    > [!TIP]
    > You can review the favorites service documentation here - [/favorites](https://docs.thecatapi.com/api-reference/favourites/)

1. To add support for adding an image to your favorites, locate the comment **// Insert Add below here** and replace it with the following code:

    ```csharp
    // Insert Add below here
    public async Task<Response> Add(CatImage image)
    {
        var result = await this.PostAsync(
            $"https://api.thecatapi.com/v1/favourites",
            JsonSerializer.Serialize(
                new Dictionary<string, string>
                {
                    { "image_id", image.Id },
                    { "sub_id", "uno-client" }
                }),
            _defaultHeaders);

        if (result != null)
        {
            return JsonSerializer.Deserialize<Response>(result);
        }

        return null;
    }
    ```

    In order to add an image to your favorites, the API expects a JSON payload that contains the image ID and an optional **sub_id** value. The **Add** methods constructs this using a **Dictionary** that is then serialized to JSON and submitted as the payload. Rather than returning a **Favorite**, it returns a **Response** instance which contains the new Favorite ID.

1. To add support for deleting an image from your favorites, locate the comment **// Insert Delete below here** and replace it with the following code:

    ```csharp
    // Insert Delete below here
    public async Task<Response> Delete(Favorite favorite)
    {
        var result = await this.DeleteAsync(
            $"https://api.thecatapi.com/v1/favourites/{favorite.Id}",
            _defaultHeaders);

        if (result != null)
        {
            return JsonSerializer.Deserialize<Response>(result);
        }

        return null;
    }
    ```

    In order to delete an image from your favorites, the API expects a JSON payload that contains the favorite ID value. The **Delete** method submits the favorite ID value in the url. The method returns a **Response** instance.

1. The implementation of **FavoritesApi** should look similar to:

    ```csharp
    using System.Collections.Generic;
    using System.Text.Json;
    using System.Threading.Tasks;
    using TheCatApiClient.Models.DataModels;

    namespace TheCatApiClient.WebServices
    {
        public class FavoritesApi : WebApiBase
        {
            private Dictionary<string, string> _defaultHeaders = new Dictionary<string, string> {
                {"accept", "application/json" },
                {"x-api-key", "{YOUR-API-KEY}"}
            };

            // Insert GetAll and Get below here
            public async Task<IEnumerable<Favorite>> GetAll()
            {
                var result = await this.GetAsync(
                    $"https://api.thecatapi.com/v1/favourites",
                    _defaultHeaders);

                if (result != null)
                {
                    return JsonSerializer.Deserialize<IEnumerable<Favorite>>(result);
                }

                return new List<Favorite>();
            }

            public async Task<Favorite> Get(int id)
            {
                var result = await this.GetAsync(
                    $"https://api.thecatapi.com/v1/favourites/{id}",
                    _defaultHeaders);

                if (result != null)
                {
                    return JsonSerializer.Deserialize<Favorite>(result);
                }

                return null;
            }

            // Insert Add below here
            public async Task<Response> Add(CatImage image)
            {
                var result = await this.PostAsync(
                    $"https://api.thecatapi.com/v1/favourites",
                    JsonSerializer.Serialize(new Dictionary<string, string> { { "image_id", image.Id }, { "sub_id", "uno-client" } }),
                    _defaultHeaders);

                if (result != null)
                {
                    return JsonSerializer.Deserialize<Response>(result);
                }

                return null;
            }

            // Insert Delete below here
            public async Task<Response> Delete(Favorite favorite)
            {
                var result = await this.DeleteAsync(
                    $"https://api.thecatapi.com/v1/favourites/{favorite.Id}",
                    _defaultHeaders);

                if (result != null)
                {
                    return JsonSerializer.Deserialize<Response>(result);
                }

                return null;
            }
        }
    }
    ```

Now that the services are complete, it is time to update the UI.

## Task 9 - Add favorites to the UI view model

In this task, you will add the favorites capability to the Main view-model.

1. Open the **MainViewModel.cs** file in the editor.

1. To add the variables, property and method placeholders for the favorites implementation, locate the **// Insert Favorites below here** comment and replace it with the following code:

    ```csharp
    // Insert Favorites below here
    private ImageApi _imageApi = new ImageApi();
    private FavoritesApi _favoritesApi = new FavoritesApi();
    private ObservableCollection<Favorite> _favorites = new ObservableCollection<Favorite>();

    public ObservableCollection<Favorite> Favorites
    {
        get => _favorites;
        set => SetProperty(ref _favorites, value);
    }

    // Insert LoadFavorites below here

    // Insert AddFavorite below here

    // Insert DeleteFavorite below here
    ```

    This code creates the API services and the collection that will hold the user's favorites.

1. To add the method that retrieves the current user favorites, locate the **// Insert LoadFavorites below here** comment and replace it with the following code:

    ```csharp
    // Insert LoadFavorites below here
    public async Task LoadFavorites()
    {
        try
        {
            IsBusy = true;
            var result = await _favoritesApi.GetAll().ConfigureAwait(false);
            if (result.Any())
            {
                Favorites = new ObservableCollection<Favorite>(result);
            }
        }
        finally
        {
            IsBusy = false;
        }
    }
    ```

    This method is virtually identical to the **SearchBreeds** method that you created earlier.

1. To implement support for adding an image to favorites, locate the **// Insert AddFavorite below here** comment and replace it with the following code:

    ```csharp
    // Insert AddFavorite below here
    public async Task AddFavorite(Breed selectedBreed)
    {
        if (selectedBreed != null)
        {
            try
            {
                IsBusy = true;
                var result = await _imageApi.GetByBreed(selectedBreed.Id).ConfigureAwait(false);
                if (result.Any())
                {
                    var image = result.First();
                    var response = await _favoritesApi.Add(image).ConfigureAwait(false);

                    if (response != null && response.Message == "SUCCESS")
                    {
                        var favoriteResult = await _favoritesApi.Get(response.Id).ConfigureAwait(false);
                        if (favoriteResult != null)
                        {
                            await DispatchAsync(() => Favorites.Insert(0, favoriteResult)).ConfigureAwait(false);
                        }
                    }
                }
            }
            finally
            {
                IsBusy = false;
            }
        }
    }
    ```

    There is a bit more going on in this method, but it follows a familiar pattern. If we have a **selectedBreed**, we set the **IsBusy** property and then use the **ImageApi** to retrieve a collection of images for the breed. If we find any (some breeds don't have images... you would show a message in a production app), we just grab the first image that is returned. We then call the **FavoritesApi** to add the image. We then check the **response** value and, if successful, use the ID that was returned via the **response** to retrieve the new **Favorite**. We then insert the favorite at the beginning of our **Favorites** collection.

    You should notice the use of the `.ConfigureAwait(false)` code throughout to ensure the UI is not blocked. You will also notice the use of the **DispatchAsync** helper to ensure the **CollectionChanged** event raised by the insertion is raised on the UI thread so any bound control updates correctly.

1. Finally, to add support for deleting a favorite, locate the **// Insert DeleteFavorite below here** comment and replace it with the following code:

    ```csharp
    // Insert DeleteFavorite below here
    public async Task DeleteFavorite(Favorite selectedFavorite)
    {
        if (selectedFavorite != null)
        {
            try
            {
                IsBusy = true;
                var result = await _favoritesApi.Delete(selectedFavorite).ConfigureAwait(false);
                if (result.Message != null)
                {
                    await DispatchAsync(() => Favorites.Remove(selectedFavorite)).ConfigureAwait(false);
                }
            }
            finally
            {
                IsBusy = false;
            }
        }
    }
    ```

    Similar to the flow of the **AddFavorite** method, this implementation calls the delete operation, and then this time removes the **selectedFavorite** from thee **Favorites** collection.

You have now updated the view-model - the final task will have you update the UI to include the favorites.

## Task 10 - Add favorites to the main view

In this final task, you will bring together the new **FavoritesApi** with the updated **MainViewModel** to add a list of favorites to the UI.

1. In the **Solution Explorer**, in the **TheCatApiClient** project, open the **MainPage.xaml** file.

1. If the **MainPage.xaml** file has opened in the **Design** view, switch to the **XAML** view.

1. To add support for clicking a breed in the search results, locate the `<!-- ROW 2 - Search Results -->` comment and replace all of the row 2 XAML with the following:

    ```xml
    <!-- ROW 2 - Search Results -->
    <GridView Grid.Row="2" ItemsSource="{x:Bind ViewModel.SearchResults, Mode=OneWay}" Margin="4"
            SelectionMode="None"
            IsItemClickEnabled="True"
            ItemClick="SearchResults_ItemClick">
        <GridView.ItemTemplate>
            <DataTemplate x:DataType="datamodels:Breed">
                <StackPanel Width="300" Padding="4">
                    <TextBlock Text="{x:Bind Name}" Style="{StaticResource TitleTextBlockStyle}"/>
                    <TextBlock Text="{x:Bind Description}" Style="{StaticResource BodyTextBlockStyle}" TextWrapping="WrapWholeWords"
                            Height="70" TextTrimming="CharacterEllipsis"/>
                </StackPanel>

            </DataTemplate>
        </GridView.ItemTemplate>
    </GridView>
    ```

    Notice that two attributes have been added to the **GridView** - **IsItemClickEnabled** configures the **GridView** to raise ItemClick events (by default this is disabled) and then the **ItemClick** event is directed to the code-behind. You will add the code-behind implementation shortly.

1. To add the favorites list, locate the `<!-- ROW 4 - Favorites -->` comment and replace it with the following XAML:

    ```xml
    <!-- ROW 4 - Favorites -->
    <GridView Grid.Row="4" ItemsSource="{x:Bind ViewModel.Favorites, Mode=OneWay}" Margin="4"
            SelectionMode="None"
            Name="Favorites"
            IsItemClickEnabled="True"
            ItemClick="Favorites_ItemClick">
        <GridView.ItemTemplate>
            <DataTemplate x:DataType="datamodels:Favorite">
                <Grid Padding="4" Height="100" Width="100" Background="#EEEEEE">
                    <Image Source="{x:Bind Image.Url}" Stretch="Uniform"/>
                </Grid>
            </DataTemplate>
        </GridView.ItemTemplate>
    </GridView>
    ```

    This **GridView** is configured in a similar way to the search results - item click is enabled with a code-behind handler, etc. The primary differences are that **ItemsSource** is bound to the **ViewModel.Favorites** property, the data template is bound to the **Favorite** data model and the template displays an image.

    That's it for the XAML. Now to update the code-behind.

1. To add the code-behind functionality for favorites, switch to the code view by either opening **MainPage.xaml.cs** or by pressing the default keyboard shortcut **F7**.

1. Locate the **// insert favorites below here** comment and and replace it with the following code:

    ```csharp
    // insert favorites below here
    private async void Favorites_ItemClick(object sender, ItemClickEventArgs e)
    {
        await ViewModel.DeleteFavorite((Favorite)e.ClickedItem);
    }

    private async void SearchResults_ItemClick(object sender, ItemClickEventArgs e)
    {
        await ViewModel.AddFavorite((Breed)e.ClickedItem);
    }
    ```

    These methods are very straightforward - they merely pass on the clicked item to the view-model.

1. You have now completed the addition of favorites to the client. In the **Solution Explorer**, right-click the **TheCatApiClient.Windows** project and select **Set as Startup project**.

1. To run the Windows application, press **F5**.

1. In the application, in the **Search for breed** search box, enter **S** and click the search icon.

    The **Downloading data...** UI should be shown and then the results should be populated. You should be able to scroll the results and select one (nothing will happen yet).

    ![Windows app Search UI preview](Assets/how-to-webservice/uwp-ui-preview.png)

1. In the search results, click **Abyssinian** and you should see an image of a cat added to the **Favorites** list.

    ![Windows app Search UI preview](Assets/how-to-webservice/client-with-favorite.png)

1. Repeat the above, adding images for other breeds.

1. In the **Favorites** list, click an image and you should see it be removed.

1. Ensure you have one or more images remaining in your **Favorites** list and exit the Windows application.

1. To test the app in Wasm, in the **Solution Explorer**, right-click the **TheCatApiClient.Wasm** project and select **Set as Startup project**.

1. To run the application, press **F5**.

    Visual Studio will open a browser and display the application. You should see the same favorites you had listed in the Windows app.

1. Search for additional breeds and add and remove favorites - you should see the same functionality as the Windows app.

1. Try the app on other platforms. Below is an image of the app running on iPhone and Android simulators.

    ![Application running on iPhone and Android simulators](Assets/how-to-webservice/favorites-on-phone.png)

## Summary

In this how-to, you built a multi-platform application that leverages web services. Specifically you:

* Created a simple Uno application
* Registered and obtained a key for The Cat API web service.
* Built a number of data models that utilize JSON serialization
* Built a web service base class that supports REST service operations and then implemented a number of services that derived from it
* Leveraged the services in a view-model
  * You built a base class that uses the dispatcher to ensure bound properties are updated on the UI thread
* Built a XAML UI that utilizes the view-model
* Tested the application in Windows and WASM (and optionally on iOS and Android)

The full source code for this tutorial is available here - [Tutorial Source Code - TheCatApiClient](https://github.com/unoplatform/Uno.Samples/tree/master/UI/TheCatApiClient)

## References

* Uno Platform:
  * [Using Uno - getting started on Visual Studio](https://platform.uno/docs/articles/get-started-vs.html)
* Uno Platform Samples:
  * [unoplatform/Uno.Samples](https://github.com/unoplatform/Uno.Samples)
  * [Tutorial Source Code - TheCatApiClient](https://github.com/unoplatform/Uno.Samples/tree/master/UI/TheCatApiClient)
* Microsoft Documentation
  * [HttpClient class](https://learn.microsoft.com/dotnet/api/system.net.http.httpclient)
  * [REST Client tutorial](https://learn.microsoft.com/dotnet/csharp/tutorials/console-webapiclient)
  * [How to serialize and deserialize (marshal and unmarshal) JSON in .NET](https://learn.microsoft.com/dotnet/standard/serialization/system-text-json-how-to)
  * [HttpClient Remarks](https://learn.microsoft.com/dotnet/api/system.net.http.httpclient#remarks)
  * [HttpClient - Error handling, a test driven approach](https://josef.codes/httpclient-error-handling-a-test-driven-approach/)
  * [The Model-View-ViewModel Pattern](https://learn.microsoft.com/xamarin/xamarin-forms/enterprise-application-patterns/mvvm)
  * [Keep the UI thread responsive](https://learn.microsoft.com/windows/uwp/debug-test-perf/keep-the-ui-thread-responsive)
  * [Reserved attributes: Determine caller information](https://learn.microsoft.com/dotnet/csharp/language-reference/attributes/caller-information)
  * [Lambda expressions](https://learn.microsoft.com/dotnet/csharp/language-reference/operators/lambda-expressions)
  * [ObservableCollection<T> Class](https://learn.microsoft.com/dotnet/api/system.collections.objectmodel.observablecollection-1)
* The Cat API Documentation
  * [Key sign-up](https://thecatapi.com/signup)
  * [API documentation](https://docs.thecatapi.com/)
  * [GET /breeds/search](https://docs.thecatapi.com/api-reference/breeds/breeds-search)
  * [/images](https://docs.thecatapi.com/api-reference/images/)
  * [/favorites](https://docs.thecatapi.com/api-reference/favourites/)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/howto-migrate-existing-code.md

---
uid: Uno.Development.MigrateExistingCode
---

# Migrating single-platform WinUI code to Uno

Uno Platform takes WinUI code and makes it run on almost any target platform. If you have an existing application or library that was written to target WinUI, you'll find guidance here for converting it to a cross-platform codebase, using WinUI to target Windows 10 and Uno Platform to target other platforms. Depending on the APIs your code uses, it may run with minimal modifications, or you may need to add [platform-specific code](platform-specific-csharp.md) to cover missing functionality.

The articles in this guide cover:

- Initial [checklist](migrating-before-you-start.md)
- Steps for [migrating an application](migrating-apps.md)
- Steps for [migrating a class library](migrating-libraries.md)
- [General guidance](migrating-guidance.md) for converting WinUI-only code to Uno-compatible code

See also the [guide to working with Control Class Libraries](xref:Guide.HowTo.Create-Control-Library).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/image.md

---
uid: Uno.Features.Image
---

# The Image Control

This page details the specific aspects of the `Image` control for Uno Platform. General information about `Image` is available in WinUI [official documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.image).

## Support for `ms-appx`

`ms-appx` supports reading images provided as `Content` assets in your project. See [`StorageFile.GetFileFromApplicationUriAsync`](xref:Uno.Features.FileManagement#support-for-storagefilegetfilefromapplicationuriasync) for more details.

## Support for `ms-appdata`

[`ms-appdata:///`](hhttps://learn.microsoft.com/windows/uwp/app-resources/uri-schemes#path-ms-appdata) supports reading content from the some known folders of an app.

For instance, these are paths which can be used to show images:

- `ms-appdata:///local/myimage.png`, using the path from `ApplicationData.Current.LocalFolder`
- `ms-appdata:///temp/myimage.png`, using the path from `ApplicationData.Current.TemporaryFolder`
- `ms-appdata:///roaming/myimage.png`, using the path from `ApplicationData.Current.RoamingFolder`

Files written at those locations will be shown in the `Image` control.

Here's a simple example:

```csharp
var httpClient = new HttpClient();
var response = await httpClient.GetAsync("https://fakeimg.pl/300/");

var file = await ApplicationData.Current.LocalFolder.CreateFileAsync("image.jpg", CreationCollisionOption.ReplaceExisting);
using (var stream = await file.OpenStreamForWriteAsync())
{
    await response.Content.CopyToAsync(stream);
}

MyImage.UriSource = new BitmapImage { UriSource = new($"ms-appdata:///local/image.jpg") };
```

> [!IMPORTANT]
> When using WinAppSDK Unpackaged mode, `ms-appdata:///` is not supported on `Image`. In this case, you can use [`BitmapImage.SetSourceAsync`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.imaging.bitmapsource.setsourceasync) to set the image programmatically.

## Gif Support

Displaying animated GIFs is supported on:

- netX.0-desktop (5.4 and later)
- netX.0-windows
- netX.0-browserwasm

Unsupported targets, where only the first frame is shown, as of Uno Platform 5.4:

- netX.0-ios
- netX.0-android

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/contributing/guidelines/implementing-a-new-winui-winrt-feature.md

---
uid: Uno.Contributing.ImplementWinUIWinRTAPI
---

# Guidelines for implementing a new WinUI/WinRT API

Implementing a new WinUI/WinRT API generally requires:

- Finding the generated API source file (e.g. `src\Uno.UWP\Generated\3.0.0.0\Windows.Data.Pdf\PdfDocument.cs`).
- Copying the file to the non-generated location (e.g. `src\Uno.UWP\Data.Pdf\PdfDocument.cs`).
- Keeping only the members that need to be implemented in the non-generated location.
- Removing (completely or partially depending on the platforms) the implemented members in the generated file.

If your API implementation is for a specific platform:

- You can use a platform suffix in the source file name (`PdfDocument.Android.cs`) so the file is built only for this platform.
- Remove the parts that relate to your platform in the `NotImplemented` attribute:

    ```csharp
    #if __ANDROID__ || __IOS__ || __TVOS__ || IS_UNIT_TESTS || __WASM__ || __SKIA__ || __NETSTD_REFERENCE__
    [global::Uno.NotImplemented("__ANDROID__", "__IOS__", "__TVOS__", "IS_UNIT_TESTS", "__WASM__", "__SKIA__", "__NETSTD_REFERENCE__")]
    public  global::Windows.Data.Pdf.PdfPageDimensions Dimensions
    {
    #endif
    ```

    becomes

    ```csharp
    #if false || __IOS__ || __TVOS__ || IS_UNIT_TESTS || __WASM__ || __SKIA__ || __NETSTD_REFERENCE__
    [global::Uno.NotImplemented("__IOS__", "__TVOS__", "IS_UNIT_TESTS", "__WASM__", "__SKIA__", "__NETSTD_REFERENCE__")]
    public  global::Windows.Data.Pdf.PdfPageDimensions Dimensions
    {
    #endif
    ```

    when implemented for Android only.

When implementing a feature, try to place as much code as possible in a common source file (a non-suffixed file), so that it is reused across platforms. Make sure to follow [partial classes coding guidelines](code-style.md).

Note that the generated files may be overridden at any point, and placing custom code (aside from changing the `NotImplemented` values) will be overwritten.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/interaction-tracker-internals.md

# InteractionTracker internals

This document tries to detail and clarify the implementation of InteractionTracker.

The interaction tracker has four states:

1. Idle
2. Interacting
3. Inertia
4. CustomAnimation

Currently, custom animation is not yet implemented. The transitioning between states is well-explained in [InteractionTracker Class | Microsoft Learn](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.composition.interactions.interactiontracker).

This document is going to focus on the Inertia state. The core calculations for this state are in `AxisHelper` nested class (in `InteractionTrackerInertiaHandler.AxisHelper.cs` file).

First, there are two things we need to early calculate:

1. The position distance we will move
1. The total inertia time (i.e, the time we stay in inertia state before transitioning to idle, which also is the time it takes for the position to be constant)

> [!NOTE]
> All mentions of decay rates below are `1 - PositionInertiaDecayRate`, unless `PositionInertiaDecayRate` is explicitly written.

## Position distance to move

This is about the "natural" distance, i.e, not taking into account MinPosition/MaxPosition constraints.

The core important equation of this is:

```csharp
float val = MathF.Pow(DecayRate, time);
return ((val - 1.0f) * InitialVelocity) / MathF.Log(DecayRate);
```

This equation represents the position of an object undergoing exponential decay over time.

Normally, the exponential decay is represented by `DecayRate ^ t`. This equation, however, is more about a "rate of change" in position. So, to get the position, we integrate that.

The integration of `DecayRate ^ t` is `(DecayRate ^ t) / ln(DecayRate)`.

However, we want the distance to be zero at time t = zero. Note that at time t = 0 the numerator is `DecayRate ^ 0` which is `1`. So, we subtract one.

The formula is now `x(t) = ((DecayRate ^ t) - 1) / ln(DecayRate)`. One last important thing that affects the distance is the initial velocity.

For a given decay rate and a given time, the effect of initial velocity is linear. So, we multiply the initial velocity. That is the final formula.

Now, let's visualize this by looking at a graph (assuming initial velocity = 60):

![image](https://github.com/unoplatform/uno/assets/31348972/2e76c554-2299-4ad1-8917-144d01978915)

You can see the position distance at time zero is always zero, and at the beginning it's exponentially growing until it settles down to its final value.

## Total inertia time (`TimeToMinimumVelocity`)

The core important equation of this is:

```csharp
return (MathF.Log(minimumVelocity) - MathF.Log(initialVelocity)) / MathF.Log(decayRate);
```

Note that as we have exponential decay, the final velocity is calculated as `v_f = v_i * r^t`, where:

- `v_f`: final velocity
- `v_i`: initial velocity
- `r`: decay rate
- `t`: time

To get the time:

1. `v_f / v_i = r^t`
1. `ln(v_f / v_i) = ln(r^t)`
1. `ln(v_f) - ln(v_i) = t ln(r)`
1. `t = (ln(v_f) - ln(v_i)) / ln(r)`

Currently, we fix the final velocity `v_f` to 30 px/sec, and call that `minimumVelocity`.

Note that the expression above will produce negative value if initialVelocity < minimumVelocity. So, in `GetTimeToMinimumVelocity`, if initialVelocity <= minimumVelocity, we return zero. The following graph visualizes the expression:

![image](https://github.com/unoplatform/uno/assets/31348972/958b0e92-d268-4229-810d-b38609eff4e0)

The red curve corresponds to decay rate 0.7, and the green one corresponds to decay rate 0.9. The x-axis is the initial velocity, and the y-axis is `TimeToMinimumVelocity`.

Note that in both cases, the intersection with x-axis is the minimum velocity. The higher the decay rate, the more `TimeToMinimumVelocity`. Again, decay rate mentioned here is `1 - PositionInertiaDecayRate`.
So, actually as `PositionInertiaDecayRate` gets larger, the time gets smaller.

## Generalized position calculation

Earlier, we concluded that `x(t) = InitialVelocity * ((DecayRate ^ t) - 1) / ln(DecayRate)`. This works well if "overpanning" isn't taken into account.
The overpanning happens when, in interacting state, the user active input goes beyond the restrictions of MinPosition and MaxPosition.

Two cases where this can happen:

1. In Interacting state, the active input caused Position to be out of the specified range. That is, when we switch from Interacting to Idle, the position is already out of the specified range.
2. Interacting state is left with high velocity that causes the calculation in Inertia state to calculate natural distance out of the MinPosition/MaxPosition range.

In this case, once we have a value outside of the range while in inertia, we want to bring it back. For that, we use a damping animation.

In WinUI, underdamped animation is used, and potentially critically-damped animation is also used for low velocities.

The current Uno implementation is more simple, using only critically-damped animation.

So, once we get a value outside of the range in inertia, we set `_dampingStateTimeInSeconds` to the current elapsed time, and set `_dampingStatePosition` to the current position. These values will be used in future `GetPosition` calls.

Basically, we want the animation to settle in the *remaining* time, i.e, `TimeToMinimumVelocity - _dampingStateTimeInSeconds.Value`.

The following graph shows the critical damping equation with time being the x-axis. As you see, it starts from value of 0 until it settles to 1, and the settling time is approximately `5.8335 / w`.

The settling time above is the 2% criterion, defined as "the time required for the response curve to reach and stay within 2% of the final value". The position calculation is then done by:

```csharp
value * (FinalModifiedValue - _dampingStatePosition!.Value) + _dampingStatePosition.Value
```

where `value` is the result of the critically damped equation.

Note that at the beginning when `value` is zero, we get `_dampingStatePosition`, then as time goes on and we reach 1, we get `FinalModifiedValue`, where `FinalModifiedValue` is the natural position clamped between `MinPosition` and `MaxPosition`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/intro.md

---
uid: Uno.Documentation.Intro
---

# Uno Platform Documentation

<!-- markdownlint-disable MD001 -->

**Uno Platform** is an open-source .NET platform that enables developers to quickly build native mobile, web, desktop, and embedded applications—all from a single codebase.

<br/>

<div class="row">

<!-- Get Started -->
<div class="col-md-6 col-xs-12 ">
<a href="get-started.md">
<div class="alert alert-info alert-hover">

#### Get Started

Set up with your OS and IDE of choice.

</div>
</a>
</div>

<!-- How-tos and Tutorials -->
<div class="col-md-6 col-xs-12 ">
<a href="samples-tutorials-overview.md">
<div class="alert alert-info alert-hover">

#### How-Tos and Tutorials

Four complete tutorials and hundreds of real-world samples.

</div>
</a>
</div>

<!-- Developing with Uno Platform -->
<div class="col-md-6 col-xs-12 ">
<a href="using-uno-ui.md">
<div class="alert alert-info alert-hover">

#### Developing with Uno Platform

Learn the principles of cross-platform development with Uno.

</div>
</a>
</div>

<!-- Uno Platform Studio -->
<div class="col-md-6 col-xs-12 ">
<a href="xref:Uno.Platform.Studio.Overview">
<div class="alert alert-info alert-hover">

#### Uno Platform Studio

**Uno Platform Studio** is a set of productivity tools designed to enhance developer productivity.

</div>
</a>
</div>

<!-- C# Markup -->
<div class="col-md-6 col-xs-12 ">
<a href="xref:Uno.Extensions.Markup.Overview">
<div class="alert alert-info alert-hover">

#### C# Markup

Write UI using C# instead of XAML

</div>
</a>
</div>

<!-- MVUX -->
<div class="col-md-6 col-xs-12 ">
<a href="xref:Uno.Extensions.Mvux.Overview">
<div class="alert alert-info alert-hover">

#### MVUX

Reactive programming with Uno Platform

</div>
</a>
</div>

<!-- Uno Toolkit -->
<div class="col-md-6 col-xs-12 ">
<a href="xref:Toolkit.GettingStarted">
<div class="alert alert-info alert-hover">

#### Uno Toolkit

Include new advanced UI controls

</div>
</a>
</div>

<!-- Figma -->
<div class="col-md-6 col-xs-12 ">
<a href="xref:Uno.Figma.GetStarted">
<div class="alert alert-info alert-hover">

#### Figma

Design your app in Figma and easily import to XAML or C#

</div>
</a>
</div>

<!-- Uno Themes -->
<div class="col-md-6 col-xs-12 ">
<a href="external/uno.themes/doc/themes-overview.md">
<div class="alert alert-info alert-hover">

#### Uno Themes

Use Material theme in your app

</div>
</a>
</div>

<!-- Uno Extensions -->
<div class="col-md-6 col-xs-12 ">
<a href="external/uno.extensions/doc/ExtensionsOverview.md">
<div class="alert alert-info alert-hover">

#### Uno Extensions

Include large building blocks to complete your app faster

</div>
</a>
</div>

<!-- API Reference -->
<div class="col-md-6 col-xs-12 ">
<a href="implemented-views.md">
<div class="alert alert-info alert-hover">

#### API Reference

Browse the set of available controls and their properties.

</div>
</a>
</div>

</div>

<br/>

## High Level Architecture

Uno Platform's application API is compatible with Microsoft's [WinUI 3 API](https://learn.microsoft.com/windows/apps/winui/winui3/). In fact, when your application runs on Windows, it's just an ordinary WinUI 3/WinAppSDK application.

This means that existing WinUI code is compatible with Uno Platform. Existing WinUI libraries can be recompiled for use in Uno Platform applications. A number of [3rd-party libraries](xref:Uno.Development.SupportedLibraries) have been ported to Uno Platform.

![High-level architecture diagram - WinUI on Windows, Uno.UI on other platforms](Assets/high-level-architecture-diagram.png)

Uno Platform is pixel-perfect by design, delivering consistent visuals on every platform. At the same time, it can either use the [native UI framework](xref:uno.features.renderer.native) on some target platforms or use a [Skia-based rendering](xref:uno.features.renderer.skia) approach, while making it easy to [integrate native views](xref:Uno.Development.NativeViews) and tap into native platform features.

Learn more about [how Uno Platform works](xref:Uno.Development.HowItWorks).

## Next Steps

Once you've gone through our [Get Started](get-started.md) guides, please visit our [GitHub Discussions](https://github.com/unoplatform/uno/discussions) where our team and community will be able to help you.
<br/>
<br/>

---

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/contributing/guidelines/issue-triage.md

---
uid: Uno.Contributing.IssueTriage
---

# Guidelines for issue triage

## Purpose

Speed up issue management.

The detailed list of labels can be found at <https://github.com/unoplatform/uno/labels>.

While working on triaging issues, you may not have the privilege to assign a specific label and in that case add a comment in the issue with your findings.

Here are a few predetermined searches on issues for convenience:

* [Longest un-triaged issues](https://github.com/unoplatform/uno/issues?q=is%3Aissue+is%3Aopen+sort%3Acreated-asc) (sorted by age)
* [Newest incoming issues](https://github.com/unoplatform/uno/issues?q=is%3Aopen+is%3Aissue)
* [Busy un-triaged issues](https://github.com/unoplatform/uno/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-desc) (sorted by number of comments)
* [Issues that need more attention](https://github.com/unoplatform/uno/issues?q=is%3Aissue+is%3Aopen+sort%3Acomments-asc)

## Scope

These guidelines serves as a primary document for triaging incoming issues to Uno. Maintainers and contributors are encouraged to either use these guidelines, or use this as a starting point if necessary.

## Security

Security-related matters should be disclosed in private as per [our policy on GitHub](https://github.com/unoplatform/uno/security/policy). If a security matter is raised as an issue, please capture the relevant information, [delete the GitHub issue](https://docs.github.com/issues/tracking-your-work-with-issues/deleting-an-issue), and follow up via email. This [tool can be used to find](https://emailaddress.github.io/) (almost) any GitHub user's email address.

## Support requests

These issues should be directed to our support structures (see below) and then closed _but_ before doing so consider why the support request was raised.

Is something unclear? Do we need to improve our documentation or samples?

Community support requests should be directed to:

* Our [documentation](https://platform.uno/docs/) and [troubleshooting guide](xref:Uno.UI.CommonIssues).
* [GitHub Discussions](https://github.com/unoplatform/uno/discussions)
* The [Discord Server](https://platform.uno/discord)
* On [X/Twitter using the #unoplatform](https://x.com/search?q=%23unoplatform) hashtag.

Organizations that want a deeper level of support beyond community support should be directed to [contact Uno Platform](https://platform.uno/contact/) to discuss obtaining professional support.

## Validate if the issue is a bug

Confirm if the problem is a bug by reproducing it. If a test case has not been supplied, ask the reporter to supply one. You may need to contact the issue reporter in the following cases:

* Do a quick duplicate search to see if the issue has been reported already. If a duplicate is found, let the issue reporter know it by marking it duplicate. Label such issues as `triage/duplicate`.
* If you can not reproduce the issue, label it as a `triage/not-reproducible`. Contact the issue reporter with your findings and close the issue if both the parties agree that it could not be reproduced.
* If you need more information to further work on the issue, let the reporter know it by adding an issue comment followed by label `triage/needs-information`.

In all cases, if you do not get a response in 20 days, then close the issue with an appropriate comment.

## Closing issues

Issues that are identified as a support request, duplicate, not-reproducible, or lacks enough information from reporter should be closed using the following guidelines explained in this file. Also, any issues that can not be resolved because of any particular reason should be closed. These issues should have one or more of following self-readable labels:

* `triage/duplicate`: Indicates an issue is a duplicate of other open issue.
* `triage/not-reproducible`: Indicates an issue can not be reproduced as described.
* `triage/needs-information`: Indicates an issue needs more information in order to work on it.

## Help Wanted issues

We use two labels [help wanted](https://github.com/unoplatform/uno/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22+sort%3Aupdated-desc) and [good first issue](https://github.com/unoplatform/uno/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22+sort%3Aupdated-desc) to identify issues that have been specially curated for new contributors.

The `good first issue` label is a subset of `help wanted` label, indicating that members have committed to providing extra assistance for new contributors. All `good first issue` items also have the `help wanted` label.

Items marked with the `good first issue` label are intended for _first-time
contributors_. It indicates that members will keep an eye out for these pull
requests and shepherd them through our processes.

**New contributors should not be left to find an approver, ping for reviews, or identify that their build failed due to a flake.**

This makes new contributors feel welcome, valued, and assures them that they will have an extra level of help with their first contribution.

After a contributor has successfully completed 1-2 `good first issue`'s, they should be ready to move on to `help wanted` items, saving remaining `good first issue`'s for other new contributors.

These items need to ensure that they follow the guidelines for `help wanted` labels (above) in addition to meeting the following criteria:

* **No Barrier to Entry**

  The task is something that a new contributor can tackle without advanced setup, or domain knowledge.

* **Solution Explained**

  The recommended solution is clearly described in the issue.

* **Provides Context**

  If background knowledge is required, this should be explicitly mentioned and a list of suggested readings included.

* **Gives Examples**

  Link to examples of similar implementations so new contributors have a reference guide for their changes.

* **Identifies Relevant Code**

  The relevant code and tests to be changed should be linked in the issue.

* **Ready to Test**

  There should be existing tests that can be modified, or existing test cases fit to be copied. If the area of code doesn't have tests, before labelling the issue, add a test fixture. This prep often makes a great `help wanted` task!

## Quick Replies

When commenting on an issue or pull request, there's a [feature in GitHub](https://help.github.com/en/articles/using-saved-replies) where you can add a saved reply that you've already set up. The saved reply can be the entire comment or if you want to customize it, you can add or delete content. Below you'll find some suggestions that maintainers and contributors can use as a starting point.

### already fixed

> Thanks for reporting this!
>
> This has already been fixed in [INSERT URL OF PR HERE]. It should be available in version [VERSION NUMBER HERE].

### closing inactive

> Closing this out due to inactivity. @[NAME] if you're able to provide the requested information we're happy to revisit the issue.

### duplicate

> Thanks for taking the time to contribute!
>
> We noticed that this is a duplicate of [ISSUE URL]. Please follow that issue for further updates.

### future proposal

> Thanks for the suggestion!
>
> This idea is interesting for the future, but this is beyond the scope of our current roadmap.
>
> We will keep it open until there's more evidence. If you believe this to be incorrectly prioritized, please do let us know and we will evaluate your counter-proposal. If you want to contribute the implementation, please tell the maintainers that you are willing to send in a pull-request and we'll do everything we can to bring you up to speed with becoming a contributor.

### needs information or reproduction (Android)

> Thanks for the report!
>
> Specific things I'd like to learn about are what Android API level you are using and if you are testing in a simulator or on a device.
>
> Could you please provide a test case that reproduces the issue and provide [logs from `logcat`](https://learn.microsoft.com/xamarin/android/deploy-test/debugging/android-debug-log?tabs=windows)?

### needs template

> Thanks for reaching out!
>
> We require the template to be filled out when submitting all issues. We do this so that we can be certain we have all the information we need to address your submission efficiently. This allows the maintainers to spend more time fixing bugs, implementing enhancements, and reviewing and merging pull requests.
>
> Thanks for understanding and meeting us halfway!

### no response

> Thank you for your issue!
>
> We haven't gotten a response to our questions in our comment [insert URL here]. With only the information that is currently in the issue, we don't have enough information to take action. I'm going to close this but don't hesitate to reach out if you have or find the answers we need, we'll be happy to reopen the issue.

### not a priority

> Thanks for the suggestion @[NAME]!
>
> This would be good to have, but we may not have anyone available to work on it right now or in the immediate future.
>
> I've added the `help wanted` label to this issue and community contributions would be most welcome in the meantime. If you want to contribute the implementation, please tell the maintainers that you are willing to send in a pull-request and we'll do everything we can to bring you up to speed with becoming a contributor.

### open a new issue

> @[NAME] please open a new issue and fill out the issue template so that we're better able to help you.

### send in a pull-request

> This would be good to have and we'd love it if you or someone from the community could contribute the implementation. Please let us know if you want to send in the PR and we'll do everything we can to bring you up to speed with becoming a contributor.

## Acknowledgements

* This document was based off the [Kubernetes community sig guidelines](https://github.com/kubernetes/community/blob/e4eabb7c3c26ce4463f1ab89e0ad94a7a7671b08/contributors/guide/issue-triage.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/lightsensor.md

---
uid: Uno.Features.LightSensor
---

# LightSensor

> [!TIP]
> This article covers Uno-specific information for LightSensor. For a full description of the feature and instructions on using it, see [Use the light sensor](https://learn.microsoft.com/windows/uwp/devices-sensors/use-the-light-sensor).

* The `Windows.Devices.Sensors.LightSensor` class allows measuring the illuminance in LUX.

## Supported features

| Feature          |Windows|Android|iOS|Wasm|macOS|Skia|
|------------------|-------|-------|---|----|-----|----|
| `GetDefault`     |   ✔   |   ✔   | ✖ | ✔ | ✖ | ✖ |
| `ReadingChanged` |   ✔   |   ✔   | ✖ | ✔ | ✖ | ✖ |
| `ReportInterval` |   ✔   |   ✔   | ✖ | ✖ | ✖ | ✖ |

## Using LightSensor with Uno

* The `GetDefault` method is available on all targets and will return `null` on those which do not support `LightSensor` or devices that do not have such a sensor.
* Ensure to unsubscribe from the `ReadingChanged` events when you no longer need the readings, so that the sensor is no longer active to avoid unnecessary battery consumption.

## Examples

### Capturing sensor readings

```csharp
var lightSensor = LightSensor.GetDefault();
lightSensor.ReadingChanged += LightSensor_ReadingChanged;

private async void LightSensor_ReadingChanged(LightSensor sender, LightSensorReadingChangedEventArgs args)
{
    // If you want to update the UI in some way, ensure the Dispatcher is used,
    // as the ReadingChanged event handler does not run on the UI thread.
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        OutputTextBlock.Text = $"Sensor reading is " +
            $"IlluminanceInLux = {args.Reading.IlluminanceInLux}, " + 
            $"timestamp = {args.Reading.Timestamp}";
    });
}
```

### Unsubscribing from the readings

```csharp
lightSensor.ReadingChanged -= LightSensor_ReadingChanged;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.themes/refs/heads/master/doc/lightweight-styling.md

---
uid: Uno.Themes.LightweightStyling
---

# Lightweight Styling

[Lightweight styling](https://learn.microsoft.com/windows/apps/design/style/xaml-styles#lightweight-styling) is a way to customize the appearance of XAML controls by **overriding** their default brushes, fonts, and numeric properties. Lightweight styles are changed by providing alternate resources with the same key. All Uno Material styles support the capability to be customized through resource overrides without the need to redefine the style.

Overriding resources from Uno Material can be done at the App level, Page level, or even at the Control level. The following sections will cover how to override resources at each of these levels.

> [!Video https://www.youtube-nocookie.com/embed/5CsJHMTlNAw]

## App/Page level styling

The most common way to override resources is at the App level. This is done by adding a new `ResourceDictionary` to the `ResourceDictionary.MergedDictionaries` collection in your `AppResources.xaml` file. The following XAML shows how to override the default resources used with the `FilledButtonStyle` from Uno Themes.

```xml
<!-- AppResources.xaml -->
<ResourceDictionary.MergedDictionaries>

    <!-- Load WinUI resources -->
    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />

    <!-- Load Uno Material resources -->
    <MaterialTheme xmlns="using:Uno.Material" />

    <!-- Override resources -->
    <ResourceDictionary>
        <ResourceDictionary.ThemeDictionaries>
            <ResourceDictionary x:Key="Light">
                <Thickness x:Key="ButtonBorderThickness">2</Thickness>
                <SolidColorBrush x:Key="FilledButtonForeground" Color="DarkGreen" />
                <SolidColorBrush x:Key="FilledButtonBackground" Color="LightGreen" />
                <SolidColorBrush x:Key="FilledButtonBorderBrush" Color="DarkGreen" />
            </ResourceDictionary>
            <ResourceDictionary x:Key="Default">
                <Thickness x:Key="ButtonBorderThickness">2</Thickness>
                <SolidColorBrush x:Key="FilledButtonForeground" Color="LightGreen" />
                <SolidColorBrush x:Key="FilledButtonBackground" Color="DarkGreen" />
                <SolidColorBrush x:Key="FilledButtonBorderBrush" Color="LightGreen" />
            </ResourceDictionary>
        </ResourceDictionary.ThemeDictionaries>
    </ResourceDictionary>

</ResourceDictionary.MergedDictionaries>
```

Notice the `ResourceDictionary.ThemeDictionaries` element. This is where you can override resources for each theme. In the example above, we are overriding the resources for both the Light and Default themes. The Light theme is used when the device is in Light mode, and the Default theme is used when the device is in Dark mode. Below is an example of the same `Button` using the `FilledButtonStyle` from Uno Material, but with the overrides from above applied to both the Light and Dark themes.

![Material - Button lightweight styling themes](assets/lightweight-styling-theme-comparison.png)

Placing these brush overrides at the `AppResources.xaml` level will alter every `Button` that is styled with `FilledButtonStyle` within the entire application. The overrides can be scoped to a specific page by placing them in the `Page.Resources` element of the page’s XAML. The following XAML shows how to override the same resources from above, but scoped to a specific page.

```xml
<!-- MyPage.xaml -->
<Page.Resources>
    <ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
        <ResourceDictionary.ThemeDictionaries>
            <ResourceDictionary x:Key="Light">
                <Thickness x:Key="ButtonBorderThickness">2</Thickness>
                <SolidColorBrush x:Key="FilledButtonForeground" Color="DarkGreen" />
                <SolidColorBrush x:Key="FilledButtonBackground" Color="LightGreen" />
                <SolidColorBrush x:Key="FilledButtonBorderBrush" Color="DarkGreen" />
            </ResourceDictionary>
            <ResourceDictionary x:Key="Default">
                <Thickness x:Key="ButtonBorderThickness">2</Thickness>
                <SolidColorBrush x:Key="FilledButtonForeground" Color="LightGreen" />
                <SolidColorBrush x:Key="FilledButtonBackground" Color="DarkGreen" />
                <SolidColorBrush x:Key="FilledButtonBorderBrush" Color="LightGreen" />
            </ResourceDictionary>
        </ResourceDictionary.ThemeDictionaries>
    </ResourceDictionary>
</Page.Resources>
```

## Per-control styling

In other cases, changing a single control on one page only to look a certain way, without altering any other versions of that control, can also be achieved. The provided XAML code and image depict a `Button` using the default `FilledButtonStyle` followed by a second `Button`, also with `FilledButtonStyle` applied, but now with specific resource keys overridden to customize its appearance.

```xml
<Button Content="Default Button Style"
        Style="{StaticResource FilledButtonStyle}" />

<Button Content="Overridden Button Style"
        Style="{StaticResource FilledButtonStyle}"
        BorderThickness="2">
    <Button.Resources>
        <SolidColorBrush x:Key="FilledButtonForeground" Color="DarkGreen" />
        <SolidColorBrush x:Key="FilledButtonBackground" Color="LightGreen" />
        <SolidColorBrush x:Key="FilledButtonBorderBrush" Color="DarkGreen" />
    </Button.Resources>
</Button>
```

![Material - Button lightweight styling](assets/material-lightweight-styling-anatomy.png)

Lightweight Styling allows for fine-grained control over the look of your UI components across all visual states. All interactive controls have multiple states, such as **PointerOver** (mouse is hovered over), **Pressed** (control is pressed on), and **Disabled** (control is not interactable). These states are appended onto the endings of the resource keys: ButtonForeground*PointerOver*, ButtonForeground*Pressed*, and ButtonForeground*Disabled*. Combined with these, the `CheckBox` and `RadioButton` controls also have **Checked** and **Unchecked** states. This means that it is possible to customize the appearance of your Uno Material-styled controls across any visual state without the need to redefine the style. As an example, the XAML below defines three Buttons, all using FilledButtonStyle from Uno Material:

1. A Default Button with no changes
2. A Button with several brush resources overridden for the **Normal** visual state
3. A Button that overrides resources that are used with FilledButtonStyle's **PointerOver** visual state

```xml
<!-- #1 -->
<Button Content="Default Button Style"
        Style="{StaticResource FilledButtonStyle}" />

<!-- #2 -->
<Button Content="Overridden Button Style"
        Style="{StaticResource FilledButtonStyle}">
    <Button.Resources>
        <Thickness x:Key="ButtonBorderThickness">2</Thickness>
        <SolidColorBrush x:Key="FilledButtonForeground" Color="DarkGreen" />
        <SolidColorBrush x:Key="FilledButtonBackground" Color="LightGreen" />
        <SolidColorBrush x:Key="FilledButtonBorderBrush" Color="DarkGreen" />
    </Button.Resources>
</Button>

<!-- #3 -->
<Button Content="Overridden Button Style (PointerOver)"
        Style="{StaticResource FilledButtonStyle}">
    <Button.Resources>
        <Thickness x:Key="ButtonBorderThickness">2</Thickness>
        <SolidColorBrush x:Key="FilledButtonForegroundPointerOver" Color="DarkRed" />
        <SolidColorBrush x:Key="FilledButtonBackgroundPointerOver" Color="LightPink" />
        <SolidColorBrush x:Key="FilledButtonBorderBrushPointerOver" Color="DarkRed" />
    </Button.Resources>
</Button>
```

With this XAML, we are given the following visual result, notice the third Button has a new `BorderThickness` applied and takes on different colors while in the **PointerOver** state.

![Material - Button lightweight styling](assets/material-button-pointerover-lightweight-styling.png)

## C# Markup

All Lightweight Styling resource keys can also be used in C# Markup through a collection of static helper classes available in the [Uno.Themes.WinUI.Markup](https://www.nuget.org/packages/Uno.Themes.WinUI.Markup/) NuGet package. The following code shows how to override several `FilledButton` resources in C# from the previous XAML example above. Notice that the `Button` is still using the `FilledButtonStyle` from Uno Material, but the resources are being overridden.

```csharp
// basic filled button
new Button()
    .Style(Theme.Button.Styles.Filled)
    .Content("Default Button Style"),

// filled button with overridden colors
new Button()
    .Style(Theme.Button.Styles.Filled)
    .Resources(config => config
        .Add(Theme.Button.Resources.BorderThickness, 2)
        .Add(Theme.Button.Resources.Filled.Foreground.Default, new SolidColorBrush(Colors.DarkGreen))
        .Add(Theme.Button.Resources.Filled.Background.Default, new SolidColorBrush(Colors.LightGreen))
        .Add(Theme.Button.Resources.Filled.BorderBrush.Default, new SolidColorBrush(Colors.DarkGreen))
    )
    .Content("Overridden Button Style"),

// filled button with overridden colors for PointerOver state
new Button()
    .Style(Theme.Button.Styles.Filled)
    .Resources(config => config
        .Add(Theme.Button.Resources.BorderThickness, 2)
        .Add(Theme.Button.Resources.Filled.Foreground.PointerOver, new SolidColorBrush(Colors.DarkRed))
        .Add(Theme.Button.Resources.Filled.Background.PointerOver, new SolidColorBrush(Colors.LightPink))
        .Add(Theme.Button.Resources.Filled.BorderBrush.PointerOver, new SolidColorBrush(Colors.DarkRed))
    )
    .Content("Overridden Button Style (PointerOver)")
```

### Resource Key Pattern

The general pattern used for mapping the Lightweight Styling resource keys to C# Markup is as follows:

`Theme.{control}.Resources.{?:variant}.{member-path}.{?:visual-state}`

| Name Part      | Description                                                                                                                                      |
|----------------|--------------------------------------------------------------------------------------------------------------------------------------------------|
| `control`      | Name of the control type (Button, TextBox, CheckBox, etc.)                                                                                       |
| `variant`      | **(Optional) Defaults to `Default`** Certain styles have multiple variants. Ex: For Button we have variants such as: Outlined, Text, Filled      |
| `member-path`  | The property or the nested property to assign value to. (Foreground, Background, Placeholder.Foreground, etc.)                                   |
| `visual-state` | **(Optional) Defaults to `Default`**  Specifies which `VisualState` that this resource will be applied to (PointerOver, Checked, Disabled, etc.) |

For example, the following resource keys are used with `FilledButtonStyle`, `HyperlinkButtonStyle`, and `CheckBoxStyle` from Uno Material:

#### Filled Button

- `Theme.Button.Resources.Filled.Foreground.Default`
- `Theme.Button.Resources.Filled.Foreground.Pressed`
- `Theme.Button.Resources.Filled.Foreground.PointerOver`

#### HyperlinkButton (Default)

- `Theme.HyperlinkButton.Resources.Default.Foreground.Default`
- `Theme.HyperlinkButton.Resources.Default.Foreground.Pressed`
- `Theme.HyperlinkButton.Resources.Default.Foreground.PointerOver`

#### CheckBox (Default)

- `Theme.CheckBox.Resources.Default.Foreground.Checked`
- `Theme.CheckBox.Resources.Default.Foreground.CheckedPressed`
- `Theme.CheckBox.Resources.Default.Foreground.CheckedPointerOver`

All C# Markup-friendly Lightweight Styling resource keys can be found in [Uno.Themes GitHub repository](https://github.com/unoplatform/Uno.Themes/tree/master/src/library/Uno.Themes.WinUI.Markup/Theme)

## Resource Keys

For more information about the lightweight styling resource keys used in each control, check out the following links:

- [Button](styles/Button.md)
- [CalendarDatePicker](styles/CalendarDatePicker.md)
- [CheckBox](styles/CheckBox.md)
- [ComboBox](styles/ComboBox.md)
- [DatePicker](styles/DatePicker.md)
- [FloatingActionButton](styles/FloatingActionButton.md)
- [HyperlinkButton](styles/HyperlinkButton.md)
- [NavigationView](styles/NavigationView.md)
- [PasswordBox](styles/PasswordBox.md)
- [PipsPager](styles/PipsPager.md)
- [ProgressBar](styles/ProgressBar.md)
- [ProgressRing](styles/ProgressRing.md)
- [RadioButton](styles/RadioButton.md)
- [RatingControl](styles/RatingControl.md)
- [Slider](styles/Slider.md)
- [TextBlock](styles/TextBlock.md)
- [TextBox](styles/TextBox.md)
- [ToggleButton](styles/ToggleButton.md)
- [ToggleSwitch](styles/ToggleSwitch.md)

## Toolkit

Toolkit also has controls that allow lightweight styling, check out [Lightweight Styling in Uno.Toolkit](xref:Toolkit.LightweightStyling).

### Further Reading

[Lightweight Styling (Windows Dev Docs)](https://learn.microsoft.com/windows/apps/design/style/xaml-styles#lightweight-styling)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/listviewbase-internals.md

---
uid: Uno.Contributing.ListViewBase
---

# ListViewBase internals for contributors

This document describes the internal operations of Uno's `ListViewBase` implementation(s) in detail, aimed at contributors.

Before reading it, you should first read the documentation of [ListViewBase aimed at Uno app developers](../controls/ListViewBase.md), which covers the high-level differences between Uno's implementation and UWP's implementation.

## Introduction

`ListViewBase` is the base class of `ListView` and `GridView`. The remainder of the article will refer to 'ListView', the more commonly used of the two derived controls, for ease of reading, but most of the information is applicable to `GridView` as well since a large part of the implementation is shared.

`ListView` is a specialized type of [`ItemsControl`](https://learn.microsoft.com/uwp/api/windows.ui.xaml.controls.itemscontrol) designed for showing large numbers of items. `ListView` is by default *virtualized*, meaning that it only materializes view containers for those items which are visible or about to be visible within the scroll viewport. When items disappear from view, their containers are *recycled* and reused for newly appearing views. Correctly-functioning virtualization is the key to good scroll performance.

Other important features of `ListView`:

- selection, including multiple selection
- support for 'observable' collections, allowing items to be inserted and deleted without completely resetting the state of the list, and (on some platforms) with an animation of the item being added or removed
- item groups (with optional 'sticky' group headers)
- drag and drop to reorder items in the list

## Platform-specific implementations of `ListView`

On Android and iOS, `ListView` uses a platform-specific implementation that maps the XAML API to an inner instance of the native list control on each platform, being [RecyclerView](https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView) and [UICollectionView](https://developer.apple.com/documentation/uikit/uicollectionview) respectively. Using the native list control brings the advantage of getting advanced features like item animations 'for free', along with the disadvantage of added maintenance burden, the possibility of platform-specific differences in behavior, and the additional complexity of having non-`FrameworkElement` views in the visual tree.

Other platforms (WebAssembly, Skia, and macOS at the time of writing) use a purely managed implementation of `ListView`. This implementation is closer to WinUI in its comportment, for example, it actually uses the items panel (`ItemsStackPanel`) to host items. However, it's not a direct port of the WinUI control.

The managed ListView implementation is newer and lacks some features that are supported by the Android and iOS ListViews (and of course WinUI); the feature gap is tracked by [this issue](https://github.com/unoplatform/uno/issues/234).

### Jargon

`ListView` can scroll either vertically or horizontally, and the layouting logic is written as much as possible to reuse the same code for both orientations. Accordingly, certain terms are used throughout the code to avoid using orientation-specific terms like 'width' and 'height'. (These usages are probably unique to the Uno codebase.) The main terms are the following:

- Extent: Size along the dimension parallel to scrolling. The equivalent of 'Height' if scrolling is vertical, or 'Width' otherwise.
- Breadth: Size along the dimension orthogonal to scrolling. The equivalent of 'Width' if scrolling is vertical, or 'Height' otherwise.
- Start: The edge of the element nearest to the top of the content panel, ie 'Top' or 'Left' depending whether scrolling is vertical or horizontal.
- End: The edge of the element nearest to the bottom of the content panel, ie 'Bottom' or 'Right' depending whether scrolling is vertical or horizontal.
- Leading: When scrolling, the edge that is coming into view. ie, if the scrolling forward in a vertical orientation, the bottom edge.
- Trailing: When scrolling, the edge that is disappearing from view.

### Android and iOS ListViews in detail

Although the Android and iOS implementations are quite different, they share some high-level similarities. Both platforms expose a `NativeListViewBase` class, which inherits from the native list view for the platform.

Architecturally, the Android and iOS implementations share a similar high-level 'division of labor', reflecting the underlying platform API. Aside from the view type itself, both implementations implement a class, `VirtualizingPanelLayout`, whose responsibility is to determine what items are visible, what size they should take, and how they should be positioned within the list. Additionally, both Android and iOS implement an 'adapter' or 'source' class with the responsibility of materializing item containers for a given list index and binding them to the appropriate item from the items source.

(As an aside, this division of labor has no equivalent in `ListView`, but a somewhat similar approach is taken by WinUI's newer [`ItemsRepeater`](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.controls.itemsrepeater) control, also available in Uno.)

[This diagram](../controls/ListViewBase.md#difference-in-the-visual-tree) shows how the `NativeListViewBase` view is incorporated into the visual tree, and the resulting difference from WinUI. The key differences are:

- the scrolling container is the `NativeListViewBase` itself, not the `ScrollViewer`. Thus, the `ItemsPresenter` is **outside** the scrollable region. Additionally, there's no ScrollContentPresenter; instead, there's a ListViewBaseScrollContentPresenter. (It was implemented this way back when ScrollContentPresenter inherited directly from the native scroll container.)
- the `ItemsStackPanel` (or `ItemsWrapGrid`) is not actually present in the visual tree. These items' panels are created, and their configured values (eg, `Orientation`) are used to set the behavior of the list, but they are not actually loaded into the visual hierarchy or measured and arranged. They just act as a facade for the native layouter.
- the Header and Footer, if present, are managed by the native list on Android and iOS, whereas on WinUI, they're outside the ItemsStackPanel/ItemsWrapGrid.

Much of the time, these are implementation details that are invisible to the end user. In certain cases, they can have a visible impact. They're useful to be aware of when working on `ListView` bugs.

#### Android

`NativeListViewBase` implements Android's [`RecyclerView`](https://developer.android.com/reference/androidx/recyclerview/widget/RecyclerView). The available customization points of `RecyclerView` are heavily utilized to support all the features exposed by the XAML `ListView` contract.

The most important class is `VirtualizingPanelLayout`, which inherits from `RecyclerView.LayoutManager`, and is responsible for determining which views to create for a given scroll position, and where they should go.

The 'life cycle' of view creation and positioning of the `ListView` largely takes place during the measure and arrange phases, and when scrolling. A summary follows:

##### Layouting 'life cycle' summary

1. List is measured.
    1. Android framework calls `VirtualizingPanelLayout.OnMeasure()`, which calls `VirtualizingPanelLayout.UpdateLayout()`.
    1. `UpdateLayout()` => `ScrapLayout()`. `ScrapLayout()` performs a 'lightweight detach operation' on all views and adds them to the `Recycler's` 'scrap'. This allows the size and position of views to be recalculated if need be, but is very cheap (compared to removing and re-adding views in the normal Android way, which kills performance if done frequently).
    1. `UpdateLayout()` => `FillLayout()`. `FillLayout()` takes a direction, either Forward or Backward, and fills in unmaterialized items in that direction. The next item to add is always determined *relative to existing materialized items*, and it is added *if there is available viewport space in the designated direction*. To take a concrete example: the viewport is 320 pixels high; individual item containers are 80 pixels high; the list is currently scrolled to an offset of 100 pixels. Item containers for positions 0, 1, 2, 3 are currently materialized; their bounds in y are (-100, -20), (-20, 60), (60, 140), and (140, 220), relative to the viewport. `FillLayout()` would determine that the next unmaterialized item is 4. It would also see that `220 < 320`, and therefore space is available to add the item - this occurs within `TryCreateLine()`. Item 4 will be added at (220, 300). The list would then try to add item 5 at (300, 380), and succeed because `300 < 320`. It will then try to add item 6, and fail, because `380 > 320` (that is, item 6 is still entirely out of the viewport), at which point the loop terminates.
    1. `UpdateLayout()` => `UnfillLayout()`. `UnfillLayout()` takes a direction, and trims materialized item containers that are not visible starting from the **opposite** direction. So to take the example above: `UnfillLayout()` would start with item 0, and see that it lies entirely outside the viewport (`-20 < 0`), so it would dematerialize it, returning it to the recycler to be reused. It would then consider item 1, see that it is partially visible (`60 > 0`), and terminate at that point. `UnfillLayout()` is particularly important during scrolling (see below).
2. List is arranged.
    1. Android framework => `VirtualizingPanelLayout.OnLayoutChildren()` => `VirtualizingPanelLayout.UpdateLayout()`.
    2. `UpdateLayout()` does *not* call `ScrapLayout()` from within the arrange pass. This is because item dimensions should not have changed since the measure. It does however call `FillLayout()` and `UnfillLayout()` again. This is because the dimensions available to the list itself *might* be different from the ones it was measured with.
3. List is scrolled.
    1. Android framework => `VirtualizingPanelLayout.ScrollVerticallyBy()` (or `ScrollHorizontallyBy()`).
    1. `ScrollVerticallyBy()` => `ScrollBy()`.
    1. `ScrollBy()` => `ScrollByInner()`. `ScrollByInner()` essentially moves the viewport 'window' according to the supplied offset, and calls `FillLayout()` and `UnfillLayout()` to add the views visible within that window and remove the ones not visible within it. For large scrolls, `ScrollBy()` will `ScrollByInner()` multiple times with increasingly larger offsets: the purpose of this is to have `FillLayout()` not add multiple views in a single call, because that uses the pool of recycled views inefficiently and will cause new views to be created unnecessarily, which in turn degrades performance.

        At some point the end of the items will be reached, meaning for large requested scrolls, it may not actually be possible to scroll as far as requested. Consequently, `ScrollBy()` returns the actual offset that was possible to scroll.
    1. `ScrollBy()` => `OffsetChildrenVertical()` (or `OffsetChildrenHorizontal()`). The base native method is what actually adjusts the offset of the children relative to the `NativeListViewBase`, which produces the impression that they're being scrolled. Uno-side state which depends on the scroll offset is also updated here.

#### iOS

On iOS, `NativeListViewBase` inherits from the `UICollectionView` native control. `UICollectionView` is special in that it expects to be given dimensions and positions for the item containers in the list **before** those containers have been materialized. This poses a challenge, because if the individual containers have not been materialized, then they have not been data-bound, and depending on the specific item template, the bound data may change the measured size. (Eg, for data-bound text wrapped to multiple lines, panel elements `Visibility={Binding SomeVMProperty}` ... etc.)

The measuring logic for iOS' `ListView` makes an initial guess for the size of each item based on the dimensions of the unbound `ItemTemplate`. Then, once the container for the item is actually materialized and bound, `UICollectionView` offers a chance to update the measured dimensions for the item, via the method `UICollectionViewCell.PreferredLayoutAttributesFittingAttributes()`. This method is implemented by the `ListViewBaseInternalContainer` derived type. This approach to supporting dynamic item container sizes works for the most part, but can be brittle and throws up a number of edge cases.

##### Layouting 'life cycle' summary

1. Upon measure, `VirtualizingPanelLayout.SizeThatFits()` is called, and in turn calls `PrepareLayoutIfNeeded()`. (`SizeThatFits()` is called from Uno's layouting code. `SizeThatFits()` is an overridden virtual method that's defined in UIKit, but it's mostly not used by UIKit itself.) `PrepareLayoutIfNeeded()` determines the `DirtyState` of the list. A `DirtyState` of `None` indicates that the existing internal layout state is still valid. `NeedsRelayout` indicates that the layout should be completely rebuilt, which may be the case if the available size changed, or if `InvalidateLayout()` was called. Other `DirtyState` values indicate more specific reasons for updating the layout state.
2. If `PrepareLayoutIfNeeded()` determines that a layout rebuild is required, it calls `PrepareLayoutInternal()`. `PrepareLayoutInternal()` calculates the sizes and positions of every item in the list, as well as non-item elements like header, footer, and group headers. Note that during measure, these sizes and values are not actually persisted (governed by the `createLayoutInfo` parameter), just used to calculate the total dimensions of the list contents.
3. On arrange, `UICollectionView` calls the `VirtualizingPanelLayout.PrepareLayout()` method, which also calls `PrepareLayoutIfNeeded()`=>`PrepareLayoutInternal()`. This time, `PrepareLayoutInternal()` will persist the calculated sizes and offsets of the items, as `UICollectionViewLayoutAttributes` objects.
4. `UICollectionView` calls `VirtualizingPanelLayout.LayoutAttributesForElementsInRect()` with the current viewport bounds, to determine what elements should be shown. `LayoutAttributesForElementsInRect()` checks the cached layout attributes, and returns all those that intersect with the passed viewport bounds.
5. For each element returned by `LayoutAttributesForElementsInRect()`, `UICollectionView` materializes a container by calling `ListViewBaseSource.GetCell()`. `GetCell()` returns a `ListViewBaseInternalContainer`, which has a `ListViewItem` (or a `ContentControl` in the case of a header, footer, or group header element) in its visual subtree.
6. For each container, `UICollectionView` calls `ListViewBaseInternalContainer.PreferredLayoutAttributesFittingAttributes()`. Here we are able to actually measure the data-bound item, and determine the final size it needs. If the size differs from the un-data-bound size, we:
    1. Return updated layout attributes from the method;
    2. Update the cached layout attributes for that item, for future use;
    3. Update the positions of subsequent items in the cached layout info, since if an item is larger/smaller than initially estimated, the offsets of the remaining items must be modified accordingly.
7. Whenever the list is scrolled, `UICollectionView` will call `LayoutAttributesForElementsInRect()` with the new visible viewport. Steps 5. and 6. will occur for each newly-visible item.

### Android and iOS internal classes

| Uno class | Android base class | iOS base class | Description |
| --- | --- | --- | --- |
| NativeListViewBase | AndroidX.RecyclerView.Widget.RecyclerView | UIKit.UICollectionView | Native list view, parent of item views. |
| VirtualizingPanelLayout† | RecyclerView.LayoutManager | UIKit.UICollectionViewLayout | Tells NativeListViewBase how to lay out its items. Bridge for ItemsStackPanel/ItemsWrapGrid. |
| NativeListViewBaseAdapter(Android), ListViewBaseSource(iOS) | RecyclerView.Adapter | UIKit.UICollectionViewSource | Handles creation and binding of item views.
| ListViewBaseInternalContainer | - | UICollectionViewCell | Implements the native container type - one is created for every `ListViewItem`/`GridViewItem` |
| ScrollingViewCache | RecyclerView.ViewCacheExtension | - | Additional virtualization handling on Android which optimizes scroll performance. |

† `VirtualizingPanelLayout` is the base class of `ItemsStackPanelLayout` and `ItemsWrapGridLayout`. The derived classes implement the item positioning logic for the corresponding items panel.

### Managed ListView in detail

On WASM, Skia, and macOS, `ListViewBase` uses a shared implementation that's dubbed 'managed' because it doesn't rely upon an external native control. The visible implementation details of the managed `ListView` are much closer to WinUI. Specifically:

- the items panel is a 'real' panel which hosts the ListViewItems as its children. The size of the panel reflects the estimated total size based on the number of items, as determined by the list.
- the `ScrollViewer` in the ListView's control template is a 'real' `ScrollViewer`, ie, it is in fact responsible for scrolling.

The internals of the managed `ListView` were originally implemented independently of the WinUI source, but have been gradually converging on the internals of WinUI.

Consistent with the other platforms, the managed `ListView` delegates layouting to a class called `VirtualizingPanelLayout`. Item container management is delegated to `VirtualizingPanelGenerator` (similar in responsibility to `NativeListViewBaseAdapter` (Android) and `ListViewBaseSource` (iOS)).

#### Layouting 'life cycle' summary

1. On measure, `ItemsStackPanel.MeasureOverride()` directly calls `VirtualizingPanelLayout.MeasureOverride()`.
2. `VirtualizingPanelLayout.MeasureOverride()` 'scraps' the existing layout. The 'scrap' concept is borrowed from Android: existing containers are returned to the item generator, but marked as able to be reused without rebinding during the current pass, if they are still needed (which will often be the case).
3. `VirtualizingPanelLayout.MeasureOverride()` => `UpdateLayout()`. `UpdateLayout()` calls `UnfillLayout()` and `FillLayout()`, which respectively dematerialize containers that are no longer visible within the current viewport and materialize containers for newly visible items.
4. `FillLayout()` calls `CreateLine()` for every missing 'line', which in turn calls `AddView()` for the view(s) in the line. `AddView()` measures the view, adds it to the panel, and stores its planned `Bounds` (size and offset) in `VirtualizationInformation` attached to the view.
5. `MeasureOverride()` returns an estimate of the panel size, based on the current extent of materialized items, the number of unmaterialized items, and the best guess of their size. (This estimate is potentially inaccurate, in the case that the unmaterialized items have a different data-bound size or use a template with a different size; this is a fundamental limitation of the `ListView` that's also present on WinUI.)
6. `ArrangeOverride()` calls `ArrangeElements()` which arranges each child view according to its stored Bounds, adjusted for the actual arranged size of the panel itself and also the parent `ScrollViewer`.
7. The panel listens to the `ViewChanged` event of its parent `ScrollViewer`. `VirtualizingPanelLayout.OnScrollChanged()` calls `UpdateLayout()`, in small increments to ensure that vanished views are recycled at the same rate as appearing views are materialized. `OnScrollChanged()` then calls `ArrangeElements()` to ensure newly-added views are arranged.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/localization.md

---
uid: Uno.Tutorials.Localization
---

# How to localize text resources

This guide will walk you through the necessary steps to localize an Uno Platform application.

> [!TIP]
> The complete source code that goes along with this guide is available in the [unoplatform/Uno.Samples](https://github.com/unoplatform/Uno.Samples) GitHub repository - [Localization](https://github.com/unoplatform/Uno.Samples/tree/master/UI/LocalizationSamples/Localization)
>
> [!TIP]
> For a step-by-step guide to installing the prerequisites for your preferred IDE and environment, consult the [Get Started guide](../get-started.md).

## Step-by-step instructions

1. Create a new Uno Platform application, following the instructions in [Get Started guide](../get-started.md).
1. Modify the content of `MainPage`:

    - In `MainPage.xaml`, replace the content of the page:

        ```xml
        <Page x:Class="UnoLocalization.MainPage"
              xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
              xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
              xmlns:toolkit="using:Uno.UI.Toolkit">

            <StackPanel toolkit:VisibleBoundsPadding.PaddingMask="Top">
                <TextBlock x:Uid="MainPage_IntroText" Text="Hello, world!" Margin="20" FontSize="30" />
                <TextBlock x:Name="CodeBehindText" Text="This text will be replaced" />
            </StackPanel>
        </Page>
        ```

        > Note:
        >
        > - The [`x:Name`](https://learn.microsoft.com/windows/uwp/xaml-platform/x-name-attribute) is used to make the element accessible from the code-behind with that same name.
        > - The [`x:Uid`](https://learn.microsoft.com/windows/uwp/xaml-platform/x-uid-directive) is used for localization.
        To localize a property, you need to add a string resource in each resource file using its `x:Uid` followed by a dot (`.`) and then the property name. eg: `MainPage_IntroText.Text`
        More on this in the resource steps that follow.

    - In `MainPage.xaml.cs`, add an `Page.Loaded` handler to change the text for `CodeBehindText`:

        ```csharp
        public MainPage()
        {
            this.InitializeComponent();
            this.Loaded += (s, e) => CodeBehindText.Text = Windows.ApplicationModel.Resources.ResourceLoader
                .GetForViewIndependentUse()
                .GetString("MainPage_CodeBehindString");
        }
        ```

1. Create a new resource file for localization in French in the `UnoLocalization.Shared` project:
    1. Add a new folder `fr` under the `Strings` folder by:
    Right-click on `Strings` > Add > New Folder
    1. Add a new resource file `Resources.resw` under the `fr` folder by:
    Right-click on `fr` > Add > New Item ... > Visual C# > Xaml > Resources File
1. Add the localization strings for both English and French:

    Open both `Strings\en\Resources.resw` and `Strings\fr\Resources.resw`, and add these:

    |Name|Value in `en\Resources.resw`|Value in `fr\Resources.resw`|
    |-|-|-|
    |MainPage_IntroText.Text|`Hello Uno`|`Bonjour Uno`|
    |MainPage_CodeBehindString|`String from code-behind`|`Texte provenant du code-behind`|
    > [!NOTE]
    > Make sure to hit Ctrl+S for both files, to save the changes.
    >
    > [!IMPORTANT]
    > The `ResourceLoader` will search for resources in the current language, then the default language. The default language is defined by the MSBuild property `DefaultLanguage`, which defaults to `en`.

1. You can now try to run the app.

    The "Hello World" text should be replaced with "Hello Uno", or "Bonjour Uno" if the targeted environment is on French culture.
    Now, if you change the language of the targeted PC or the mobile device AND restart the app, that text should also change accordingly.

    You can also set the starting culture to see the result, without having to modify the system language:
    - `App.cs` or `App.xaml.cs`:

        ```csharp
        public App()
        {
            InitializeLogging();
            ChangeStartingLanguage();

            this.InitializeComponent();
            this.Suspending += OnSuspending;
        }

        private void ChangeStartingLanguage()
        {
            var culture = new System.Globalization.CultureInfo("fr");

            Windows.Globalization.ApplicationLanguages.PrimaryLanguageOverride = culture.TwoLetterISOLanguageName;
        }
        ```

1. For WinUI 3 projects
   - As an unpackaged WinUI 3 app doesn't contain a package.appxmanifest file, no further action is needed after adding the appropriate resources to the project.
   - If you are working with a packaged WinUI 3 app, open the .wapproj's `package.appxmanifest` in a text editor and locate the following section:

    ```xml
    <Resources>
        <Resource Language="x-generate"/>
    </Resources>
    ```

    Replace it with elements for each of your supported languages. For example:

    ```xml
    <Resources>
        <Resource Language="en-US"/>
        <Resource Language="es-ES"/>
        <!-- Add more languages as needed -->
    </Resources>
    ```

## Get the complete code

See the completed sample on GitHub: [LocalizationSamples/Localization](https://github.com/unoplatform/Uno.Samples/tree/master/UI/LocalizationSamples/Localization)

## Additional Resources

[Globalization and localization](https://learn.microsoft.com/windows/uwp/design/globalizing/globalizing-portal)

## Help! I'm having trouble

[!include[getting-help](../includes/getting-help.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/logging.md

---
uid: Uno.Development.Logging
---

# Logging

Virtually every production level application should utilize some form of logging. During development, especially when developing WASM applications where using a debugger can be more challenging, diagnostic logs can be invaluable for identifying issues. Once in production, capturing information about critical failures can be invaluable.

> [!IMPORTANT]
> If you created your app using the **Recommended** preset, please refer to our [**Uno.Extensions.Logging** documentation](xref:Uno.Extensions.Logging.Overview) instead.
>
> For more information about the difference between the **Blank** and **Recommended** presets, please see the [Preset selection](xref:Uno.GettingStarted.UsingWizard#preset-selection) section of our Solution Template documentation.

## Logging in Uno Platform

The Uno platform makes use of the Microsoft logging NuGet packages to provide comprehensive logging support.

### Configuring logging

The standard Uno template configures logging in the **App.xaml.cs** file.

1. Add the [`Uno.UI.Adapter.Microsoft.Extensions.Logging`](https://www.nuget.org/packages/Uno.UI.Adapter.Microsoft.Extensions.Logging/) NuGet package to your platform projects.
1. In the iOS project, add the [`Uno.Extensions.Logging.OSLog`](https://www.nuget.org/packages/Uno.Extensions.Logging.OSLog/) NuGet package to your platform projects.
1. In the WebAssembly project, add the [`Uno.Extensions.Logging.WebAssembly.Console`](https://www.nuget.org/packages/Uno.Extensions.Logging.WebAssembly.Console/) NuGet package to your platform projects.

1. Open the **App.xaml.cs** file.

1. Locate the **App** constructor and note that logging is configured first:

    ```csharp
    public App()
    {
        InitializeLogging();
    ```

    Notice that Uno provides a logger factory implementation.

1. Locate the **InitializeLogging** method and review the code:

   > [!IMPORTANT]
   > The `InitializeLogging()` method is wrapped in a `#if DEBUG` preprocessor directive. This means **logging is only enabled in DEBUG builds by default**. If you need logging in Release builds, you'll need to remove or modify the `#if DEBUG` condition, keeping in mind the performance implications mentioned in the code comments.

    ```csharp

    private static void InitializeLogging()
    {
    #if DEBUG

    // Logging is disabled by default for release builds, as it incurs a significant
    // initialization cost from Microsoft.Extensions.Logging setup. If startup performance
    // is a concern for your application, keep this disabled. If you're running on web or
    // desktop targets, you can use url or command line parameters to enable it yourself.
    //
    // For more performance documentation: https://platform.uno/docs/articles/Uno-UI-Performance.html

        var factory = LoggerFactory.Create(builder =>
        {
    #if __WASM__
            builder.AddProvider(new global::Uno.Extensions.Logging.WebAssembly.WebAssemblyConsoleLoggerProvider());
    #elif __IOS__ || __TVOS__
            builder.AddProvider(new global::Uno.Extensions.Logging.OSLogLoggerProvider());
            builder.AddConsole();
    #elif NETFX_CORE
            builder.AddDebug();
    #else
            builder.AddConsole();
    #endif

            // Exclude logs below this level
            builder.SetMinimumLevel(LogLevel.Information);

            // Default filters for Uno Platform namespaces
            builder.AddFilter("Uno", LogLevel.Warning);
            builder.AddFilter("Windows", LogLevel.Warning);
            builder.AddFilter("Microsoft", LogLevel.Warning);

            // Generic Xaml events
            // builder.AddFilter("Windows.UI.Xaml", LogLevel.Debug );
            // builder.AddFilter("Windows.UI.Xaml.VisualStateGroup", LogLevel.Debug );
            // builder.AddFilter("Windows.UI.Xaml.StateTriggerBase", LogLevel.Debug );
            // builder.AddFilter("Windows.UI.Xaml.UIElement", LogLevel.Debug );
            // builder.AddFilter("Windows.UI.Xaml.FrameworkElement", LogLevel.Trace );

            // Layouter specific messages
            // builder.AddFilter("Windows.UI.Xaml.Controls", LogLevel.Debug );
            // builder.AddFilter("Windows.UI.Xaml.Controls.Layouter", LogLevel.Debug );
            // builder.AddFilter("Windows.UI.Xaml.Controls.Panel", LogLevel.Debug );

            // builder.AddFilter("Windows.Storage", LogLevel.Debug );

            // Binding related messages
            // builder.AddFilter("Windows.UI.Xaml.Data", LogLevel.Debug );
            // builder.AddFilter("Windows.UI.Xaml.Data", LogLevel.Debug );

            // Binder memory references tracking
            // builder.AddFilter("Uno.UI.DataBinding.BinderReferenceHolder", LogLevel.Debug );

            // RemoteControl and HotReload related
            // builder.AddFilter("Uno.UI.RemoteControl", LogLevel.Information);

            // Debug JS interop
            // builder.AddFilter("Uno.Foundation.WebAssemblyRuntime", LogLevel.Debug );
        });

        global::Uno.Extensions.LogExtensionPoint.AmbientLoggerFactory = factory;

    #if HAS_UNO
        global::Uno.UI.Adapter.Microsoft.Extensions.Logging.LoggingAdapter.Initialize();
    #endif

    #endif // DEBUG
    }
    ```

    Notice that the logging levels of various categories can be added and configured.

    > [!NOTE]
    > Notice that console logging is configured by default with `.AddConsole();` for most platforms. However, this **does not** log output to the Visual Studio console when running a WinUI app. For WinUI apps (the `NETFX_CORE` platform in the code above), logging is configured with `builder.AddDebug();` instead, which outputs to the Visual Studio Debug window.

### Uno logging extensions

The Uno platform also provides an extension that simplifies the use of logging by making it simple to retrieve a reference to the logger.

1. In order to add logging to a class, add the following using statements namespaces:

    ```csharp
    using Microsoft.Extensions.Logging;
    using Uno.Extensions;
    ```

1. In order to write output to a log, the **Log** extension method is available on an object instance, which then exposes the operations available from **Microsoft.Extensions.Logging.LoggerExtensions**. Here is an example on how to write error and information level messages:

    ```csharp
    if (discoveryClient.IsError)
    {
        this.Log().LogError(discoveryClient.Error);
        throw new Exception(discoveryClient.Error);
    }
    this.Log().LogInformation($"UserInfoEndpoint: {discoveryClient.UserInfoEndpoint}");
    ```

    > [!TIP]
    > To learn more about the logging capabilities, review the Microsoft logging reference materials here:
    >
    > * [Logging in .NET](https://learn.microsoft.com/dotnet/core/extensions/logging)

## Log output for not implemented member usage

By default, when a member is invoked at runtime that's not implemented by Uno (ie, marked with the `[NotImplemented]` attribute), an error message is logged.

> [!IMPORTANT]
> This feature flag must be set before the `base.InitializeComponent()` call within the `App.xaml.cs` constructor.

The logging behavior can be configured using feature flags:

* By default, a message is only logged on the first usage of a given member. To log every time the member is invoked:

    ```csharp
    Uno.UI.FeatureConfiguration.ApiInformation.AlwaysLogNotImplementedMessages = true;
    ```

* By default the message is logged as an error. To change the logging level:

    ```csharp
    Uno.UI.FeatureConfiguration.ApiInformation.NotImplementedLogLevel = LogLevel.Debug; // Raise not implemented usages as Debug messages
    ```

    This can be used to suppress the not implemented output, if it's not useful.

## iOS Specifics

### Logging with OSLogLoggerProvider

The OSLogProvider will log to the device's syslog, and is visible on macOS using the **Monitor** app when selecting the device.

Note that by default, debug and info messages are not visible and must be enabled on the **Monitor** app in the **Action** Menu, with the **Include Info/Debug Messages**.

### OptionsMonitor issues

```Unhandled Exception:
System.InvalidOperationException: A suitable constructor for type 'Microsoft.Extensions.Options.OptionsMonitor`1[Microsoft.Extensions.Logging.LoggerFilterOptions]' could not be located. Ensure the type is concrete and services are registered for all parameters of a public constructor.
```

If you are getting the above exception when running on iOS and the Linker Behavior is set to "Link All" it is likely that the IL linker is removing some logging classes.
See [Linking Xamarin.iOS Apps](https://learn.microsoft.com/xamarin/ios/deploy-test/linker?tabs=macos)

One option is to use `linkskip` file to exclude the assemblies causing issues.
Add the following to your `mtouch` arguments:

```console
--linkskip=Uno.Extensions.Logging.OSLog 
--linkskip=Microsoft.Extensions.Options
```

The other option is to add a [custom linker definition file](https://learn.microsoft.com/xamarin/cross-platform/deploy-test/linker)

```xml
<linker> 
  <assembly fullname="YOUR PROJECT ASSEMBLIES" />
  
  <assembly fullname="Microsoft.Extensions.Options" />

  <assembly fullname="System.Net.Http" />

  <assembly fullname="System.Core">
    <!-- This is required by JSon.NET and any expression.Compile caller -->
    <type fullname="System.Linq.Expressions*" />
  </assembly>
</linker>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/magnetometer.md

---
uid: Uno.Features.Magnetometer
---

# Magnetometer

> [!TIP]
> This article covers Uno-specific information for Magnetometer. For a full description of the feature and instructions on using it, see [Magnetometer Class](https://learn.microsoft.com/uwp/api/windows.devices.sensors.magnetometer).

* The `Windows.Devices.Sensors.Magnetometer` class allows measuring magnetic force affecting the device.

## Supported features

| Feature        |  Windows  | Android |  iOS  |  Web (WASM)  | macOS | Linux (Skia)  | Win 7 (Skia) |
|---------------|-------|-------|-------|-------|-------|-------|-|
| `GetDefault`         | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `ReadingChanged` | ✔ | ✔ | ✔ | ✔ | ✖ | ✖| ✖ |
| `ReportInterval`     | ✔ | ✔ | ✔ | ✔ | ✖ | ✖ | ✖ |

## Using Magnetometer with Uno

* The `GetDefault` method is available on all targets and will return `null` on those which do not support `Magnetometer` or devices which do not have such sensor.
* Ensure to unsubscribe from the `ReadingChanged` event when you no longer need the readings, so that the sensor is no longer active to avoid unnecessary battery consumption.
* `ReportInterval` property on WASM is currently not supported directly. Uno uses an approximation in the form of raising the `ReadingChanged` event, only when enough time has passed since the last report. The event is raised a bit more often to make sure the gap caused by the filter is not too large, but this is in-line with the behavior of Windows' `Magnetometer`.
* `DirectionalAccuracy` is not reported on iOS, so it will always return `Unknown`.

## Example

### Capturing sensor readings

```csharp
var magnetometer = Magnetometer.GetDefault();
magnetometer.ReadingChanged += Magnetometer_ReadingChanged;

private async void Magnetometer_ReadingChanged(Magnetometer sender, MagnetometerReadingChangedEventArgs args)
{
    // If you want to update the UI in some way, ensure the Dispatcher is used,
    // as the ReadingChanged event handler does not run on the UI thread.
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        MagneticFieldX = args.Reading.MagneticFieldX;
        MagneticFieldY = args.Reading.MagneticFieldY;
        MagneticFieldZ = args.Reading.MagneticFieldZ;
        DirectionalAccuracy = args.Reading.DirectionalAccuracy;
        Timestamp = args.Reading.Timestamp.ToString("R");
    });
}
```

### Unsubscribing from the readings

```csharp
magnetometer.ReadingChanged -= Magnetometer_ReadingChanged;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/controls/map-control-support.md

---
uid: Uno.Controls.MapControl
---

# MapControl

The `MapControl` is a control that allows you to display maps in your app. Currently, Uno supports `MapControl` on iOS and Android.

## Architecture

Although `MapControl` is defined in `Uno.UI`, to function, it requires an additional package to be installed, `Uno.UI.Maps`, which supplies the actual implementation. This is done to avoid imposing an unnecessary dependency on applications that don't use maps, and also to allow alternative map providers (eg, Google Maps on iOS) to be easily supported in the future.

The current implementation uses the native UIKit Map for iOS and the Google Play Services Map control for Android.

## How to use MapControl in an Uno Platform app

1. Install the [Uno.WinUI.Maps NuGet package](https://www.nuget.org/packages/Uno.WinUI.Maps/) in the Android and/or iOS head projects of your app.
1. Add the `MapResources` resource dictionary to `Application.Resources` in your `App.xaml` file:

    ```xml
    <Application.Resources>
        <MapResources xmlns="using:Uno.UI.Maps"/>
    </Application.Resources>
    ```

1. (Windows and Android) Obtain an API key for your app, following the instructions below.
1. (Android) Configure permissions in the manifest, following the instructions below.
1. Add `MapControl` to your app (`<MapControl xmlns="using:Microsoft.UI.Xaml.Controls.Maps" />`).

## Sample XAML

Here's a complete sample:

```xml
<Page x:Class="MapControlSample.MainPage"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:local="using:MapControlSample"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      xmlns:maps="using:Microsoft.UI.Xaml.Controls.Maps"
      mc:Ignorable="d"
      Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
        <StackPanel>
            <Slider Minimum="1"
                    Maximum="20"
                    StepFrequency=".5"
                    Header="ZoomLevel"
                    x:Name="zoomSlider"
                    Value="12" />
        </StackPanel>
        <maps:MapControl Grid.Row="1"
                         ZoomLevel="{Binding ElementName=zoomSlider, Path=Value, Mode=TwoWay}" />
    </Grid>
</Page>
```

The above code will display Page with a Map Control and a slider that will be used to change the ZoomLevel.

## Platform support

| Feature                                   | Android | iOS | Wasm |
| ------------------------------------------|:-------:|:---:|:----:|
| Display a map                             |    X    |  X  |      |
| Display a path                            |         |  X  |      |
| Customize pushpins with icon              |         |     |      |
| Fully template pushpins                   |         |     |      |
| Show user's location on map               |         |     |      |
| Toggle native Locate-Me button visibility |         |     |      |
| Toggle native Compass button visibility   |         |     |      |

## Usage

## Get API key for the map component

To use the map component, you will need an API key for Windows and Android. Here are the steps to retrieve it.

### Windows

For the detailed procedure for Windows, see [Request a maps authentication key
](https://learn.microsoft.com/windows/uwp/maps-and-location/authentication-key) documentation.

+ Go to <https://www.bingmapsportal.com>
+ Login to your account or register if you don't have one
+ Go to MyAccount -> Keys
+ Click on create a new key
+ Enter the following information:

  + Application name
  + Application URL (optional)
  + Key type
  + Application type
+ Hit *Create* and get the key

The key will be set as the value for the parameter *MapServiceToken* for the MapControl object.

### Android

+ Create a project in the Google Developers Console.

+ Enable Map Service. In case this is your first time using the Google Maps API you will need to enable it before using it.

    1. Go to <https://console.developers.google.com>
    2. Login with a Google account
    3. Click on "Enable APIs and Services"
    4. Select "Maps SDK for Android" and click on Enable
+ Generate an API key.

    1. If you are coming from step-2 just navigate back until you are again in the dashboard, otherwise, go to <https://console.developers.google.com> and login with a Google account.
    2. Go to the Credentials section on the left-hand side menu
    3. Click on "Create Credentials", then "API key"
    4. Copy the key generated as this will be the one we will use later in the application

**Note:** For apps in production we suggest restricting the keys to be used only by your Android app. This is possible by using the SHA-1 fingerprint of your app.

*For a detailed procedure on how to retrieve the SHA-1 fingerprint for your Android application, please follow this link: <https://developers.google.com/maps/documentation/android-api/signup#release-cert>*

## Configure your application

+ For **Android**
    1. Add the following to AndroidManifest.xml:

        ```xml
        <uses-library android:name="com.google.android.maps" />
        ```

    2. Add the API key to `AssemblyInfo.cs`.

        ```csharp
        [assembly: MetaData("com.google.android.maps.v2.API_KEY", Value = "YOUR_API_KEY")]
        ```

        Replace the text YOUR_API_KEY with the key generated in previous step.

        Note: Since this key might vary depending on the platform and environment we suggest using a constant class where the key could be retrieved from.

    3. Add the relevant permissions to `AssemblyInfo.cs`. For example, if you wish to access the user location

        ```csharp
        [assembly: UsesPermission(Android.Manifest.Permission.AccessFineLocation)]
        [assembly: UsesPermission("com.myapp.permission.MAPS_RECEIVE")]
        [assembly: Permission(Name = "com.myapp.permission.MAPS_RECEIVE", ProtectionLevel = Android.Content.PM.Protection.Signature)]
        ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.themes/refs/heads/master/doc/material-colors.md

---
uid: Uno.Themes.Material.Colors
---

# Material Colors and Brushes

## Colors

| Key                          | LightValue | DarkValue |
|------------------------------|------------|-----------|
| `PrimaryColor`               | `#5946D2`  | `#C7BFFF` |
| `PrimaryInverseColor`        | `#C8BFFF`  | `#2A009F` |
| `OnPrimaryColor`             | `#FFFFFF`  | `#2A009F` |
| `PrimaryContainerColor`      | `#E5DEFF`  | `#4129BA` |
| `OnPrimaryContainerColor`    | `#170065`  | `#E4DFFF` |
| `PrimaryVariantDarkColor`    | `#0021C1`  | `#4128BA` |
| `PrimaryVariantLightColor`   | `#9679FF`  | `#C8BFFF` |
| `SecondaryColor`             | `#6B4EA2`  | `#CDC2DC` |
| `OnSecondaryColor`           | `#FFFFFF`  | `#332D41` |
| `SecondaryContainerColor`    | `#EBDDFF`  | `#433C52` |
| `OnSecondaryContainerColor`  | `#220555`  | `#EDDFFF` |
| `SecondaryVariantDarkColor`  | `#3B2574`  | `#441F8A` |
| `SecondaryVariantLightColor` | `#9B7BD5`  | `#EBE6F1` |
| `TertiaryColor`              | `#0061A4`  | `#9FCAFF` |
| `OnTertiaryColor`            | `#FFFFFF`  | `#003258` |
| `TertiaryContainerColor`     | `#CFE4FF`  | `#00497D` |
| `OnTertiaryContainerColor`   | `#001D36`  | `#D1E4FF` |
| `ErrorColor`                 | `#B3261E`  | `#FFB4AB` |
| `OnErrorColor`               | `#FFFFFF`  | `#690005` |
| `ErrorContainerColor`        | `#F9DEDC`  | `#93000A` |
| `OnErrorContainerColor`      | `#410E0B`  | `#FFDAD6` |
| `BackgroundColor`            | `#FCFBFF`  | `#1C1B1F` |
| `OnBackgroundColor`          | `#1C1B1F`  | `#E5E1E6` |
| `SurfaceColor`               | `#FFFFFF`  | `#302D37` |
| `OnSurfaceColor`             | `#1C1B1F`  | `#E6E1E5` |
| `SurfaceVariantColor`        | `#F2EFF5`  | `#47464F` |
| `OnSurfaceVariantColor`      | `#8A8494`  | `#C9C5D0` |
| `SurfaceInverseColor`        | `#313033`  | `#E6E1E5` |
| `OnSurfaceInverseColor`      | `#F4EFF4`  | `#1C1B1F` |
| `SurfaceTintColor`           | `#5946D2`  | `#C7BFFF` |
| `OutlineColor`               | `#79747E`  | `#928F99` |
| `OutlineVariantColor`        | `#C9C5D0`  | `#57545D` |
| `ShadowColor`                | `#000000`  | `#000000` |

## Opacities

| Key             | Value |
|-----------------|-------|
| HoverOpacity    | 0.08  |
| FocusedOpacity  | 0.12  |
| PressedOpacity  | 0.12  |
| DraggedOpacity  | 0.16  |
| SelectedOpacity | 0.08  |
| MediumOpacity   | 0.64  |
| LowOpacity      | 0.32  |
| DisabledOpacity | 0.12  |

## Brushes

| Key                                | Color                        | Opacity           |
|------------------------------------|------------------------------|-------------------|
| PrimaryBrush                       | `PrimaryColor`               | 1                 |
| PrimaryHoverBrush                  | `PrimaryColor`               | `HoverOpacity`    |
| PrimaryFocusedBrush                | `PrimaryColor`               | `FocusedOpacity`  |
| PrimaryPressedBrush                | `PrimaryColor`               | `PressedOpacity`  |
| PrimaryDraggedBrush                | `PrimaryColor`               | `DraggedOpacity`  |
| PrimarySelectedBrush               | `PrimaryColor`               | `SelectedOpacity` |
| PrimaryMediumBrush                 | `PrimaryColor`               | `MediumOpacity`   |
| PrimaryLowBrush                    | `PrimaryColor`               | `LowOpacity`      |
| PrimaryDisabledBrush               | `PrimaryColor`               | `DisabledOpacity` |
| PrimaryInverseBrush                | `PrimaryInverseColor`        | 1                 |
| PrimaryInverseHoverBrush           | `PrimaryInverseColor`        | `HoverOpacity`    |
| PrimaryInverseFocusedBrush         | `PrimaryInverseColor`        | `FocusedOpacity`  |
| PrimaryInversePressedBrush         | `PrimaryInverseColor`        | `PressedOpacity`  |
| PrimaryInverseDraggedBrush         | `PrimaryInverseColor`        | `DraggedOpacity`  |
| PrimaryInverseSelectedBrush        | `PrimaryInverseColor`        | `SelectedOpacity` |
| PrimaryInverseMediumBrush          | `PrimaryInverseColor`        | `MediumOpacity`   |
| PrimaryInverseLowBrush             | `PrimaryInverseColor`        | `LowOpacity`      |
| PrimaryInverseDisabledBrush        | `PrimaryInverseColor`        | `DisabledOpacity` |
| OnPrimaryBrush                     | `OnPrimaryColor`             | 1                 |
| OnPrimaryHoverBrush                | `OnPrimaryColor`             | `HoverOpacity`    |
| OnPrimaryFocusedBrush              | `OnPrimaryColor`             | `FocusedOpacity`  |
| OnPrimaryPressedBrush              | `OnPrimaryColor`             | `PressedOpacity`  |
| OnPrimaryDraggedBrush              | `OnPrimaryColor`             | `DraggedOpacity`  |
| OnPrimarySelectedBrush             | `OnPrimaryColor`             | `SelectedOpacity` |
| OnPrimaryMediumBrush               | `OnPrimaryColor`             | `MediumOpacity`   |
| OnPrimaryLowBrush                  | `OnPrimaryColor`             | `LowOpacity`      |
| OnPrimaryDisabledBrush             | `OnPrimaryColor`             | `DisabledOpacity` |
| PrimaryContainerBrush              | `PrimaryContainerColor`      | 1                 |
| PrimaryContainerHoverBrush         | `PrimaryContainerColor`      | `HoverOpacity`    |
| PrimaryContainerFocusedBrush       | `PrimaryContainerColor`      | `FocusedOpacity`  |
| PrimaryContainerPressedBrush       | `PrimaryContainerColor`      | `PressedOpacity`  |
| PrimaryContainerDraggedBrush       | `PrimaryContainerColor`      | `DraggedOpacity`  |
| PrimaryContainerSelectedBrush      | `PrimaryContainerColor`      | `SelectedOpacity` |
| PrimaryContainerMediumBrush        | `PrimaryContainerColor`      | `MediumOpacity`   |
| PrimaryContainerLowBrush           | `PrimaryContainerColor`      | `LowOpacity`      |
| PrimaryContainerDisabledBrush      | `PrimaryContainerColor`      | `DisabledOpacity` |
| OnPrimaryContainerBrush            | `OnPrimaryContainerColor`    | 1                 |
| OnPrimaryContainerHoverBrush       | `OnPrimaryContainerColor`    | `HoverOpacity`    |
| OnPrimaryContainerFocusedBrush     | `OnPrimaryContainerColor`    | `FocusedOpacity`  |
| OnPrimaryContainerPressedBrush     | `OnPrimaryContainerColor`    | `PressedOpacity`  |
| OnPrimaryContainerDraggedBrush     | `OnPrimaryContainerColor`    | `DraggedOpacity`  |
| OnPrimaryContainerSelectedBrush    | `OnPrimaryContainerColor`    | `SelectedOpacity` |
| OnPrimaryContainerMediumBrush      | `OnPrimaryContainerColor`    | `MediumOpacity`   |
| OnPrimaryContainerLowBrush         | `OnPrimaryContainerColor`    | `LowOpacity`      |
| OnPrimaryContainerDisabledBrush    | `OnPrimaryContainerColor`    | `DisabledOpacity` |
| PrimaryVariantLightBrush           | `PrimaryVariantLightColor`   | 1                 |
| PrimaryVariantLightHoverBrush      | `PrimaryVariantLightColor`   | `HoverOpacity`    |
| PrimaryVariantLightFocusedBrush    | `PrimaryVariantLightColor`   | `FocusedOpacity`  |
| PrimaryVariantLightPressedBrush    | `PrimaryVariantLightColor`   | `PressedOpacity`  |
| PrimaryVariantLightDraggedBrush    | `PrimaryVariantLightColor`   | `DraggedOpacity`  |
| PrimaryVariantLightSelectedBrush   | `PrimaryVariantLightColor`   | `SelectedOpacity` |
| PrimaryVariantLightMediumBrush     | `PrimaryVariantLightColor`   | `MediumOpacity`   |
| PrimaryVariantLightLowBrush        | `PrimaryVariantLightColor`   | `LowOpacity`      |
| PrimaryVariantLightDisabledBrush   | `PrimaryVariantLightColor`   | `DisabledOpacity` |
| PrimaryVariantDarkBrush            | `PrimaryVariantDarkColor`    | 1                 |
| PrimaryVariantDarkHoverBrush       | `PrimaryVariantDarkColor`    | `HoverOpacity`    |
| PrimaryVariantDarkFocusedBrush     | `PrimaryVariantDarkColor`    | `FocusedOpacity`  |
| PrimaryVariantDarkPressedBrush     | `PrimaryVariantDarkColor`    | `PressedOpacity`  |
| PrimaryVariantDarkDraggedBrush     | `PrimaryVariantDarkColor`    | `DraggedOpacity`  |
| PrimaryVariantDarkSelectedBrush    | `PrimaryVariantDarkColor`    | `SelectedOpacity` |
| PrimaryVariantDarkMediumBrush      | `PrimaryVariantDarkColor`    | `MediumOpacity`   |
| PrimaryVariantDarkLowBrush         | `PrimaryVariantDarkColor`    | `LowOpacity`      |
| PrimaryVariantDarkDisabledBrush    | `PrimaryVariantDarkColor`    | `DisabledOpacity` |
| SecondaryBrush                     | `SecondaryColor`             | 1                 |
| SecondaryHoverBrush                | `SecondaryColor`             | `HoverOpacity`    |
| SecondaryFocusedBrush              | `SecondaryColor`             | `FocusedOpacity`  |
| SecondaryPressedBrush              | `SecondaryColor`             | `PressedOpacity`  |
| SecondaryDraggedBrush              | `SecondaryColor`             | `DraggedOpacity`  |
| SecondarySelectedBrush             | `SecondaryColor`             | `SelectedOpacity` |
| SecondaryMediumBrush               | `SecondaryColor`             | `MediumOpacity`   |
| SecondaryLowBrush                  | `SecondaryColor`             | `LowOpacity`      |
| SecondaryDisabledBrush             | `SecondaryColor`             | `DisabledOpacity` |
| OnSecondaryBrush                   | `OnSecondaryColor`           | 1                 |
| OnSecondaryHoverBrush              | `OnSecondaryColor`           | `HoverOpacity`    |
| OnSecondaryFocusedBrush            | `OnSecondaryColor`           | `FocusedOpacity`  |
| OnSecondaryPressedBrush            | `OnSecondaryColor`           | `PressedOpacity`  |
| OnSecondaryDraggedBrush            | `OnSecondaryColor`           | `DraggedOpacity`  |
| OnSecondarySelectedBrush           | `OnSecondaryColor`           | `SelectedOpacity` |
| OnSecondaryMediumBrush             | `OnSecondaryColor`           | `MediumOpacity`   |
| OnSecondaryLowBrush                | `OnSecondaryColor`           | `LowOpacity`      |
| OnSecondaryDisabledBrush           | `OnSecondaryColor`           | `DisabledOpacity` |
| SecondaryContainerBrush            | `SecondaryContainerColor`    | 1                 |
| SecondaryContainerHoverBrush       | `SecondaryContainerColor`    | `HoverOpacity`    |
| SecondaryContainerFocusedBrush     | `SecondaryContainerColor`    | `FocusedOpacity`  |
| SecondaryContainerPressedBrush     | `SecondaryContainerColor`    | `PressedOpacity`  |
| SecondaryContainerDraggedBrush     | `SecondaryContainerColor`    | `DraggedOpacity`  |
| SecondaryContainerSelectedBrush    | `SecondaryContainerColor`    | `SelectedOpacity` |
| SecondaryContainerMediumBrush      | `SecondaryContainerColor`    | `MediumOpacity`   |
| SecondaryContainerLowBrush         | `SecondaryContainerColor`    | `LowOpacity`      |
| SecondaryContainerDisabledBrush    | `SecondaryContainerColor`    | `DisabledOpacity` |
| OnSecondaryContainerBrush          | `OnSecondaryContainerColor`  | 1                 |
| OnSecondaryContainerHoverBrush     | `OnSecondaryContainerColor`  | `HoverOpacity`    |
| OnSecondaryContainerFocusedBrush   | `OnSecondaryContainerColor`  | `FocusedOpacity`  |
| OnSecondaryContainerPressedBrush   | `OnSecondaryContainerColor`  | `PressedOpacity`  |
| OnSecondaryContainerDraggedBrush   | `OnSecondaryContainerColor`  | `DraggedOpacity`  |
| OnSecondaryContainerSelectedBrush  | `OnSecondaryContainerColor`  | `SelectedOpacity` |
| OnSecondaryContainerMediumBrush    | `OnSecondaryContainerColor`  | `MediumOpacity`   |
| OnSecondaryContainerLowBrush       | `OnSecondaryContainerColor`  | `LowOpacity`      |
| OnSecondaryContainerDisabledBrush  | `OnSecondaryContainerColor`  | `DisabledOpacity` |
| SecondaryVariantLightBrush         | `SecondaryVariantLightColor` | 1                 |
| SecondaryVariantLightHoverBrush    | `SecondaryVariantLightColor` | `HoverOpacity`    |
| SecondaryVariantLightFocusedBrush  | `SecondaryVariantLightColor` | `FocusedOpacity`  |
| SecondaryVariantLightPressedBrush  | `SecondaryVariantLightColor` | `PressedOpacity`  |
| SecondaryVariantLightDraggedBrush  | `SecondaryVariantLightColor` | `DraggedOpacity`  |
| SecondaryVariantLightSelectedBrush | `SecondaryVariantLightColor` | `SelectedOpacity` |
| SecondaryVariantLightMediumBrush   | `SecondaryVariantLightColor` | `MediumOpacity`   |
| SecondaryVariantLightLowBrush      | `SecondaryVariantLightColor` | `LowOpacity`      |
| SecondaryVariantLightDisabledBrush | `SecondaryVariantLightColor` | `DisabledOpacity` |
| SecondaryVariantDarkBrush          | `SecondaryVariantDarkColor`  | 1                 |
| SecondaryVariantDarkHoverBrush     | `SecondaryVariantDarkColor`  | `HoverOpacity`    |
| SecondaryVariantDarkFocusedBrush   | `SecondaryVariantDarkColor`  | `FocusedOpacity`  |
| SecondaryVariantDarkPressedBrush   | `SecondaryVariantDarkColor`  | `PressedOpacity`  |
| SecondaryVariantDarkDraggedBrush   | `SecondaryVariantDarkColor`  | `DraggedOpacity`  |
| SecondaryVariantDarkSelectedBrush  | `SecondaryVariantDarkColor`  | `SelectedOpacity` |
| SecondaryVariantDarkMediumBrush    | `SecondaryVariantDarkColor`  | `MediumOpacity`   |
| SecondaryVariantDarkLowBrush       | `SecondaryVariantDarkColor`  | `LowOpacity`      |
| SecondaryVariantDarkDisabledBrush  | `SecondaryVariantDarkColor`  | `DisabledOpacity` |
| TertiaryBrush                      | `TertiaryColor`              | 1                 |
| TertiaryHoverBrush                 | `TertiaryColor`              | `HoverOpacity`    |
| TertiaryFocusedBrush               | `TertiaryColor`              | `FocusedOpacity`  |
| TertiaryPressedBrush               | `TertiaryColor`              | `PressedOpacity`  |
| TertiaryDraggedBrush               | `TertiaryColor`              | `DraggedOpacity`  |
| TertiarySelectedBrush              | `TertiaryColor`              | `SelectedOpacity` |
| TertiaryMediumBrush                | `TertiaryColor`              | `MediumOpacity`   |
| TertiaryLowBrush                   | `TertiaryColor`              | `LowOpacity`      |
| TertiaryDisabledBrush              | `TertiaryColor`              | `DisabledOpacity` |
| OnTertiaryBrush                    | `OnTertiaryColor`            | 1                 |
| OnTertiaryHoverBrush               | `OnTertiaryColor`            | `HoverOpacity`    |
| OnTertiaryFocusedBrush             | `OnTertiaryColor`            | `FocusedOpacity`  |
| OnTertiaryPressedBrush             | `OnTertiaryColor`            | `PressedOpacity`  |
| OnTertiaryDraggedBrush             | `OnTertiaryColor`            | `DraggedOpacity`  |
| OnTertiarySelectedBrush            | `OnTertiaryColor`            | `SelectedOpacity` |
| OnTertiaryMediumBrush              | `OnTertiaryColor`            | `MediumOpacity`   |
| OnTertiaryLowBrush                 | `OnTertiaryColor`            | `LowOpacity`      |
| OnTertiaryDisabledBrush            | `OnTertiaryColor`            | `DisabledOpacity` |
| TertiaryContainerBrush             | `TertiaryContainerColor`     | 1                 |
| TertiaryContainerHoverBrush        | `TertiaryContainerColor`     | `HoverOpacity`    |
| TertiaryContainerFocusedBrush      | `TertiaryContainerColor`     | `FocusedOpacity`  |
| TertiaryContainerPressedBrush      | `TertiaryContainerColor`     | `PressedOpacity`  |
| TertiaryContainerDraggedBrush      | `TertiaryContainerColor`     | `DraggedOpacity`  |
| TertiaryContainerSelectedBrush     | `TertiaryContainerColor`     | `SelectedOpacity` |
| TertiaryContainerMediumBrush       | `TertiaryContainerColor`     | `MediumOpacity`   |
| TertiaryContainerLowBrush          | `TertiaryContainerColor`     | `LowOpacity`      |
| TertiaryContainerDisabledBrush     | `TertiaryContainerColor`     | `DisabledOpacity` |
| OnTertiaryContainerBrush           | `OnTertiaryContainerColor`   | 1                 |
| OnTertiaryContainerHoverBrush      | `OnTertiaryContainerColor`   | `HoverOpacity`    |
| OnTertiaryContainerFocusedBrush    | `OnTertiaryContainerColor`   | `FocusedOpacity`  |
| OnTertiaryContainerPressedBrush    | `OnTertiaryContainerColor`   | `PressedOpacity`  |
| OnTertiaryContainerDraggedBrush    | `OnTertiaryContainerColor`   | `DraggedOpacity`  |
| OnTertiaryContainerSelectedBrush   | `OnTertiaryContainerColor`   | `SelectedOpacity` |
| OnTertiaryContainerMediumBrush     | `OnTertiaryContainerColor`   | `MediumOpacity`   |
| OnTertiaryContainerLowBrush        | `OnTertiaryContainerColor`   | `LowOpacity`      |
| OnTertiaryContainerDisabledBrush   | `OnTertiaryContainerColor`   | `DisabledOpacity` |
| ErrorBrush                         | `ErrorColor`                 | 1                 |
| ErrorHoverBrush                    | `ErrorColor`                 | `HoverOpacity`    |
| ErrorFocusedBrush                  | `ErrorColor`                 | `FocusedOpacity`  |
| ErrorPressedBrush                  | `ErrorColor`                 | `PressedOpacity`  |
| ErrorDraggedBrush                  | `ErrorColor`                 | `DraggedOpacity`  |
| ErrorSelectedBrush                 | `ErrorColor`                 | `SelectedOpacity` |
| ErrorMediumBrush                   | `ErrorColor`                 | `MediumOpacity`   |
| ErrorLowBrush                      | `ErrorColor`                 | `LowOpacity`      |
| ErrorDisabledBrush                 | `ErrorColor`                 | `DisabledOpacity` |
| OnErrorBrush                       | `OnErrorColor`               | 1                 |
| OnErrorHoverBrush                  | `OnErrorColor`               | `HoverOpacity`    |
| OnErrorFocusedBrush                | `OnErrorColor`               | `FocusedOpacity`  |
| OnErrorPressedBrush                | `OnErrorColor`               | `PressedOpacity`  |
| OnErrorDraggedBrush                | `OnErrorColor`               | `DraggedOpacity`  |
| OnErrorSelectedBrush               | `OnErrorColor`               | `SelectedOpacity` |
| OnErrorMediumBrush                 | `OnErrorColor`               | `MediumOpacity`   |
| OnErrorLowBrush                    | `OnErrorColor`               | `LowOpacity`      |
| OnErrorDisabledBrush               | `OnErrorColor`               | `DisabledOpacity` |
| ErrorContainerBrush                | `ErrorContainerColor`        | 1                 |
| ErrorContainerHoverBrush           | `ErrorContainerColor`        | `HoverOpacity`    |
| ErrorContainerFocusedBrush         | `ErrorContainerColor`        | `FocusedOpacity`  |
| ErrorContainerPressedBrush         | `ErrorContainerColor`        | `PressedOpacity`  |
| ErrorContainerDraggedBrush         | `ErrorContainerColor`        | `DraggedOpacity`  |
| ErrorContainerSelectedBrush        | `ErrorContainerColor`        | `SelectedOpacity` |
| ErrorContainerMediumBrush          | `ErrorContainerColor`        | `MediumOpacity`   |
| ErrorContainerLowBrush             | `ErrorContainerColor`        | `LowOpacity`      |
| ErrorContainerDisabledBrush        | `ErrorContainerColor`        | `DisabledOpacity` |
| OnErrorContainerBrush              | `OnErrorContainerColor`      | 1                 |
| OnErrorContainerHoverBrush         | `OnErrorContainerColor`      | `HoverOpacity`    |
| OnErrorContainerFocusedBrush       | `OnErrorContainerColor`      | `FocusedOpacity`  |
| OnErrorContainerPressedBrush       | `OnErrorContainerColor`      | `PressedOpacity`  |
| OnErrorContainerDraggedBrush       | `OnErrorContainerColor`      | `DraggedOpacity`  |
| OnErrorContainerSelectedBrush      | `OnErrorContainerColor`      | `SelectedOpacity` |
| OnErrorContainerMediumBrush        | `OnErrorContainerColor`      | `MediumOpacity`   |
| OnErrorContainerLowBrush           | `OnErrorContainerColor`      | `LowOpacity`      |
| OnErrorContainerDisabledBrush      | `OnErrorContainerColor`      | `DisabledOpacity` |
| BackgroundBrush                    | `BackgroundColor`            | 1                 |
| BackgroundHoverBrush               | `BackgroundColor`            | `HoverOpacity`    |
| BackgroundFocusedBrush             | `BackgroundColor`            | `FocusedOpacity`  |
| BackgroundPressedBrush             | `BackgroundColor`            | `PressedOpacity`  |
| BackgroundDraggedBrush             | `BackgroundColor`            | `DraggedOpacity`  |
| BackgroundSelectedBrush            | `BackgroundColor`            | `SelectedOpacity` |
| BackgroundMediumBrush              | `BackgroundColor`            | `MediumOpacity`   |
| BackgroundLowBrush                 | `BackgroundColor`            | `LowOpacity`      |
| BackgroundDisabledBrush            | `BackgroundColor`            | `DisabledOpacity` |
| OnBackgroundBrush                  | `OnBackgroundColor`          | 1                 |
| OnBackgroundHoverBrush             | `OnBackgroundColor`          | `HoverOpacity`    |
| OnBackgroundFocusedBrush           | `OnBackgroundColor`          | `FocusedOpacity`  |
| OnBackgroundPressedBrush           | `OnBackgroundColor`          | `PressedOpacity`  |
| OnBackgroundDraggedBrush           | `OnBackgroundColor`          | `DraggedOpacity`  |
| OnBackgroundSelectedBrush          | `OnBackgroundColor`          | `SelectedOpacity` |
| OnBackgroundMediumBrush            | `OnBackgroundColor`          | `MediumOpacity`   |
| OnBackgroundLowBrush               | `OnBackgroundColor`          | `LowOpacity`      |
| OnBackgroundDisabledBrush          | `OnBackgroundColor`          | `DisabledOpacity` |
| SurfaceBrush                       | `SurfaceColor`               | 1                 |
| SurfaceHoverBrush                  | `SurfaceColor`               | `HoverOpacity`    |
| SurfaceFocusedBrush                | `SurfaceColor`               | `FocusedOpacity`  |
| SurfacePressedBrush                | `SurfaceColor`               | `PressedOpacity`  |
| SurfaceDraggedBrush                | `SurfaceColor`               | `DraggedOpacity`  |
| SurfaceSelectedBrush               | `SurfaceColor`               | `SelectedOpacity` |
| SurfaceMediumBrush                 | `SurfaceColor`               | `MediumOpacity`   |
| SurfaceLowBrush                    | `SurfaceColor`               | `LowOpacity`      |
| SurfaceDisabledBrush               | `SurfaceColor`               | `DisabledOpacity` |
| OnSurfaceBrush                     | `OnSurfaceColor`             | 1                 |
| OnSurfaceHoverBrush                | `OnSurfaceColor`             | `HoverOpacity`    |
| OnSurfaceFocusedBrush              | `OnSurfaceColor`             | `FocusedOpacity`  |
| OnSurfacePressedBrush              | `OnSurfaceColor`             | `PressedOpacity`  |
| OnSurfaceDraggedBrush              | `OnSurfaceColor`             | `DraggedOpacity`  |
| OnSurfaceSelectedBrush             | `OnSurfaceColor`             | `SelectedOpacity` |
| OnSurfaceMediumBrush               | `OnSurfaceColor`             | `MediumOpacity`   |
| OnSurfaceLowBrush                  | `OnSurfaceColor`             | `DisabledOpacity` |
| OnSurfaceDisabledBrush             | `OnSurfaceColor`             | `DisabledOpacity` |
| SurfaceVariantBrush                | `SurfaceVariantColor`        | 1                 |
| SurfaceVariantHoverBrush           | `SurfaceVariantColor`        | `HoverOpacity`    |
| SurfaceVariantFocusedBrush         | `SurfaceVariantColor`        | `FocusedOpacity`  |
| SurfaceVariantPressedBrush         | `SurfaceVariantColor`        | `PressedOpacity`  |
| SurfaceVariantDraggedBrush         | `SurfaceVariantColor`        | `DraggedOpacity`  |
| SurfaceVariantSelectedBrush        | `SurfaceVariantColor`        | `SelectedOpacity` |
| SurfaceVariantMediumBrush          | `SurfaceVariantColor`        | `MediumOpacity`   |
| SurfaceVariantLowBrush             | `SurfaceVariantColor`        | `LowOpacity`      |
| SurfaceVariantDisabledBrush        | `SurfaceVariantColor`        | `DisabledOpacity` |
| OnSurfaceVariantBrush              | `OnSurfaceVariantColor`      | 1                 |
| OnSurfaceVariantHoverBrush         | `OnSurfaceVariantColor`      | `HoverOpacity`    |
| OnSurfaceVariantFocusedBrush       | `OnSurfaceVariantColor`      | `FocusedOpacity`  |
| OnSurfaceVariantPressedBrush       | `OnSurfaceVariantColor`      | `PressedOpacity`  |
| OnSurfaceVariantDraggedBrush       | `OnSurfaceVariantColor`      | `DraggedOpacity`  |
| OnSurfaceVariantSelectedBrush      | `OnSurfaceVariantColor`      | `SelectedOpacity` |
| OnSurfaceVariantMediumBrush        | `OnSurfaceVariantColor`      | `MediumOpacity`   |
| OnSurfaceVariantLowBrush           | `OnSurfaceVariantColor`      | `LowOpacity`      |
| OnSurfaceVariantDisabledBrush      | `OnSurfaceVariantColor`      | `DisabledOpacity` |
| SurfaceInverseBrush                | `SurfaceInverseColor`        | 1                 |
| SurfaceInverseHoverBrush           | `SurfaceInverseColor`        | `HoverOpacity`    |
| SurfaceInverseFocusedBrush         | `SurfaceInverseColor`        | `FocusedOpacity`  |
| SurfaceInversePressedBrush         | `SurfaceInverseColor`        | `PressedOpacity`  |
| SurfaceInverseDraggedBrush         | `SurfaceInverseColor`        | `DraggedOpacity`  |
| SurfaceInverseSelectedBrush        | `SurfaceInverseColor`        | `SelectedOpacity` |
| SurfaceInverseMediumBrush          | `SurfaceInverseColor`        | `MediumOpacity`   |
| SurfaceInverseLowBrush             | `SurfaceInverseColor`        | `LowOpacity`      |
| SurfaceInverseDisabledBrush        | `SurfaceInverseColor`        | `DisabledOpacity` |
| OnSurfaceInverseBrush              | `OnSurfaceInverseColor`      | 1                 |
| OnSurfaceInverseHoverBrush         | `OnSurfaceInverseColor`      | `HoverOpacity`    |
| OnSurfaceInverseFocusedBrush       | `OnSurfaceInverseColor`      | `FocusedOpacity`  |
| OnSurfaceInversePressedBrush       | `OnSurfaceInverseColor`      | `PressedOpacity`  |
| OnSurfaceInverseDraggedBrush       | `OnSurfaceInverseColor`      | `DraggedOpacity`  |
| OnSurfaceInverseSelectedBrush      | `OnSurfaceInverseColor`      | `SelectedOpacity` |
| OnSurfaceInverseMediumBrush        | `OnSurfaceInverseColor`      | `MediumOpacity`   |
| OnSurfaceInverseLowBrush           | `OnSurfaceInverseColor`      | `LowOpacity`      |
| OnSurfaceInverseDisabledBrush      | `OnSurfaceInverseColor`      | `DisabledOpacity` |
| OutlineBrush                       | `OutlineColor`               | 1                 |
| OutlineHoverBrush                  | `OutlineColor`               | `HoverOpacity`    |
| OutlineFocusedBrush                | `OutlineColor`               | `FocusedOpacity`  |
| OutlinePressedBrush                | `OutlineColor`               | `PressedOpacity`  |
| OutlineDraggedBrush                | `OutlineColor`               | `DraggedOpacity`  |
| OutlineSelectedBrush               | `OutlineColor`               | `SelectedOpacity` |
| OutlineMediumBrush                 | `OutlineColor`               | `MediumOpacity`   |
| OutlineLowBrush                    | `OutlineColor`               | `LowOpacity`      |
| OutlineDisabledBrush               | `OutlineColor`               | `DisabledOpacity` |
| OutlineVariantBrush                | `OutlineVariantColor`        | 1                 |
| OutlineVariantHoverBrush           | `OutlineVariantColor`        | `HoverOpacity`    |
| OutlineVariantFocusedBrush         | `OutlineVariantColor`        | `FocusedOpacity`  |
| OutlineVariantPressedBrush         | `OutlineVariantColor`        | `PressedOpacity`  |
| OutlineVariantDraggedBrush         | `OutlineVariantColor`        | `DraggedOpacity`  |
| OutlineVariantSelectedBrush        | `OutlineVariantColor`        | `SelectedOpacity` |
| OutlineVariantMediumBrush          | `OutlineVariantColor`        | `MediumOpacity`   |
| OutlineVariantLowBrush             | `OutlineVariantColor`        | `LowOpacity`      |
| OutlineVariantDisabledBrush        | `OutlineVariantColor`        | `DisabledOpacity` |
| SurfaceTintBrush                   | `SurfaceTintColor`           | 1                 |

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.themes/refs/heads/master/doc/material-dsp.md

---
uid: Uno.Themes.Material.DSP
---

# Using the DSP Tooling in Uno.Material

## Introduction

Is it possible to automate the creation of the Material Design color palette? Yes, it is. Uno.Material provides a tooling to generate the color palette from the official Material Design color palette. This tooling is available in the [Uno.Dsp.Cli](https://nuget.org/packages/Uno.Dsp.Cli) and [Uno.Dsp.Tasks](https://nuget.org/packages/Uno.Dsp.Tasks) NuGet packages. The following instructions will cover the Uno.Dsp.Tasks version, which is more automatic.

> [!NOTE]
> Make sure you are referencing the generated XAML file in your
> application's `App.xaml` file, as shown in the following example:
>
> ```xml
>  <MaterialTheme xmlns="using:Uno.Material"
>                 ColorOverrideSource="ms-appx:///PROJECT_NAME/Styles/Application/MaterialColorsOverride.xaml" />
> ```
>
> More details [In the _Manual Color Overrides_ section of the Getting Started page](xref:Uno.Themes.Material.GetStarted)

## The Uno.Dsp.Tasks NuGet package

This package will be automatically present in the project after [creating a new Uno Platform project](https://aka.platform.uno/get-started) specifying the _Material_ theme. It is also possible to add it manually to an existing Uno Platform project by adding the following line to the _PackageReference_ section of the _csproj_ file:

* Add a nuget package reference:

   ```xml
   <PackageReference Include="Uno.Dsp.Tasks" Version="[latest version]" />
   ```

* The package is already present when you select _Material_ theme during project creation:
   ![Selection of Material theme when creating a project using the Uno Template Wizard](assets/material-theme-selection-wizard.png)

It is possible to configure the import process. The _UnoDspImportColors_ item found in the _csproj_ file has a number of attributes we can set:

| Attribute        | Description                     | Default Value           |
|------------------|---------------------------------|-------------------------|
| `Include`        | Style files to input            |                         |
| `Generator`*     | Type of generator to use        | `Xaml`                  |
| `OutputPath`**   | Path to use for the output      | Input file directory    |

\* The possible values for `Generator` are `Xaml` or `Csharp`.

\*\* If `Include` is a glob (eg: \*.json), `OutputPath` should be a directory.

```xml
<ItemGroup>
   <UnoDspImportColors Include="Styles\*.json" Generator="Csharp" OutputPath="Styles\Theme\"  />
</ItemGroup>
```

## Generating a custom color palette and exporting it as a JSON file

1. Navigate to the [Material Theme Builder](https://aka.platform.uno/uno-material-themebuilder) and select the colors you want to use for your application.
2. When you are done customizing, open the **Export** section located at the top rightmost of the screen.

   ![material-theme-export-section](assets/material-theme-export-section.png)
3. In the **Export** section, locate the _Export_ button and pick the _Material Theme (JSON)_ format.

   ![material-theme-export-button](assets/material-theme-export-button.png) ![material-theme-export-json](assets/material-theme-export-json.png)
4. Save the file to your computer.
5. Replace the `ColorPaletteOverride.json` file in the `Styles` folder of your application project with the one you just downloaded.
6. Build your application. The `ColorPaletteOverride.xaml` file will be automatically updated with the colors present in the JSON file.

## More flexibility

Using `Uno.Dsp.Tasks` will generate the file at each build, potentially overriding any changes you made to it. If you want to keep it that way, you can remove the `ColorPaletteOverride.json` file from the `Styles` folder so it won't get overwritten.

Alternatively, you can use the [Uno.Dsp.Cli](https://nuget.org/packages/Uno.Dsp.Cli) package to generate the file from the command line. This tool allows you to generate the file only when desired rather than during every build.

> [!NOTE]
> Although the **Material Theme Builder Tool** doesn't export **Material Tokens (DSP)** packages anymore, to import DSP packages just follow the same steps described previously and save the downloaded DSP zip file as `ColorPaletteOverride.zip` in the `Styles` folder of your application project.
> In that case, make sure to delete the `material-theme.json` file from `Styles` folder before building your application, to avoid conflicts.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.toolkit.ui/refs/heads/main/doc/material-getting-started.md

# Source: https://raw.githubusercontent.com/unoplatform/uno.themes/refs/heads/master/doc/material-getting-started.md

# Source: https://raw.githubusercontent.com/unoplatform/uno.toolkit.ui/refs/heads/main/doc/material-getting-started.md

---
uid: Toolkit.GettingStarted.Material
---
# Uno Material Toolkit Library

<p align="center">
  <img src="assets/material-toolkit-design-system.png" alt="Material Toolkit Design System">
</p>

The Uno Material Toolkit provides a set of resources and styles based on [Material Design guidelines](https://m3.material.io/) for the controls included in the base [Uno Toolkit library](xref:Toolkit.GettingStarted)

## Getting Started

Initialization of the Material Toolkit resources is handled by the specialized `MaterialToolkitTheme` ResourceDictionary.

### `MaterialToolkitTheme`

> [!NOTE]
> The `MaterialToolkitTheme` class also handles the required initialization of the Uno Material resources. Therefore, there is no need to initialize `MaterialTheme` within the `App.xaml`

#### Constructors

| Constructor                                                                                 | Description                                                                                                  |
|---------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|
| `MaterialToolkitTheme()`                                                                    | Initializes a new instance of the `MaterialToolkitTheme` resource dictionary.                                |
| `MaterialToolkitTheme(ResourceDictionary? colorOverride, ResourceDictionary? fontOverride)` | Initializes a new instance of the `MaterialToolkitTheme` resource dictionary and applies the given overrides |

#### Properties

| Property              | Type     | Description                                                                                                                                                                            |
|-----------------------|----------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `ColorOverrideSource` | `string` | (Optional) Gets or sets a Uniform Resource Identifier that provides the source location of a ResourceDictionary containing overrides for the default Uno.Material Color resources      |
| `FontOverrideSource`  | `string` | (Optional) Gets or sets a Uniform Resource Identifier that provides the source location of a ResourceDictionary containing overrides for the default Uno.Material FontFamily resources |

## Installation

> [!NOTE]
> Make sure to setup your environment first by [following our instructions](xref:Uno.GetStarted.vs2022).

### Creating a new project with the Uno Material Toolkit

#### [**Wizard**](#tab/wizard)

1. Follow the steps in the [Getting Started with Visual Studio](xref:Uno.GettingStarted.CreateAnApp.VS2022#create-the-app) instructions to launch the Uno Platform Template Wizard.
2. Select `Material` under the `Theme` section.

    ![Material selection in the Uno Platform Template Wizard](assets/material-toolkit-wizard-theme.png)

3. Select `Toolkit` under the `Features` section.

    ![Toolkit selection in the Uno Platform Template Wizard](assets/material-toolkit-wizard-feature.png)

#### [**CLI**](#tab/cli)

1. Install the [`dotnet new` CLI templates](xref:Uno.GetStarted.dotnet-new) with:

    ```bash
    dotnet new install Uno.Templates
    ```

2. Create a new application with:

    ```bash
    dotnet new unoapp -o MaterialToolkitApp -toolkit -theme material
    ```

---

### Installing Uno Material Toolkit in an existing project

Depending on the type of project template that the Uno Platform application was created with, follow the instructions below to install the Uno Material Toolkit.

#### [**Single Project Template**](#tab/singleproj)

1. Edit your project file (`PROJECT_NAME.csproj`) and add `Toolkit` and `Material` to the list of `UnoFeatures`:

    ```xml
    <UnoFeatures>Toolkit;Material</UnoFeatures>
    ```

2. Initialize `MaterialToolkitTheme` in the `App.xaml`:

    ```xml
    <Application.Resources>
        <ResourceDictionary>
            <ResourceDictionary.MergedDictionaries>

                <!-- Code omitted of brevity -->

                <MaterialToolkitTheme xmlns="using:Uno.Toolkit.UI.Material" />
            </ResourceDictionary.MergedDictionaries>
        </ResourceDictionary>
    </Application.Resources>
    ```

#### [**Multi-Head Project Template (Legacy)**](#tab/multihead)

1. In the Solution Explorer panel, right-click on your app's **App Code Library** project (`PROJECT_NAME.csproj`) and select `Manage NuGet Packages...`
2. Install the [`Uno.Toolkit.WinUI.Material`](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material)
3. Add the `MaterialToolkitTheme` to `AppResources.xaml`:

    ```xml
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>

            <MaterialToolkitTheme xmlns="using:Uno.Toolkit.UI.Material" />

        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
    ```

#### [**Shared Project (.shproj) Template (Legacy)**](#tab/shproj)

1. In the Solution Explorer panel, right-click on your solution name and select `Manage NuGet Packages for Solution ...`. Choose either:
     - The [`Uno.Toolkit.UI.Material`](https://www.nuget.org/packages/Uno.Toolkit.UI.Material/) package when targetting Xamarin/UWP
     - The [`Uno.Toolkit.WinUI.Material`](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material) package when targetting net6.0+/WinUI

2. Select the following projects for installation:
    - `PROJECT_NAME.Wasm.csproj`
    - `PROJECT_NAME.Mobile.csproj` (or `PROJECT_NAME.iOS.csproj`, `PROJECT_NAME.Droid.csproj`, and `PROJECT_NAME.macOS.csproj` if you have an existing project)
    - `PROJECT_NAME.Skia.Gtk.csproj`
    - `PROJECT_NAME.Skia.WPF.csproj`
    - `PROJECT_NAME.Windows.csproj` (or `PROJECT_NAME.UWP.csproj` for existing projects)
3. Add the following resources inside `App.xaml`:

    ```xml
    <Application ...>
        <Application.Resources>
            <ResourceDictionary>
                <ResourceDictionary.MergedDictionaries>

                    <!-- Load WinUI resources -->
                    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />

                    <MaterialToolkitTheme xmlns="using:Uno.Toolkit.UI.Material" />

                    <!-- Load custom application resources -->
                    <!-- ... -->

                </ResourceDictionary.MergedDictionaries>
            </ResourceDictionary>
        </Application.Resources>
    </Application>
    ```

---

## Customization

With `MaterialToolkitTheme`, you do not need to explicitly initialize `ToolkitResources`, `MaterialTheme`, `MaterialColors`, or `MaterialFonts`. This means that all resource overrides should go through `MaterialToolkitTheme` itself. There are two properties on `MaterialToolkitTheme` that you can set within your `App.xaml`.

### Customize Colors

Follow the [Uno Material Customization guide](xref:Uno.Themes.Material.GetStarted#customization) to create a `ColorPaletteOverride.xaml` file and add it to your application project.

In `App.xaml`, use the `ColorOverrideSource` property on `MaterialToolkitTheme`:

```xml
<MaterialToolkitTheme xmlns="using:Uno.Toolkit.UI.Material"
                      ColorOverrideSource="ms-appx:///Style/Application/ColorPaletteOverride.xaml" />
```

### Customize Fonts

Follow the [Uno Material Customization guide](xref:Uno.Themes.Material.GetStarted#customization) to create a `FontOverride.xaml` file and add it to your application project.

In `App.xaml`, use the `FontOverrideSource` property on `MaterialToolkitTheme`:

```xml
<MaterialToolkitTheme xmlns="using:Uno.Toolkit.UI.Material"
                      FontOverrideSource="ms-appx:///Style/Application/FontOverride.xaml" />
```

## Using C# Markup

The Uno Material Toolkit library also has support for C# Markup through a [Uno.Toolkit.WinUI.Material.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material.Markup) NuGet Package.

To get started with the Uno Material Toolkit in your C# Markup application, add the `Uno.Toolkit.WinUI.Material.Markup` NuGet package to your application project.
Then, add the following code to your `App.xaml.cs`:

```csharp
using Uno.Toolkit.UI.Material.Markup;

this.Build(r => r.UseMaterialToolkit(
    //optional
    new Styles.ColorPaletteOverride(),
    //optional
    new Styles.MaterialFontsOverride()
));
```

> [!NOTE]
> The [Uno.Toolkit.WinUI.Material.Markup](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Material.Markup) NuGet package includes the base [Uno Toolkit Markup package](https://www.nuget.org/packages/Uno.Toolkit.WinUI.Markup) as a dependency. Therefore, there is no need to add the `Uno.Toolkit.WinUI.Markup` package separately. Furthermore, the `UseMaterialToolkit` extension method also initializes the base Uno Toolkit library, so there is no need to call the `UseToolkit` extension method in your `App.xaml.cs`.

## Additional Resources

- [Uno Platform Material Toolkit Sample App](https://aka.platform.uno/unomaterialtoolkit-sampleapp)
- [Uno Platform Material Toolkit Figma File](https://aka.platform.uno/uno-figma-material-toolkit)
- [Official Material Design 3 Guidelines](https://m3.material.io/components)
- [Official Material Design 3 Theme Builder](https://m3.material.io/theme-builder)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-apps.md

---
uid: Uno.Development.MigratingApps
---

# Migrating a WinUI/UWP-only application codebase to an Uno Platform application

This article describes how to migrate a C# and XAML application targeting only WinUI/UWP to one targeting multiple platforms using Uno Platform. The final application codebase will share 99% of the same code as the original, but the solution structure will be different.

It assumes you're using Visual Studio for Windows, but the steps are similar if you're using VS Code or another IDE. The basic principle is to create an empty Uno Platform app with the same name as your WinUI/UWP-only app and to copy the contents of the old app into the main project of the new app.

After you've migrated the files and dependencies, the general [migration guidance article](migrating-guidance.md) will take you through the final steps to adjust your code to be Uno-compatible.

## Prerequisites

Follow the instructions to [set up your development environment for Uno Platform with Visual Studio for Windows](xref:Uno.GetStarted.vs2022). You can also use another IDE such as [VS Code](xref:Uno.GetStarted.vscode), however some steps may be slightly different.

## Migrating files to the Uno solution structure

Note: these steps will **destructively modify** your existing WinUI/UWP-only solution. Make sure you have a copy in source control or in a backup folder.

1. In order to reuse the name of the existing WinUI/UWP project, we want to first rename it and its containing folder. (If you don't want to reuse the name, you can skip this step.)

    i. First, rename the project itself within the solution by right-clicking on the project and choosing 'Rename'. For example, if the project is called `BugTracker`, we can rename it to `BugTracker_OLD`.

    ii. Next the folder containing the project must be renamed (assuming it still has the default name from when the project was originally created). Navigate to the folder containing the project. (Eg, by right-clicking on the project in Visual Studio and choosing 'Open Folder in File Explorer'.) Close your Visual Studio instance. Rename the folder, so that the project path becomes `./BugTracker_OLD/BugTracker_OLD.csproj`.

    iii. Finally, before reopening Visual Studio, open the `.sln` file with your favorite text editor. Locate the line referencing your project, and update it to the new path. It should look something like:

 ```sln
 Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "BugTracker_OLD", "BugTracker_OLD\BugTracker_OLD.csproj", "{92E4C60C-336D-4DFB-B08D-80489617C1F2}"
 ```

1. Open the solution. Right-click on the solution and choose 'Add > New Project'. Search for the 'Uno Platform App' template. Enter the desired name (eg `BugTracker` in our fictional example). Hit 'Create'. You should now have a project named `BugTracker`.

1. Delete `MainPage.xaml` from the new project - you will replace these with your existing files.

1. Replace `App.cs` contents with everything from your existing `App.xaml.cs` except the `InitializeComponent` call in the constructor.

1. Transfer all code files (C# and XAML) and assets from your old WinUI/UWP-only project to the new project.

*Note: you can safely delete 'head' projects for platforms that you're sure you don't want to target.*

## Adding dependencies

If your old WinUI/UWP app project had dependencies, you will have to add those dependencies to each new target platform project you wish to support. These include:

- .NET Standard projects within the solution: you should be able to add these as dependencies to any target platform project without difficulties.

- WinUI/UWP projects within the solution: these will have to be modified to be cross-platform class libraries - follow the instructions in [Migrating Libraries](migrating-libraries.md).

- external dependencies: [see information here](migrating-before-you-start.md) on finding equivalent dependencies for NuGet packages and framework libraries.

## Migrating app configuration

For WinUI/UWP, the `Package.appxmanifest` file can be copied directly from your old WinUI/UWP project to the new one in the `Platforms` folder. For other platforms, you will need to manually set the app name, capabilities, and other packaging information.

## Adjusting code for Uno compatibility

[See the next section](migrating-guidance.md) for adjustments to make to get your code compiling on Uno.

## What if my existing app targets WinUI 3?

The basic idea is the same, however, you'll use the [`dotnet new` templates](xref:Uno.GetStarted.dotnet-new) to create a WinUI 3-compatible Uno Platform app, into which you can transfer files and dependencies in a similar manner.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-before-you-start.md

---
uid: Uno.Development.MigratingBeforeYouStart
---

# Migrating WinUI/UWP-only code - Checklist

Before you start migrating a WinUI/UWP-only application or library to be Uno compatible, it's a good idea to assess the degree of effort involved in getting the port fully functional. Depending on the code in question, it may be as easy as copying the files, or it may involve significant extra effort.

The key questions to ask are:

- what framework APIs is the code using?
- what third-party dependencies does the code rely upon?
- what general .NET functionality is used that may not be supported on specific platforms?

## Controls and framework APIs

The controls supported by Uno and those currently unsupported are [listed here](implemented-views.md). You can see supported non-UI APIs under the 'Features and Controls' section of the docs. Note that API coverage varies by the target platform.

Once you migrate your code to Uno, unsupported API usages will be highlighted with a warning by Uno's included Roslyn analyzer.

## Third-party dependencies

Look at the NuGet packages referenced by the code. For each package, ask:

- is it supported on each platform you wish to target?
- if not, is there an acceptable alternative?

Third-party dependencies typically fall into one of a few categories:

### Platform-independent

Fully platform-independent dependencies will typically be packaged as .NET Standard binaries. They should be compatible with any target.

### Platform-dependent

These include dependencies that may be calling platform-specific functionality (eg push notifications), or that may depend on unmanaged binaries that must be separately compiled for each platform.

You can check if there is a version of the package for your target platform by visiting the package page on nuget.org and opening the 'Dependencies' expander. Typically you'll see `UAP 10.0.x` listed as a target. If you want to target Android and iOS with Uno, you should check that `MonoAndroid` and `Xamarin.iOS` are listed as supported targets. If you want to target macOS, check that `Xamarin.Mac` is listed.

Unfortunately, it's less easy to check if a platform-dependent package supports WebAssembly or Linux. Uno builds .NETStandard binaries for these targets, but the fact that a .NETStandard version exists for any given dependency doesn't guarantee that it will function as expected on those platforms, if platform-specific APIs are involved. You'll generally have to do some additional research.

### Depends on WinUI/UWP

Libraries that depend on WinUI/UWP itself, such as the [Windows Community Toolkit](https://learn.microsoft.com/windows/communitytoolkit/), must be recompiled against Uno Platform in order to be used. A number of popular WinUI/UWP libraries have already been retargeted to Uno; a partial list is given in the [Uno features section](https://github.com/unoplatform/Uno#uno-features).

## .NET runtime features

On certain target platforms, support for some .NET functionality is limited or unavailable.

### iOS

.NET code must be Ahead-Of-Time (AOT) compiled to run on iOS, as a fundamental platform limitation. As a result, certain APIs that require runtime code generation (eg `System.Reflection.Emit`) will not work. This includes code that uses the `dynamic` keyword. See the [Xamarin.iOS documentation](https://learn.microsoft.com/xamarin/ios/internals/limitations) for more details.

### WASM

Currently, WebAssembly code in the browser executes on a single thread (much like JavaScript code in the browser). This limitation is expected to be lifted in the future, but for now, code that expects additional threads to be available may not function as expected.

[This issue](https://github.com/unoplatform/uno/issues/2302) tracks support for multi-threading on WebAssembly in Uno Platform.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-from-net7-to-net8.md

---
uid: Uno.Development.MigratingFromNet7ToNet8
---
# How to upgrade from .NET 7 to .NET 8

Migrating from .NET 7 to .NET 8 is a generally straightforward process. You may find below some specific adjustments to make to your projects and libraries when upgrading.

To upgrade to .NET 8:

- First, read [What's New in .NET 8](https://learn.microsoft.com/dotnet/core/whats-new/dotnet-8)
- Install [Visual Studio 17.8](https://visualstudio.microsoft.com/vs/) or later and run [uno.check](xref:UnoCheck.UsingUnoCheck) to install .NET 8.
- Change all your target framework (TFM) references from `net7.0` to `net8.0`, and `net7.0-*` to `net8.0-*`. If you are using a TFM like net7.0-ios13.6, be sure to match the shipping version of that platform or just remove the platform version (i.e. 13.6).
- Delete your bin and obj folders

## Migrating Shared Class Libraries from net7.0 to net8.0

If you are building on windows and experience the compilation error NETSDK1083 when retargeting your library from net7.0 to net8.0, add the following to the `csproj`:

```xml
<PropertyGroup>
   <RuntimeIdentifiers>win-x86;win-x64;win-arm64</RuntimeIdentifiers>
</PropertyGroup>
```

You may also need to add to your `.Windows.csproj`:

```xml
<PropertyGroup>
   <SelfContained>true</SelfContained>
</PropertyGroup>
```

## Upgrading the IL Linker for WebAssembly

If you're using the [XAML Resource Trimming feature](xref:Uno.Features.ResourcesTrimming), you'll need to upgrade or add the following package to your `.Wasm.csproj`:

```xml
<ItemGroup>
   <PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0" />
</ItemGroup>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-from-net8-to-net9.md

---
uid: Uno.Development.MigratingFromNet8ToNet9
---
# How to upgrade from .NET 8 to .NET 9

Migrating from .NET 8 to .NET 9 is a generally straightforward process. You may find below some specific adjustments to make to your projects and libraries when upgrading.

To upgrade to .NET 9:

- First, read [What's New in .NET 9](https://learn.microsoft.com/dotnet/core/whats-new/dotnet-9/overview)
- Install/Update the IDE of your choice:  
  - [Visual Studio](https://visualstudio.microsoft.com/vs/) - minimal version **2022 17.13** or later  
  - [Visual Studio Code](https://code.visualstudio.com/) - minimal version **1.94** or later with the related [**C# Dev Kit**](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) stable version
  - [JetBrains Rider](https://www.jetbrains.com/rider/) - minimal version **2024.3** or later
- Run [uno.check](xref:UnoCheck.UsingUnoCheck) to install .NET 9.
- Change all your target framework (TFM) references from `net8.0` to `net9.0`, and `net8.0-*` to `net9.0-*`.
- Delete your bin and obj folders

## Considerations for WebAssembly

WebAssembly support for .NET 9 has made significant internal changes to use the official .NET SDK. Read the following [documentation for WebAssembly migrations](https://aka.platform.uno/wasm-net9-upgrade).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-from-net9-to-net10.md

---
uid: Uno.Development.MigratingFromNet9ToNet10
---

# How to Upgrade from .NET 9 to .NET 10

Migrating from .NET 9 to .NET 10 is a generally straightforward process. Below are some specific adjustments you may need to make to your projects and libraries when upgrading.

To upgrade to .NET 10:

- First, read [What's New in .NET 10](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-10/overview).
- Use **[.NET 10 RC1](https://devblogs.microsoft.com/dotnet/dotnet-10-rc-1/)** along with:
  - **Visual Studio** - the latest version of [Visual Studio 2026 Insiders](https://visualstudio.microsoft.com/insiders/), as recommended by Microsoft in their [announcement](https://devblogs.microsoft.com/dotnet/dotnet-10-rc-1/#🚀-get-started).
    Use version **18.0.0 [11104.47]** or later to ensure compatibility with the [latest stable Uno Platform extension](https://aka.platform.uno/vs-extension-marketplace).
  - **Visual Studio Code** - the latest version of [Visual Studio Code](https://code.visualstudio.com/Download) and the [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension, also recommended by Microsoft in the same [announcement](https://devblogs.microsoft.com/dotnet/dotnet-10-rc-1/#🚀-get-started).
  - **Rider** - the latest stable version, as .NET 10 support has been available since [Rider 2025.1](https://www.jetbrains.com/rider/whatsnew/2025-1/).
- Run the latest stable version of [uno.check](xref:UnoCheck.UsingUnoCheck) with the [`--pre-major` parameter](https://aka.platform.uno/uno-check-pre-major) to install .NET 10.
- Uno Platform provides an updated [Visual Studio extension](https://aka.platform.uno/vs-extension-marketplace) in the store that supports Visual Studio 2026 and the new `.slnx` solution format.
- Change all your target framework (TFM) references from `net9.0` to `net10.0`, and from `net9.0-*` to `net10.0-*`.
- Clean your project by deleting the `bin` and `obj` folders.

## Known Issues

For an up-to-date list of **known issues** when using **.NET 10** with Uno Platform, please refer to our [Health Status page](https://aka.platform.uno/health-status).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-from-previous-releases.md

---
uid: Uno.Development.MigratingFromPreviousReleases
---

# Migrating from Previous Releases of Uno Platform

To upgrade to the latest version of Uno Platform, [follow our guide](xref:Uno.Development.UpgradeUnoNuget).

## Uno Platform 6.5

Uno Platform 6.5 does not contain breaking changes that require attention when upgrading

> [!NOTE]
> Uno App MCP: if using Visual Studio 2022/2026, sometimes the Uno App MCP does not appear in the Visual Studio tools list. See [how to make the App MCP appear in Visual Studio](xref:Uno.UI.CommonIssues.AIAgents#the-app-mcp-does-not-appear-in-visual-studio).

## Uno Platform 6.4

Uno Platform 6.4 contains an Uno.Extensions breaking changes that require attention when upgrading:

- Uno.Extensions contains an OidcClient change in namespaces. See [the migration guide](xref:Uno.Extensions.Migration) for details.

### Visual Studio, Visual Studio Code, and Rider

When upgrading to Uno Platform 6.4, make sure to update your IDE extension or plugin to the latest stable version to ensure the Uno Platform development tooling connects properly.

- [Visual Studio extension](https://aka.platform.uno/vs-extension-marketplace)
- [Visual Studio Code extension](https://aka.platform.uno/vscode-extension-marketplace)
- [Rider plugin](https://aka.platform.uno/rider-extension-marketplace)

## Uno Platform 6.3

**Uno Platform 6.3** introduces support for **.NET 10 RC1** and removes **.NET 8** targets.

### Visual Studio, Visual Studio Code, and Rider

When upgrading to Uno Platform 6.3, make sure to update your IDE extension or plugin to the latest stable version to ensure the Uno Platform development tooling connects properly.

- [Visual Studio extension](https://aka.platform.uno/vs-extension-marketplace)
- [Visual Studio Code extension](https://aka.platform.uno/vscode-extension-marketplace)
- [Rider plugin](https://aka.platform.uno/rider-extension-marketplace)

### .NET 8 Support Removed

.NET 8 targets for apps are no longer supported by Uno Platform 6.3. However, NuGet library packages that are built with `net8.0 (and earlier) and Uno 6.0 (and later) continue to be compatible with Uno Platform apps built with .NET 9 and later.
While .NET 8 itself remains a Long-Term Support (LTS) release supported until [November 2026](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core), the **.NET MAUI 8** mobile workload reached end of support in [May 2025](https://dotnet.microsoft.com/en-us/platform/support/policy/maui).

You can [upgrade your project to .NET 9](xref:Uno.Development.MigratingFromNet8ToNet9) using our migration guide.

If you need to stay on .NET 8, you can continue to use **Uno Platform 6.2 or earlier** and plan your migration to .NET 9 or .NET 10 at a later time.

### .NET 10 RC1

**Uno Platform 6.3** is now built with **.NET 10** support, allowing you to upgrade existing projects or create new ones using the project wizard or CLI.

A few considerations to keep in mind:

- Moving to .NET 10 or upgrading existing projects requires using **.NET 10 RC1** along with:
  - **Visual Studio** — the latest version of [Visual Studio 2026 Insiders](https://visualstudio.microsoft.com/insiders/), as recommended by Microsoft in their [announcement](https://devblogs.microsoft.com/dotnet/dotnet-10-rc-1/#🚀-get-started).
    Use version **18.0.0 [11104.47]** or later to ensure compatibility with the [latest stable Uno Platform extension](https://aka.platform.uno/vs-extension-marketplace).
  - **Visual Studio Code** — the latest version of [Visual Studio Code](https://code.visualstudio.com/Download) and the [C# Dev Kit](https://marketplace.visualstudio.com/items?itemName=ms-dotnettools.csdevkit) extension, as also recommended by Microsoft in the same [announcement](https://devblogs.microsoft.com/dotnet/dotnet-10-rc-1/#🚀-get-started).
  - **Rider** — the latest stable version, as .NET 10 support has been available since [Rider 2025.1](https://www.jetbrains.com/rider/whatsnew/2025-1/).

- Uno Platform provides an updated [Visual Studio extension](https://aka.platform.uno/vs-extension-marketplace) that supports **Visual Studio 2026** and the new `.slnx` solution format.
- To migrate your project to .NET 10, see our [migration guide](xref:Uno.Development.MigratingFromNet9ToNet10).

For an up-to-date list of **known issues** when using **.NET 10** with Uno Platform, please refer to our [Health Status page](https://aka.platform.uno/health-status).

### API Changes for Android

Starting with Uno Platform **6.3**, the following methods now throw `NotSupportedException` under **.NET 10** or later:

- `Microsoft.UI.Xaml.ApplicationActivity.GetTypeAssemblyFullName(string)` (Android + Native renderer)
- `Microsoft.UI.Xaml.ApplicationActivity.GetTypeAssemblyFullName(string)` (Android + Skia renderer)
- `Microsoft.UI.Xaml.NativeApplication.GetTypeAssemblyFullName(string)`

This change was introduced in [PR #21199](https://github.com/unoplatform/uno/pull/21199) ([commit 4d84ee3](https://github.com/unoplatform/uno/commit/4d84ee31adb3e7ecd3fcbdc248b79fee78211d3e)).
Methods with the [`[Java.Interop.ExportAttribute]` custom attribute](https://learn.microsoft.com/dotnet/api/java.interop.exportattribute?view=net-android-34.0) are not supported within certain runtime environments.

If your application calls any of the affected methods:

- Remove any direct usage of `GetTypeAssemblyFullName`.
- Consider removing methods with the `[Export]` custom attribute, as they may not work in certain runtime environments. Consider using managed interop or dependency injection alternatives instead.
- If you relied on these APIs for reflection or interop, migrate that logic to managed code executed at runtime.
- Rebuild and test your Android and Android+Skia apps with .NET 10 or later to ensure compatibility.

These changes prevent runtime exceptions and improve compatibility for builds on Android.

## Uno Platform 6.2

Uno Platform 6.2 does not contain breaking changes that require attention when upgrading.

## Uno Platform 6.1

Uno Platform 6.1 does not contain breaking changes that require attention when upgrading.

## Uno Platform 6.0

Uno Platform 6.0 contains breaking changes required to provide a consistent experience when using the Skia rendering feature, as well as the removal of the UWP API set support and the GTK desktop runtime support.

Read additional information about the [migration to Uno Platform 6.0](xref:Uno.Development.MigratingToUno6).

## Uno Platform 5.6

Uno Platform 5.6 contains one breaking change around using `x:Load` to align the behavior to WinUI.

### Lazy loading

To align the behavior with WinUI, lazy loading using `x:Load="False"` and `x:DeferLoadStrategy="lazy"` is no longer affected by changes to the visibility of the lazily-loaded element. Previously, binding the `Visibility` property of the lazily-loaded element and then updating the binding source to make the element visible would cause the element to materialize (i.e. load). This is no longer the case. To load the element, add an `x:Name` to the element and call `FindName` with the given name.

## Uno Platform 5.5

Uno Platform 5.5 introduces support for .NET 9 RC2 and requires installation updates for WebAssembly.

### .NET 9 RC2

A few considerations to take into account:

- Moving to .NET 9 or upgrading .NET 9 projects now require the use of .NET 9 RC2 and Visual Studio 17.12 Preview 3.
- To migrate a project to .NET 9, [read the directions](xref:Uno.Development.MigratingFromNet8ToNet9) from our documentation.

### The EnableHotReload method is deprecated

When upgrading to Uno 5.5, in the `App.xaml.cs` file, the `EnableHotReload()` method is deprecated and must be replaced with `UseStudio()` instead.

## Uno Platform 5.4

Uno Platform 5.4 contains breaking changes for Uno.Extensions.

### WinAppSDK 1.6 considerations

Uno Platform 5.4 updates to WinAppSDK 1.6 if you are using the [`Uno.SDK`](xref:Uno.Features.Uno.Sdk), which requires a temporary version adjustment until newer versions of the .NET 8 SDKs are released.

In your project, you may need to add the following lines (or uncomment them if you kept them from our templates) to get the `net8.0-windowsXX` target to build:

```xml
<PropertyGroup>
    <!-- Remove when the .NET SDK 8.0.403 or later has been released -->
    <WindowsSdkPackageVersion>10.0.19041.38</WindowsSdkPackageVersion>
</PropertyGroup>
```

Additionally, you may also get the following error message:

```text
NETSDK1198: A publish profile with the name 'win-AnyCPU.pubxml' was not found in the project.
```

This issue is not yet fixed, but it does not cause any problems during deployment.

### UWP Support for Uno.Extensions

The [`Uno.Extensions`](https://aka.platform.uno/uno-extensions) compatibility with legacy UWP apps has been removed. If your app is UWP-based and uses Uno.Extensions, in order to migrate to Uno Platform 5.4, you can keep using [previous releases of Uno.Extensions](https://github.com/unoplatform/uno.extensions/releases), or [migrate your app to WinUI](https://platform.uno/docs/articles/updating-to-winui3.html).

All the other features of Uno Platform 5.4 continue to be compatible with both UWP and WinUI apps.

### Updates in Uno.Extensions.Reactive

The generated code has changed. Make sure to [review our docs to upgrade](xref:Uno.Extensions.Reactive.Upgrading) to Uno Platform 5.4.

## Uno Platform 5.3

Uno Platform 5.3 contains an improved template and Uno.SDK versioning, new default text font, and Rider support.

The support for .NET 7 has been removed, since it was a Standard Term Support (STS) release which [ended in May 2024](https://dotnet.microsoft.com/en-us/platform/support/policy/dotnet-core). You can [upgrade your project to .NET 8](xref:Uno.Development.MigratingFromNet7ToNet8) using our guide.

Make sure to [re-run Uno.Check](xref:UnoCheck.UsingUnoCheck) to get all the latest dependencies.

### Visual Studio

Update your [Uno Platform extension](https://aka.platform.uno/vs-extension-marketplace) in VS 2022 to 5.3.x or later. Earlier versions may automatically update to an incorrect version of the Uno.SDK.

### Single Project updates

Similar to version 5.2, using the new project template is entirely optional and previous project structures are fully supported.

If you want to migrate to the new Single Project, you can follow the [Migrating to Single Project](xref:Uno.Development.MigratingToSingleProject) guide.

If you are upgrading from an Uno Platform 5.2 project, you can remove the following section from your `Directory.Build.props`:

```xml
  <!-- See https://aka.platform.uno/using-uno-sdk#implicit-packages for more information regarding the Implicit Packages version properties. -->
  <PropertyGroup>
    <UnoExtensionsVersion>...</UnoExtensionsVersion>
    <UnoToolkitVersion>...</UnoToolkitVersion>
    <UnoThemesVersion>...</UnoThemesVersion>
    <UnoCSharpMarkupVersion>...</UnoCSharpMarkupVersion>
  </PropertyGroup>
```

### Default Text Font

Starting from Uno Platform 5.3, the [default text font](xref:Uno.Features.CustomFonts#default-text-font) has been changed to [Open Sans](https://github.com/unoplatform/uno.fonts#open-sans-font) in the templates. This is because Uno.Sdk sets `UnoDefaultFont` MSBuild property to `OpenSans` when it's not set to something else. For more information, see [Custom fonts](xref:Uno.Features.CustomFonts).

### Rider support

The new [Uno Platform Rider plugin](https://aka.platform.uno/rider-support) support provides C# and XAML Hot Reload support, and to benefit from this new support, new projects created with Uno Platform 5.3 templates contain a new `.run` folder which provides proper support.

If your project was created using an Uno Platform 5.2 or earlier template, you can create a new temporary template with the same name as your current project (e.g. `dotnet new unoapp -o MyExistingProject`), then copy over the `.run` folder in your project.

## Uno Platform 5.2

Uno Platform 5.2 contains a new project template that supports all target frameworks into a single project, based on the Uno.Sdk that was introduced in Uno Platform 5.1.

Using this new project template is entirely optional and previous project structures are fully supported.

If you want to migrate to the new Single Project, you can follow the [Migrating to 5.2 Single Project](xref:Uno.Development.MigratingToSingleProject) guide.

## Uno Platform 5.1

Uno Platform 5.1 does not contain breaking changes that require attention when upgrading.

This version however introduces the MSBuild Uno.SDK, which provides support for smaller project files and better Visual Studio integration. Using the Uno.Sdk is entirely optional and previous project templates are fully supported. If you want to migrate to Uno.Sdk based projects, you can follow the [Migrating Projects to Single Project](xref:Uno.Development.MigratingToSingleProject) guide.

## Uno Platform 5.0

Uno Platform 5.0 contains binary-breaking changes in order to further align our API surface with the Windows App SDK. Most of these changes are binary-breaking changes but do not introduce behavior changes.

Additionally, this version:

- Adds support for .NET 8 for iOS, Android, Mac Catalyst, and macOS. [Follow this guide](xref:Uno.Development.MigratingFromNet7ToNet8) to upgrade from .NET 7 to .NET 8.
- Removes the support for Xamarin.iOS, Xamarin.Android, Xamarin.Mac, and netstandard2.0 for WebAssembly.
- .NET 7.0 support for iOS, Android, Mac Catalyst, and macOS remains unchanged.
- Updates the base Windows SDK version from 18362 to 19041.

Uno Platform 5.0 continues to support both UWP and WinUI API sets.

Read about additional information about the [migration to Uno Platform 5.0](xref:Uno.Development.MigratingToUno5).

## Uno Platform 4.10

This release does not require upgrade steps.

## Uno Platform 4.9

This release does not require upgrade steps.

## Uno Platform 4.8

This release does not require upgrade steps.

## Uno Platform 4.7

### Symbol Fonts

Uno Platform 4.7 now brings the Uno Fluent Symbols font implicitly. You can remove:

- The `uno-fluentui-assets.ttf` file from all your project heads,
- Any reference to `uno-fluentui-assets.ttf` in the `UIAppFonts` sections of the iOS `Info.plist`

### Breaking change with ms-appx:/// resolution

Uno Platform 4.7 brings a behavior-breaking change where the library Assets feature introduced in Uno Platform 4.6 required assembly names to be lowercase.

If you had an asset in a nuget package or project named "MyProject", you previously had to write `ms-appx:///myproject/MyAsset.txt`. With 4.7, you'll need to write `ms-appx:///MyProject/MyAsset.txt`.

## Uno Platform 4.6

### Breaking change with Android 13

The introduction of Android 13 led to a breaking change, as some Android members exposed to .NET were removed.

You'll need to migrate from `BaseActivity.PrepareOptionsPanel` to `BaseActivity.PreparePanel` instead.

## Uno Platform 4.5

### ElevatedView

The built-in `ElevatedView` control has undergone a visual unification, which means existing apps may experience slightly different shadow visuals, especially on Android, which now supports the full range of colors, including opacity. If you encounter visual discrepancies, please tweak the `Elevation` and `ShadowColor` properties to fit your needs.

## Uno Platform 4.1

### Android 12 support

Uno 4.1 removes the support for the Android SDK 10 and adds support for Android 12. Note that Android 10  versions and below are still supported at runtime, but you'll need Android 11 SDK or later to build an Uno Platform App. You can upgrade to Android 11 or 12 using the `Compile using Android version: (Target Framework)` option in Visual Studio Android project properties.

Additionally, here are some specific hints about the migration to Android 12:

- If you are building with Android 12 on Azure Devops Hosted Agents (macOS or Windows), you'll need two updates:
  - Use the JDK 11, using the following step:

    ```yml
    - pwsh: |
        echo "##vso[task.setvariable variable=JAVA_HOME]$(JAVA_HOME_11_X64)"
        echo "##vso[task.setvariable variable=JavaSdkDirectory]$(JAVA_HOME_11_X64)"
    displayName: Select JDK 11
    ```

  - You may need to add the following property to your Android csproj:

    ```xml
    <PropertyGroup>
        <AndroidUseLatestPlatformSdk>true</AndroidUseLatestPlatformSdk>
    </PropertyGroup>
    ```

- The AndroidX libraries need to be at specific versions to avoid [an upstream android issue](https://learn.microsoft.com/answers/questions/650236/error-androidattrlstar-not-found-after-upgrading-n.html). The Uno Platform NuGet packages are using those versions automatically, but if you override those packages, make sure to avoid direct or indirect dependencies on `Xamarin.AndroidX.Core(>=1.7.0.1)`. For reference, [view this page](https://github.com/unoplatform/uno/blob/533c5316cbe7537bb2f4a542b46a52b96c75004a/build/Uno.WinUI.nuspec#L66-L69) to get the package versions used by Uno Platform.

## Uno Platform 4.0

Uno 4.0 introduces a set of binary and source-breaking changes required to align with the Windows App SDK 1.0.

To migrate your application to Uno 4.0:

- Update all `Uno.UI.*` nuget packages to 4.0
- Add a package reference to `Uno.UI.Adapter.Microsoft.Extensions.Logging` to all your project heads (Except `.Desktop` for WinUI projects and `.Windows` for UWP projects)
- In your `ConfigureLogging` method, add the following block at the end:

  ```csharp
  #if HAS_UNO
  global::Uno.UI.Adapter.Microsoft.Extensions.Logging.LoggingAdapter.Initialize();
  #endif
  ```

- If you are using `ApiInformation.NotImplementedLogLevel`, use the following code instead:

  ```csharp
  global::Uno.UI.FeatureConfiguration.ApiInformation.NotImplementedLogLevel = global::Uno.Foundation.Logging.LogLevel.Debug; // Raise not implemented usages as Debug messages
  ```

- Many other smaller breaking changes that may have previously forced `#if HAS_UNO` conditionals, such as:
  - `FrameworkElement.DataContextChanged` signature
  - `FrameworkElement.Loading` signature
  - `Popup` is now correctly in the `Primitives` namespace
  - `FlyoutBase` event signatures
- Uno.UI packages no longer depend on `Uno.Core`.
  If you did depend on types or extensions provided by this package, you can take a direct dependency on it or
  use one of the sub-packages created to limit the number of transitive dependencies.
- The `Uno.UI.DualScreen` package is now renamed as`Uno.UI.Foldable`

## Uno Platform 3.6

### Optional upgrade for Microsoft.Extension.Logging

Uno Platform 3.6 templates provide an updated version of the loggers to allow the use of updated `Microsoft.Extension.Logging.*` logging packages. It is not required for applications to upgrade to these newer loggers, yet those provide additional features, particularly for iOS and WebAssembly.

Here's how to upgrade:

- For all projects:
  - Remove references to the `Microsoft.Extensions.Logging.Filter` package
  - Add a reference to the `Microsoft.Extensions.Logging` package version **5.0.0**
  - Upgrade the `Microsoft.Extensions.Logging.Console` package to version **5.0.0**
- For UWP:
  - Change the reference from `Microsoft.Extensions.Logging.Console` to `Microsoft.Extensions.Logging.Debug`
- For WebAssembly:
  - Add the following line to the `LinkerConfig.xaml` file:

    ```xml
    <assembly fullname="Microsoft.Extensions.Options" />
    ```

  - Add a reference to `Uno.Extensions.Logging.WebAssembly.Console` version **1.0.1**
- For iOS:
  - Add a reference to `Uno.Extensions.Logging.OSLog` version **1.0.1**
- In the `App.xaml.cs` file:
  - Replace the `ConfigureFilters()` method with the following:

    ```csharp
                /// <summary>
                /// Configures global Uno Platform logging
                /// </summary>
                private static void InitializeLogging()
                {
                    var factory = LoggerFactory.Create(builder =>
                    {
        #if __WASM__
                        builder.AddProvider(new global::Uno.Extensions.Logging.WebAssembly.WebAssemblyConsoleLoggerProvider());
        #elif __IOS__ || __TVOS__
                        builder.AddProvider(new global::Uno.Extensions.Logging.OSLogLoggerProvider());
        #elif NETFX_CORE
                        builder.AddDebug();
        #else
                        builder.AddConsole();
        #endif

                        // Exclude logs below this level
                        builder.SetMinimumLevel(LogLevel.Information);

                        // Default filters for Uno Platform namespaces
                        builder.AddFilter("Uno", LogLevel.Warning);
                        builder.AddFilter("Windows", LogLevel.Warning);
                        builder.AddFilter("Microsoft", LogLevel.Warning);

                        // Generic Xaml events
                        // builder.AddFilter("Windows.UI.Xaml", LogLevel.Debug );
                        // builder.AddFilter("Windows.UI.Xaml.VisualStateGroup", LogLevel.Debug );
                        // builder.AddFilter("Windows.UI.Xaml.StateTriggerBase", LogLevel.Debug );
                        // builder.AddFilter("Windows.UI.Xaml.UIElement", LogLevel.Debug );
                        // builder.AddFilter("Windows.UI.Xaml.FrameworkElement", LogLevel.Trace );

                        // Layouter specific messages
                        // builder.AddFilter("Windows.UI.Xaml.Controls", LogLevel.Debug );
                        // builder.AddFilter("Windows.UI.Xaml.Controls.Layouter", LogLevel.Debug );
                        // builder.AddFilter("Windows.UI.Xaml.Controls.Panel", LogLevel.Debug );

                        // builder.AddFilter("Windows.Storage", LogLevel.Debug );

                        // Binding related messages
                        // builder.AddFilter("Windows.UI.Xaml.Data", LogLevel.Debug );
                        // builder.AddFilter("Windows.UI.Xaml.Data", LogLevel.Debug );

                        // Binder memory references tracking
                        // builder.AddFilter("Uno.UI.DataBinding.BinderReferenceHolder", LogLevel.Debug );

                        // RemoteControl and HotReload related
                        // builder.AddFilter("Uno.UI.RemoteControl", LogLevel.Information);

                        // Debug JS interop
                        // builder.AddFilter("Uno.Foundation.WebAssemblyRuntime", LogLevel.Debug );
                    });

                    global::Uno.Extensions.LogExtensionPoint.AmbientLoggerFactory = factory;
                }
    ```

  - In the constructor, remove this call:

    ```csharp
    ConfigureFilters(global::Uno.Extensions.LogExtensionPoint.AmbientLoggerFactory);
    ```

    and replace it with:

    ```csharp
    InitializeLogging();
    ```

Note that there are two new loggers:

- `Uno.Extensions.Logging.OSLog` which provides the ability to log the iOS system logs
- `Uno.Extensions.Logging.WebAssembly.Console` which provides thread-safe and colored logging to the browser debugger console

#### Migrating WebAssembly projects to .NET 5

If your WebAssembly project is using the `netstandard2.0` TargetFramework, migrating to `net5.0` can be done as follows:

- Change `<TargetFramework>netstandard2.0</TargetFramework>` to `<TargetFramework>net5.0</TargetFramework>`
- Upgrade `Uno.Wasm.Bootstrap` and `Uno.Wasm.Bootstrap.DevServer` to `2.0.0` or later
- Add a reference to the `Microsoft.Windows.Compatibility` package to `5.0.1`

You may also want to apply the changes from the section above (logger updates) to benefit from the update to .NET 5.

### Uno Platform 2.x to Uno 3.0

Migrating from Uno 2.x to Uno 3.0 requires a small set of changes in the code and configuration.

- **Android 8.0** is not supported anymore. You'll need to update to **Android 9.0** or **10.0**.
- For Android, you'll need to update the `Main.cs` file from:

  ```csharp
  : base(new App(), javaReference, transfer)
  ```

    to

  ```csharp
  : base(() => new App(), javaReference, transfer)
  ```

- For WebAssembly, in the `YourProject.Wasm.csproj`:
  - Change `<PackageReference Include="Uno.UI" Version="2.4.4" />` to `<PackageReference Include="Uno.UI.WebAssembly" Version="3.0.12" />`
  - Remove `<WasmHead>true</WasmHead>`
  - You can remove `__WASM__` in `DefineConstants`
- The symbols font has been updated, and the name needs to be updated. For more information, see [this article](uno-fluent-assets.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-from-xamarin-to-net6.md

---
uid: Uno.Development.MigratingFromXamarinToNet6
---
# How to upgrade from Xamarin to .NET 7

There are two ways to migrate an application to .NET 7.

## The forward looking path using the WinUI/WinApp SDK APIs

   1. In a separate folder, create a new application from the templates using [`dotnet new unoapp -o MyApp`](xref:Uno.GetStarted.dotnet-new) (MyApp being of the same name as your existing app), or by using the Visual Studio `Uno Platform App` template
   2. Move the `MyApp.Mobile` project folder and include it in your existing solution
   3. Make the adjustments to move from the [UWP APIs to the WinUI APIs](xref:Uno.Development.UpdatingToWinUI3)
   4. Optionally [convert your legacy Xamarin heads](xref:Uno.Development.UpdatingToWinUI3) to use Uno.WinUI instead of Uno.UI

## Additional considerations

Since .NET 7 breaks binary compatibility with Xamarin, most of the existing nuget packages that target `monoandroidXX`, `xamarinios10` and `xamarinmac20` (bindings to native SDKs are a good example) will not work properly and will need an updated version that are compatible with `net7.0-ios`, `net7.0-android`, and `net7.0-maccatalyst`.

## Xamarin Support Policy

As defined by [Microsoft support policy](https://dotnet.microsoft.com/platform/support/policy/xamarin) for Xamarin (as of 2022-08-25):

> _Xamarin support will end on May 1, 2024 for all Xamarin SDKs. Android 13 and Xcode 14 SDKs (iOS and iPadOS 16, macOS 13) will be the final versions Xamarin will target._

Uno Platform is going provides support for Xamarin (`monoandroid12`, `monoandroid13`, `xamarinios10` and `xamarinmac20`) by that date as well in the Uno 4.x releases. Uno 5.0 and later does not support Xamarin anymore. Note that later on, apps built with these SDK will not be accepted by both [Apple](https://developer.apple.com/support/xcode/) and [Google](https://developer.android.com/google/play/requirements/target-sdk) stores.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-guidance.md

---
uid: Uno.Development.MigratingGuidance
---

# General guidance for making WinUI/UWP-only code Uno compatible

This article explains adjustments that may need to be made to WinUI/UWP-only code for it to run on Uno Platform, be it in an application or a class library.

## Code adjustments

### Add 'partial' to some class definitions

Certain class definitions will need to have the [`partial` keyword](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/partial-type) added. This is because Uno [generates additional code at compile-time](./uno-development/uno-internals-overview.md#dependencyobject-implementation-generator) to support them properly.

You'll need to do this for:

- types that inherit from `FrameworkElement`, directly or indirectly
- types that inherit directly from `DependencyObject`

Apart from adding `partial`, you don't need to worry about the generated code. You may however get misleading errors from Intellisense until the first time you try to compile the project, because the generated partial classes haven't been added yet.

### Avoid nested classes that inherit from FrameworkElement

Classes that inherit from `FrameworkElement` directly or indirectly can't be nested inside another class; it's been observed to cause problems on Xamarin.iOS. If you have any nested `FrameworkElement`-derived classes, you'll need to refactor them to be top-level classes.

### Disambiguate naming collisions with native properties

This is relevant if you're targeting Android, iOS, and/or macOS, where Uno views (hence, `FrameworkElement`) [inherit from the native view type](native-views.md). In some cases you may find that a reference to a type from the UWP framework is confused with a native property. The fix in this case is generally to disambiguate by supplying the full namespace of the type.

Some common cases:

- on iOS, inside a control definition, references to [`Window.Current`](https://learn.microsoft.com/uwp/api/windows.ui.xaml.window.current) will be confused with the [`UIView.Window`](https://learn.microsoft.com/dotnet/api/uikit.uiview.window) property. The fix is to fully qualify this as `Windows.UI.Xaml.Current`.
- on Android, inside a control definition, references to the [`TextAlignment` enum](https://learn.microsoft.com/uwp/api/windows.ui.xaml.textalignment) will be confused with the [`View.TextAlignment` property](https://learn.microsoft.com/dotnet/api/android.views.view.textalignment). The fix, again, is to fully qualify the reference as `Windows.UI.Xaml.TextAlignment`.

#### What do I do if I have a nested namespace with `Windows` in it?

If, for example, your control is defined in the `CoolControls` namespace, and you've also defined a `CoolControls.Windows` namespace, then the above will give a compilation error. You'll need to use the [`global` keyword](https://learn.microsoft.com/dotnet/csharp/language-reference/operators/namespace-alias-qualifier), eg `global::Windows.UI.Xaml.Window.Current`.

## Adjust for unsupported runtime features

Not all .NET runtime features are supported on every platform. See [Migrating - Before You Start](migrating-before-you-start.md) for more details.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-libraries.md

---
uid: Uno.Development.MigratingLibraries
---

# Migrating a WinUI or UWP class library to an Uno Platform class library

This article describes how to port a class library for UWP to one that supports multiple target platforms using Uno.

It assumes you're using Visual Studio for Windows, but the steps are similar if you're using VS Code or another IDE.

## Prerequisites

Follow the instructions to [set up your development environment for Uno Platform](get-started.md).

## Applying Uno Platform project structure

Adding Uno Platform support to an existing class library entails changing the contents of the existing `.csproj` file. The easiest way to do that is to create a temporary Uno class library and copy its contents into the existing `.csproj` file. The steps in detail:

1. Open the solution containing the WinUI/UWP-only library you wish to convert.

2. Create an **Uno Platform Library** project in the same solution, and name it `TempUno`.

3. Let's say we want to convert a library called 'CoolControls'. Right-click on the `CoolControls` project, and choose **Unload Project**.

4. Right-click again on `CoolControls`, and choose **Edit CoolControls.csproj**.

5. Right-click on `TempUno`, then **Edit TempUno.csproj**. _(There is no need to unload this type of project)_

6. Make a temporary copy of the contents of `CoolControls.csproj` (eg in a Notepad window) - you will refer to this when restoring dependencies.

7. Copy the entire contents of `TempUno.csproj` and paste them into `CoolControls.csproj`, overwriting the old contents.

8. Delete the `TempUno` project from your solution.

9. Right-click on `CoolControls`, then choose **Reload Project**.

10. In the **Properties** folder of `CoolControls`, you'll need to remove the `AssemblyVersion` and similar properties as those are now generated by [msbuild using AssemblyInfo properties](https://learn.microsoft.com/dotnet/core/tools/csproj#assemblyinfo-properties).

## Adding dependencies

If your class library had additional dependencies, you will need to restore them. See [Migrating - Before You Start](migrating-before-you-start.md) for tips on finding compatible dependency versions for each target. See the [working with Control libraries article](xref:Guide.HowTo.Create-Control-Library) for how to add dependencies to your project.

## Adjusting code for Uno compatibility

[See the next section](migrating-guidance.md) for adjustments you may need to make to get your code compiling on Uno.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-to-single-project.md

---
uid: Uno.Development.MigratingToSingleProject
---
# Migrating Projects to Single Project

The Uno Platform 5.2 and later use the [Uno.Sdk](https://www.nuget.org/packages/uno.sdk) which provides a single Uno Project structure and a single location for updating the Uno Platform core packages version in `global.json`.

> [!IMPORTANT]
> Migrating to the Uno.Sdk and Single Project are not required. Existing projects, 5.1 and earlier, continue to be supported in Uno Platform 5.2 or later.

With Uno Platform Single Project, you can optimize your project structure and simplify maintenance while leveraging the power of Uno Platform for cross-platform app development. This guide provides step-by-step instructions and practical tips to ensure a smooth migration process. Let's get started!

## What is the Uno.Sdk

The Uno.Sdk is used to abstract the complexity needed to build cross-platform projects, while still ensuring that you have the ability to customize the configuration to your needs.

This means that values such as the `SupportedOSPlatformVersion`, which have been in the template's `Directory.Build.props` in previous Uno Platform templates, now have a default value set to the minimum supported by Uno Platform.

If you need to be more restrictive for your specific project you can provide your overrides for the platform(s) that you need.

## Project Structure

In the Uno Platform Single Project, all platform-specific code is put together in one project. Instead of having separate projects for each platform, everything is organized within a `Platforms` folder. This folder contains sub-folders for each platform your project targets, like Android, iOS, Skia, WebAssembly, and Windows. Each platform folder stores the code and resources needed for that platform, making development easier to manage for multi-platform projects.

## Upgrading an existing project to Single Project

The following sections detail how to upgrade an existing project to use a single project with the Uno.Sdk. Those modifications are made in place and **it is strongly recommended to work on a source-controlled environment**.

While following this guide, you can compare with a new empty project created using [our Wizard](xref:Uno.GetStarted.Wizard), or using [dotnet new templates](xref:Uno.GetStarted.dotnet-new).

### Migrating to a Single Project

Migrating from a 5.1 or earlier template is a matter of merging all the csproj files for all the platforms heads down to one csproj file.

We'll take the example of an Uno Platform 5.0 blank app, called `MyApp`, to migrate to Single Project :

1. In a separate folder from your existing app, create a new app using the same name as your app:

   ```bash
   dotnet new unoapp -o MyApp --preset=recommended
   ```

   This will allow for taking pieces of the structure with the proper namespaces. If your app was created using the blank template, use `--preset=blank` instead. You can also use the [Live Wizard](xref:Uno.GetStarted.dotnet-new) or the [Visual Studio Wizard](xref:Uno.GettingStarted.CreateAnApp.VS2022) and select the same optional features you used for your app.
1. Next to the solution, create a `global.json` file

    ```json
    {
        "msbuild-sdks": {
            "Uno.Sdk": "{Current Version of Uno.WinUI/Uno.Sdk}"
        }
    }
    ```

1. From the empty app created at step one:
    - Take the contents of the `MyApp.csproj` and copy it over your own `MyApp.csproj`
    - Take the folder named `Properties` and copy it over your own `MyApp`
1. If you have your own `PackageReference` and `ProjectReference`, make sure to preserve them.
1. From the empty app created at step one, take the `Platforms` folder and copy it over your own `MyApp` folder.
1. In you app's `MyApp.csproj`, create the following block:

   ```xml
   <Choose>
     <When Condition="'$(TargetFramework)'=='net9.0-ios'">
     </When>
     <When Condition="'$(TargetFramework)'=='net9.0-android'">
     </When>
     <When Condition="'$(TargetFramework)'=='net9.0-windows10.0.19041'">
     </When>
     <When Condition="'$(TargetFramework)'=='net9.0-desktop'">
     </When>
     <When Condition="'$(TargetFramework)'=='net9.0-browserwasm'">
     </When>
   </Choose>
   ```

   This will allow us to place custom project configurations in each of those sections. Use the ones that are relevant to your project targets.
1. From the empty app created at step one, take the `App.xaml` and `App.xaml.cs` and copy those over your own `MyApp` folder.
1. Copy the individual modifications you made to your `AppResources.xaml` and `App.cs` into `App.xaml` and `App.xaml.cs`, respectively. Those can, for instance, be changes made to `OnLaunched`, `InitializeLogging`, or `RegisterRoutes`.
1. For the WebAssembly project, most of the configuration is now included by the `Uno.Sdk`. You can:
    1. Move all the files from your `MyApp.Wasm`  folder to the `Platforms/WebAssembly` folder, except `MyApp.Wasm.csproj` and the `Properties` folder.
    1. Copy the individual configurations, `ProjectReference` and `PackageReference` entries from your `MyApp.Wasm.csproj` to your `MyApp.csproj`, into the appropriate `When` condition block we created above. This can include properties like `WasmShellGenerateAOTProfile` or `WasmShellMonoRuntimeExecutionMode`, depending on your choices.
    1. Delete the `MyApp.Wasm` folder
1. For the Mobile project, you can:
    1. In your app, move the folders `MyApp.Mobile/Android`, `MyApp.Mobile/iOS` to the `MyApp/Platforms`.
    1. Copy the individual configurations, `ProjectReference` and `PackageReference` entries from your `MyApp.Mobile.csproj` to your `MyApp.csproj`, into the appropriate `When` condition block we created above. This can include properties like `ApplicationTitle` or `ApplicationId`, depending on your choices.
    1. Delete the `MyApp.Mobile` folder
1. For the Skia.Gtk, Skia.Wpf and Skia.Framebuffer projects, you can:
    1. Copy individual modifications made to the `Program.cs` of each platform over to `Platforms/Desktop/Program.cs`
    1. Copy the individual configurations, `ProjectReference` and `PackageReference` entries from your `MyApp.Skia.[Gtk|Wpf|Framebuffer].csproj` to your `MyApp.csproj`, into the appropriate `When` condition block we created above.
    1. You can also copy the individual modifications made to `app.manifest` and `Package.manifest` to `MyApp`. Those two files are now shared across platforms.
    1. Delete the `MyApp.Skia.[Gtk|Wpf|Framebuffer]` folders
1. For the `MyApp.Windows` project, you can:
    1. Copy the individual configurations, `ProjectReference` and `PackageReference` entries from your `MyApp.Windows.csproj` to your `MyApp.csproj`, into the appropriate `When` condition block we created above.
    1. You can copy the individual modifications made to `app.manifest` and `Package.manifest` to `MyApp`. Those two files are now shared across platforms.
1. For the `MyApp.[Shared|Base]` project, you can:
    1. Move the `Icons` and `Splash` folders to the `MyApp/Assets`
    1. If you've made modifications to the `base.props` file, you can copy those over to the `MyApp.csproj`, outside the `Choose` section.
    1. If you've made individual changes to the `AppHead.xaml` file, copy those over to the `App.xaml` file
    1. If you've made individual changes to the `AppHead.xaml.cs` file, copy those over to the `App.xaml.cs` file
    1. Delete the `MyApp.[Shared|Base]` folder
1. In All the `.cs` files, replace `AppHead` with `App`
1. Once done, you can remove the `Platforms` folder from your solution explorer, as all other platform heads have been deleted.
1. If you have a `MyApp.Server` project, make sure to change from:

    ```xml
    <ProjectReference Include="..\MyApp.Wasm\MyApp.Wasm.csproj" />
    ```

    to

    ```xml
    <ProjectReference 
        Include="..\MyApp\MyApp.csproj"
        SetTargetFramework="TargetFramework=net9.0-browserwasm"
        ReferenceOutputAssembly="false" />
    ```

1. From the empty app created at step one, take the `Directory.Build.props` and `Directory.Build.targets` files and copy those over your own root folder. Make sure to copy individual changes made in your file, such as `CSharpVersion` or `Nullable`.
1. From the empty app created at step one, take the `Directory.Packages.props`file and copy it over to your own root folder. All of the NuGet packages can be removed from this file, as the Uno.SDK provides those automatically.
1. In all the projects files, replace `$(DotnetVersion)` with `net9.0`
1. Remove the `solution-config.props.sample` file. This part is now handled by Uno Platform automatically.

At this point, your solution can be compiled using a single project and Uno Platform 5.2. For a guide through using the new single project, head over to [our getting started](xref:Uno.GetStarted).

## Wrapping up

Now that your project has gotten simplified, you can head over to our [Uno.Sdk](xref:Uno.Features.Uno.Sdk) documentation to explore its features.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-to-uno-5.md

---
uid: Uno.Development.MigratingToUno5
---
# Migrating to Uno Platform 5.0

Uno Platform 5.0 contains binary-breaking changes in order to further align our API surface with the Windows App SDK. Most of these changes are binary-breaking changes but do not introduce behavior changes. You can find a list of these changes below.

Additionally, this version:

- Adds support for .NET 8 for iOS, Android, Mac Catalyst, and macOS. [Follow this guide](xref:Uno.Development.MigratingFromNet7ToNet8) to upgrade from .NET 7 to .NET 8.
- Removes the support for Xamarin.iOS, Xamarin.Android, Xamarin.Mac, .NET 6 (iOS/Android/Catalyst), and netstandard2.0 for WebAssembly.
- .NET 7.0 support for iOS, Android, Mac Catalyst, and macOS remains unchanged.
- Updates the base Windows SDK version from 18362 to 19041.

Uno Platform 5.0 continues to support both UWP ([Uno.UI](https://www.nuget.org/packages/uno.ui) and WinUI ([Uno.WinUI](https://www.nuget.org/packages/uno.winui)) API sets.

## List of common manual changes for Uno Platform 5.0

### Xaml generator now always uses strict search

This change ensures that the XAML parser will only look for types in an explicit way, and avoids fuzzy matching that could lead to incorrect type resolution.

In order to resolve types properly in a conditional XAML namespace, make use of the [new syntax introduced in Uno 4.8](https://platform.uno/docs/articles/platform-specific-xaml.html?q=condition#specifying-namespaces).

### Enabling Hot Reload

Hot Reload support has changed in Uno Platform 5.0 and a new API invocation is needed to restore the feature in your existing app.

- If your project is built using a shared class library, you'll need to add the following lines to the `csproj`:

    ```xml
    <ItemGroup>
        <PackageReference Include="Uno.WinUI.DevServer" Version="$UnoWinUIVersion$" Condition="'$(Configuration)'=='Debug'" />
    </ItemGroup>
    ```

    > [!NOTE]
    > If your application is using the UWP API set (Uno.UI packages) you'll need to use the `Uno.UI.DevServer` package instead.
- Then, in your `App.cs` file, add the following:

    ```csharp
    using Uno.UI;

    //... in the OnLaunched method

    #if DEBUG
            MainWindow.UseStudio();
    #endif
    ```

Note that Hot Reload has changed to be based on C#, which means that changes done XAML files will need the use of C# Hot Reload feature to be applied to the running app. See [this documentation](xref:Uno.Features.HotReload) for more details.

### Migrating from Xamarin to net7.0-* targets

If your current project is built on Xamarin.* targets, you can upgrade by [following this guide](xref:Uno.Development.MigratingFromXamarinToNet6).

### Migrating from net6.0-*to net7.0-*

There are no significant changes needed to upgrade to .NET 7 for applications (iOS, Android, Catalyst), aside from replacing all occurrences of `net6.0` to `net7.0` or `net8.0` in all your `csproj` files.

For libraries that are depending on `net6.0-android/ios/maccatalyst`, depending on the impact of the breaking changes listed below, you will need to build your libraries with Uno Platform 5.0 packages, as well as target `net7.0-*` or `net8.0-*`.

### Migrating WebAssembly from `netstandard2.0` to `net7.0` or `net8.0`

Migrating from `netstandard2.0` WebAssembly apps to `net7.0` or `net8.0` requires:

- Replacing all occurrences of `netstandard2.0` to `net7.0` or `net8.0` in all your `csproj` files
- Upgrading `Uno.Wasm.Bootstrap*` packages to version `7.0.x` or `8.0.x`, depending on your chosen target framework.

### Migrating to the new `WpfHost`

The `WpfHost` was previously hosted within a WPF `Window` class, but now it takes care of creating individual windows on its own. To migrate, follow these steps:

- Remove the `StartupUri="Wpf/MainWindow.xaml"` attribute from `App.xaml`
- Delete both `MainWindow.xaml` and `MainWindow.xaml.cs`
- In `App.xaml.cs` add the following constructor:

```csharp
public App()
{
    var host = new WpfHost(Dispatcher, () => new AppHead());
    host.Run();
}
```

### Migrating `ApplicationData` on Skia targets

Previously, `ApplicationData` was stored directly in `Environment.SpecialFolder.LocalApplicationData` folder, and all Uno Platform apps shared this single location. Starting with Uno Platform 5.0, application data are stored in application-specific folders under the `LocalApplicationData` root. For more details see the [docs](features/applicationdata.md). To perform the initial migration of existing data you need to make sure to copy the files from the root of the `LocalApplicationData` folder to `ApplicationData.Current.LocalFolder` manually using `System.IO`.

### Updating the Windows SDK from 18362 to 19041

If your existing libraries or UWP/WinAppSDK projects are targeting the Windows SDK 18362, you'll need to upgrade to 19041. A simple way of doing so is to replace all occurrences of `18362` to `19041` in all your solution's `csproj`, `.targets`, `.props`, and `.wapproj` files.

### The Uno.[UI|WinUI].RemoteControl package is deprecated

The `Uno.[UI|WinUI].RemoteControl` is deprecated and should be replaced by `Uno.WinUI.DevServer` (or `Uno.WinUI.DevServer` if you're using UWP).

This is not a required change, as the package `Uno.[UI|WinUI].RemoteControl` transitively uses `Uno.WinUI.DevServer`, but the package will eventually be phased out.

## List of other breaking changes

### `ShouldWriteErrorOnInvalidXaml` now defaults to true

Invalid XAML, such as unknown properties or unknown x:Bind targets will generate a compiler error. Those errors must now be fixed as they are no longer ignored.

### ResourceDictionary now requires an explicit Uri reference

Resources dictionaries are now required to be explicitly referenced by URI to be considered during resource resolution. Applications that are already running properly on WinAppSDK should not be impacted by this change.

The reason for this change is the alignment of the inclusion behavior with WinUI, which does not automatically place dictionaries as ambiently available.

This behavior can be disabled by using `FeatureConfiguration.ResourceDictionary.IncludeUnreferencedDictionaries`, by setting the value `true`.

### `IsEnabled` property is moved from `FrameworkElement` to `Control`

This property was incorrectly located on `FrameworkElement` but its behavior has not changed.

### `RegisterLoadActions` has been removed

This method has been removed as it is not available in WinUI. You can migrate code using this method to use the `FrameworkElement.Loaded` event instead.

### Move `SwipeControl`, `SwipeItem`, `SwipeItemInvokedEventArgs`, `SwipeMode`, `SwipeItems`, `SwipeBehaviorOnInvoked`, `MenuBar`, `MenuBarItem`, and `MenuBarItemFlyout` implementation from WUX namespace to MUX namespace

These controls were present in both the `Windows.UI.Xaml` and `Microsoft.UI.Xaml`. Those are now located in the `Microsoft.UI.Xaml` namespace for the UWP version of Uno (Uno.UI).

### Move `AnimatedVisualPlayer`, `IAnimatedVisualSource`, and `IThemableAnimatedVisualSource` from WUX to MUX and `Microsoft.Toolkit.Uwp.UI.Lottie` namespace to `CommunityToolkit.WinUI.Lottie`

This change moves the `AnimatedVisualPlayer` to the appropriate namespace for WinUI, aligned with the WinAppSDK version of the Windows Community Toolkit.

### `SimpleOrientationSensor` should not schedule on `Dispatcher`

`SimpleOrientationSensor` on Android now raises events from a background thread and needs to be explicitly dispatched to the UI thread as needed.

### The following types are removed from public API: `DelegateCommand`, `DelegateCommand<T>`, `IResourceService`, `IndexPath`, and `SizeConverter`

These legacy classes have been removed. Use the [`CommunityToolkit.Mvvm`](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/) package instead.

### `SolidColorBrushHelper` isn't available in UWP, so we are making it internal

This type is not present in WinUI, use `new SolidColorBrush(xxx)` instead.

### Application.OnWindowCreated does not exist in WinAppSDK

The method has been removed.

### `DependencyObjectGenerator` no longer generated an empty ApplyCompiledBindings method

These methods have been unused since Uno 3.0 and have been removed.

### `EasingFunctionBase` API is now aligned with WinUI

The easing functions classes are now inheriting properly from `EasingFunctionBase`.

### Remove `ResourcesService` and `ResourceHelper`

The legacy `ResourcesService` and `ResourceHelper` have been removed.

### Implicit conversion from string to `Point` is removed

The implicit conversion has been removed but a conversion can be performed using the `XamlBindingHelper` class.

### Rename `CreateTheamableFromLottieAsset` to `CreateThemableFromLottieAsset`

This change is a rename for an identifier typo. Renaming the invocation to the new name is enough.

### Timeline shouldn't implement IDisposable

Timeline does not implement `IDisposable` anymore. This class was not supposed to be disposable and has been removed.

### `GridExtensions` and `PanelExtensions` are removed

These legacy classes have been removed.

### `GetLeft`, `GetTop`, `SetLeft`, `SetTop`, `GetZIndex`, and `SetZIndex` overloads that take DependencyObject are now removed

Those legacy overloads are now removed and the UIElement overloads should be used instead.

### BaseFragment is not needed and is now removed

The legacy BaseFragment class has been removed. Use `Page` navigation instead.

### `ViewHelper.GetScreenSize` method on iOS/macOS is now internal

Use the `DisplayInformation` class instead.

### `FrameworkElement` constructors are now protected instead of public

Use the `Control` class instead.

### `ViewHelper.MainScreenScale` and `ViewHelper.IsRetinaDisplay` are removed in iOS and macOS

Use the `DisplayInformation` class instead.

### WebView.NavigateWithHttpRequestMessage parameter type is now `Windows.Web.Http.HttpRequestMessage` instead of `System.Net.Http.HttpRequestMessage`

Use the new types instead.

### `OnVerticalOffsetChanged` and `OnHorizontalOffsetChanged` are now private instead of virtual protected

Use the related events instead.

### `FrameBufferHost` and `GtkHost` constructors that take `args` are now removed. `args` were already unused

You can remove the last argument of the constructor invocation. The parameters are read by the host directly.

### `RegisterDefaultStyleForType` methods were removed

This legacy method was deprecated in Uno 3.x

### Xaml code generator was generating an always-null-returning FindResource method. This method is no longer generated

This legacy method was deprecated in Uno 3.x

### The type `Windows.Storage.Streams.InMemoryBuffer` is removed

Use `Windows.Storage.Streams.Buffer` instead.

### `ContentPropertyAttribute.Name` is now a field to match UWP

This change has no effect on Control's behavior.

### Remove `FontWeightExtensions` and `CssProviderExtensions`

`Uno.UI.Runtime.Skia.GTK.UI.Text.FontWeightExtensions` and `Uno.UI.Runtime.Skia.GTK.Extensions.Helpers.CssProviderExtensions` don't exist in UWP/WinUI. So they are made internal.

### Change `GtkHost`, `WpfHost`, `FrameBufferHost` namespaces

`GtkHost`, `WpfHost`, and `FrameBufferHost` are now `Uno.UI.Runtime.Skia.Gtk.GtkHost`, `Uno.UI.Runtime.Skia.Wpf.WpfHost`, and `Uno.UI.Runtime.Skia.Linux.FrameBuffer.FrameBufferHost` instead of `Uno.UI.Runtime.Skia.GtkHost`, `Uno.UI.Skia.Platform.WpfHost`, and `Uno.UI.Runtime.Skia.FrameBufferHost`, respectively.

### Change `RenderSurfaceType` namespace

There used two be two `RenderSurfaceType`s, `Uno.UI.Runtime.Skia.RenderSurfaceType` (for Gtk) and `Uno.UI.Skia.RenderSurfaceType` (for Skia). They are now `Uno.UI.Runtime.Skia.Gtk.RenderSurfaceType` and `Uno.UI.Runtime.Skia.Wpf.RenderSurfaceType` respectively.

### `Panel`s no longer measure or arrange any children in `MeasureOverride` or `ArrangeOverride`, respectively

`Panel`s used to measure and arrange the first child in `MeasureOverride` or `ArrangeOverride`, respectively. This is no longer the case. Now, to match WinUI, `Panel`s just return an empty size in `MeasureOverride`, and the `finalSize` as is in `ArrangeOverride`. You should override these layout-override methods in `Panel`-derived subclasses instead.

### Remove `Windows.UI.Xaml.Controls.NavigationView` in Uno.WinUI

Uno.WinUI used to have NavigationView both in `Microsoft.UI.Xaml.Controls` and `Windows.UI.Xaml.Controls` namespaces. It's now removed from `Windows.UI.Xaml.Controls` and kept only in `Microsoft.UI.Xaml.Controls` namespace.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/migrating-to-uno-6.md

---
uid: Uno.Development.MigratingToUno6
---

# Migrating to Uno Platform 6.0

Uno Platform 6.0 contains some breaking changes required to provide a consistent experience when using the Skia rendering feature, as well as **the removal of the UWP API set support** and the **removal of the GTK desktop runtime support**.

You can find a list of these changes below.

## Removal of the UWP API Set

Uno Platform started off with UWP as the common API set, then added WinUI/WinAppSDK. Both API sets were kept as a convenience for upgrading to WinUI, and now that WinUI is sufficiently advanced, Uno Platform 6.0 removes the UWP API set entirely.

This makes Uno Platform easier to maintain in the long run and easier to contribute to.

If you're still using the UWP API set, you can see our [migration guides on how to move to WinUI](xref:Uno.Development.UpdatingToWinUI3).

## Removal of Skia GTK Desktop support

Over the years, we've provided desktop platform abstractions through different technologies. While desktop support started with a GTK3 shell as a common ground, Uno Platform 5.6 introduced [specialized shell support for X11, WPF, and AppKit](xref:Uno.Skia.Desktop).

Now that the support for these targets is stable, we're removing the support for the GTK shell for projects that have not yet used the Uno.SDK.

If your project is still using the GTK support, you can keep using Uno Platform 5.6, or [migrate to the Uno.SDK style project](https://platform.uno/docs/articles/migrating-from-previous-releases.html), which uses the latest platform support, including the new Win32 shell feature.

## List of common manual changes for Uno Platform 6.0

### Updating the Desktop Builder

Upgrading the Desktop platform builder is required when moving to Uno Platform 6.0, in order to align builders for all platforms, for all renderers.

To upgrade, in your `Platforms/Desktop/Program.cs`:

- Replace `using Uno.UI.Runtime.Skia;` with `using Uno.UI.Hosting;`
- Replace `SkiaHostBuilder` with `UnoPlatformHostBuilder`

### Use the new Win32 desktop support

Uno Platform 6.0 provides support for a new, faster, and leaner Windows support, which does not depend on additional libraries (like WPF in previous Uno Platform versions). This new support also enables IL, XAML, and Resource Trimming for smaller published app packages.

To upgrade to the Win32 support, in your `Platforms/Desktop/Program.cs`, replace `.UseWindows()` with `.UseWin32()`.

### WinAppSDK 1.7 considerations

Uno Platform 6 updates to WinAppSDK 1.7 when using the [`Uno.SDK`](xref:Uno.Features.Uno.Sdk).

If you encounter the following build error:

```output
error CS1705: Assembly 'Assembly_Name' with identity 'Assembly_Name, Version=255.255.255.255, Culture=neutral, PublicKeyToken=null' uses 'WinRT.Runtime, Version=2.2.0.0, Culture=neutral, PublicKeyToken=99ea127f02d97709' which has a higher version than referenced assembly 'WinRT.Runtime' with identity 'WinRT.Runtime, Version=2.1.0.0, Culture=neutral, PublicKeyToken=99ea127f02d97709'
```

This may be due to a mismatch in the Windows SDK version used by your project.

To fix this issue, add the following to your `.csproj` file to ensure the correct Windows SDK is referenced for the `net9.0-windowsXX` target to build properly:

```xml
<PropertyGroup>
    <WindowsSdkPackageVersion>10.0.19041.57</WindowsSdkPackageVersion>
</PropertyGroup>
```

### Uno Extensions

Uno Platform 6.0 introduces a breaking change to the `Http` Uno Feature:

- The existing `Http` feature still exists, but no longer includes the `Uno.Extensions.Http.Refit` package by default.
- Two new features have been added:
  - **HttpRefit** – Configures `Uno.Extensions.Http.Refit` so you can register and consume REST APIs using Refit’s type-safe client generation.
  - **HttpKiota** – Configures `Uno.Extensions.Http.Kiota` so you can register and consume OpenAPI-defined endpoints using Kiota’s HTTP client generator.

> [!NOTE]
> If you’re upgrading and previously relied on Refit from the `Http` feature, remove `Http` from your `<UnoFeatures>` and add `HttpRefit` instead. See the [HTTP overview](xref:Uno.Extensions.Http.Overview) for more information.

### Optional use of Skia Rendering for iOS, Android, and WebAssembly

In order to use Skia Rendering for these targets, we're adding new APIs that make the bootstrapping of iOS and WebAssembly platforms using common builders.

To upgrade:

- Make sure that your project is using the Uno.SDK.
- In your `.csproj`, add the following to enable Skia rendering:

    ```diff
    <UnoFeatures>
    <!-- Existing features -->
    +  SkiaRenderer;
    </UnoFeatures>
    ```

- In your `Platforms/WebAssembly/Program.cs` change this:

    ```csharp
    public static int Main(string[] args)
    {
        // code omitted for brevity

        Microsoft.UI.Xaml.Application.Start(_ => _app = new App());

        return 0;
    }
    ```

    with the following:

    ```csharp
    using Uno.UI.Hosting;

    ...

    public static async Task Main(string[] args)
    {
        // code omitted for brevity

        var host = UnoPlatformHostBuilder.Create()
            .App(() => new App())
            .UseWebAssembly()
            .Build();

        await host.RunAsync();
    }
    ```

    If your startup code contained a static `_app` field, you can remove it as well. You can also use the top-level program code, as found in the default Uno Platform templates.

> [!NOTE]
> Removing `SkiaRenderer` from `UnoFeatures` inside the project's `.csproj` file to target native rendering, then setting it back after a new build will raise a runtime Exception. You will need to remove `bin` and `obj` folders, and clear site data of the browser app in order to avoid encountering this exception.

- In your `Platforms/iOS/Main.iOS.cs` change the following:

    ```csharp
    using UIKit;

    ...

    public static void Main(string[] args)
    {
        UIApplication.Main(args, null, typeof(App));
    }
    ```

    with the following:

    ```csharp
    using Uno.UI.Hosting;

    ...

    public static void Main(string[] args)
    {
        // code omitted for brevity

        var host = UnoPlatformHostBuilder.Create()
            .App(() => new App())
            .UseAppleUIKit()
            .Build();

        host.Run();
    }
    ```

    You can also use the top-level program code, as found in the default Uno Platform templates.

- In your `Platforms/Android/Main.Android.cs`, change the following:

    ```diff
    public Application(IntPtr javaReference, JniHandleOwnership transfer)
        : base(() => new App(), javaReference, transfer)
    {
    -    ConfigureUniversalImageLoader();
    }

    -private static void ConfigureUniversalImageLoader()
    -{
    -    var config = new ImageLoaderConfiguration.Builder(Context).Build();
    -    ImageLoader.Instance.Init(config);
    -    ImageSource.DefaultImageLoader = ImageLoader.Instance.LoadImageAsync;
    -}
    ```

    Uno Platform handles image loading entirely with the Skia Rendering mode.

- If you had platform specific modifications to your `UIApplicationDelegate` in App.xaml.cs, [some modifications](xref:Uno.Features.CustomizingUIApplicationDelegate) are needed to upgrade.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/native-frame-nav-tutorial.md

---
uid: Uno.Tutorials.UseNativeFrameNav
---

# How to use native Frame navigation

## Example

The complete sample code can be found in [NativeFrameNav on Uno.Samples GitHub repository](https://github.com/unoplatform/Uno.Samples/tree/master/UI/NativeFrameNav).

## Step-by-step instructions

1. Create a new Uno Platform application, following the instructions in [Get Started guide](../get-started.md).
2. Add two more pages (`BlankPage1` and `BlankPage2`) to the `Your_Project_Name` project

    Right-click on the `Your_Project_Name` project -> `Add` -> `New Item...` -> `Page (Uno Platform Windows App SDK)`
    Repeat once
3. Modify the content of `MainPage.xaml`, `BlankPage1.xaml`, and `BlankPage2.xaml` pages to the following:

    ```xml
    <Grid toolkit:VisibleBoundsPadding.PaddingMask="Top">
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>

        <CommandBar Grid.Row="0" Content="CHANGE_THE_TEXT_HERE" />
        <StackPanel Grid.Row="1">
            <TextBlock Text="CHANGE_THE_TEXT_HERE" />
        </StackPanel>
    </Grid>
    ```

    Put a different text for each page: "MainPage", "Content 1", "Content 2".

    > [!NOTE]
    > Add `xmlns:toolkit="using:Uno.UI.Toolkit"` to the `<Page>` element.

4. Add a button for forward navigation in the first two pages:
    - `MainPage.xaml` and `BlankPage1.xaml`:

        ```xml
        <StackPanel Grid.Row="1">
            <TextBlock Text="Main Content" />
            <Button Content="Next Page" Click="GotoNextPage" />
        </StackPanel>
        ```

    - `MainPage.xaml.cs` and `BlankPage1.xaml.cs`:

        ```csharp
        private void GotoNextPage(object sender, RoutedEventArgs e) => Frame.Navigate(typeof(BlankPage1)); // in MainPage
        private void GotoNextPage(object sender, RoutedEventArgs e) => Frame.Navigate(typeof(BlankPage2)); // in BlankPage1
        ```

5. (Optionally) Add an `AppBarButton` to the `CommandBar` for back navigation in the last two pages for Skia heads:
    - `BlankPage1.xaml` and `BlankPage2.xaml`:
        > [!NOTE]
        > Here a platform conditional is used to show the `AppBarButton` on the Skia platforms only. For more information on this feature, check out: [platform specific XAML](../platform-specific-xaml.md)

        ```xml
        <Page ...
              xmlns:skia="http://uno.ui/skia"
              mc:Ignorable="d skia"
              ...>
            <!-- ...  -->
            <CommandBar Grid.Row="0" Content="BlankPage1">
                <CommandBar.PrimaryCommands>
                    <skia:AppBarButton Content="Back" Click="NavigateBack" />
               </CommandBar.PrimaryCommands>
            </CommandBar>
        ```

    - `BlankPage1.xaml.cs`, `BlankPage2.xaml.cs`:

        ```csharp
        private void NavigateBack(object sender, RoutedEventArgs e) => Frame.GoBack(); // in both pages
        ```

6. Enable native frame navigation in `App.cs` or `App.xaml.cs`:

    ```csharp
    public App()
    {
        InitializeLogging();

    #if __IOS__ || __ANDROID__
        Uno.UI.FeatureConfiguration.Style.ConfigureNativeFrameNavigation();
    #endif

        this.InitializeComponent();
        this.Suspending += OnSuspending;
    }
    ```

7. Add some extra setups for navigation:

    ```csharp
    protected override void OnLaunched(LaunchActivatedEventArgs e)
    {
        /* existing code... */

        ConfigureNavigation();
    }

    private void ConfigureNavigation()
    {
    #if __ANDROID__ || __WASM__
        var frame = (Frame)_window.Content;
        var manager = Windows.UI.Core.SystemNavigationManager.GetForCurrentView();

        // Toggle the visibility of back button based on if the frame can navigate back.
        // Setting it to visible has the follow effect on the platform:
        // - uwp: show a `<-` back button on the title bar
        // - wasm: add a dummy entry in the browser back stack
        frame.Navigated += (s, e) => manager.AppViewBackButtonVisibility = frame.CanGoBack
            ? Windows.UI.Core.AppViewBackButtonVisibility.Visible
            : Windows.UI.Core.AppViewBackButtonVisibility.Collapsed;

        // On some platforms, the back navigation request needs to be hooked up to the back navigation of the Frame.
        // These requests can come from:
        // - uwp: title bar back button
        // - droid: CommandBar back button, os back button/gesture
        // - wasm: browser back button
        manager.BackRequested += (s, e) =>
        {
            if (frame.CanGoBack)
            {
                frame.GoBack();

                e.Handled = true;
            }
        };
    #endif
    }
    ```

## Additional Resources

- [Uno-specific documentation](../controls/CommandBar.md) on `CommandBar` and `AppBarButton`
- [Native Frame navigation](../features/native-frame-nav.md)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/native-frame-nav.md

---
uid: Uno.Features.NativeFrameNav
---

# Native Frame Navigation

## Introduction

This article discusses the particularities of the native `Frame` navigation in detail.

It is recommended to be familiar with the concept of navigation in WinUI, here are some good starting points:

- [Navigation design basics for Windows apps](https://learn.microsoft.com/windows/apps/design/basics/navigation-basics)
- [`Microsoft.UI.Xaml.Controls.Frame`](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.frame)

## Native Frame Navigation

On Android and iOS, there is the option to enable native frame navigation. Enabling this feature replaces the default styles and templates of the controls below:

- `Microsoft.UI.Xaml.Controls.Frame`<superscript>*</superscript>
- `Microsoft.UI.Xaml.Controls.CommandBar`
- `Microsoft.UI.Xaml.Controls.AppBarButton`

This feature can be enabled by calling the method below, typically in the constructor of your `App` class in `App.cs` or `App.xaml.cs`:

```csharp
#if __IOS__ || __ANDROID__
    Uno.UI.FeatureConfiguration.Style.ConfigureNativeFrameNavigation();
#endif
```

> [!NOTE]
> It is recommended to enable this feature in order to provide a more native user experience.

### CommandBar and AppBarButton

In essence, by enabling this, a custom renderer will be used as the control template. This renderer injects the native control into the app, and maps dependency properties (colors, content/icon, ...) and events (clicked), between the WinUI controls and the native ones:

WinUI Control|Native Android Control|Native iOS Control
-|-|-
`CommandBar`|`android.widget.Toolbar`|`UIKit.UINavigationBar`
`AppBarButton`|`android.view.MenuItem`|`UIKit.UIBarButtonItem`

As such, you can have the look and feel of the native control, including features like native swipe to go back on iOS, while programming against the WinUI API. However, you are no longer able to customize the control template.

### Frame

The `Frame` also uses a custom presenter for its control template.
On iOS, this presenter creates a `UINavigationController`, and keeps its states in sync with its `Frame`. It also creates a `UIViewController` for each `Page` that gets navigated.
On iOS and Android, it also manages the state of the back button on the `CommandBar`, if it is present on a `Page`.

### Helpers

There is a `FrameNavigationHelper` that is in place to expose useful properties and methods related to Frame-based navigation logic. It contains the following helper methods:

Method|Return Type|Description
-|-|-
`GetCurrentEntry(Frame)`|`PageStackEntry`|Returns the `PageStackEntry` for the currently displayed Page within the given `frame`.
`GetInstance(PageStackEntry)`|`Page`|Returns the actual Page instance of the given `entry`.
`EnsurePageInitialized(Frame, PageStackEntry)`|`Page`|Retrieves the current `Page` instance of the given `PageStackEntry`. If no instance exists, the `Page` will be created and properly initialized to the provided `Frame`.
`CreateNavigationEventArgs(...)`|`NavigationEventArgs`|Creates a new instance of `NavigationEventArgs`.

## Platform Specifics

- Android: Tapping the CommandBar's back button, system back button, or performing the sweep gesture will trigger `SystemNavigationManager.BackRequested`. It's the responsibility of the application's navigation controller to eventually call `Frame.GoBack()`.
- iOS: Tapping the back button automatically triggers a back navigation on the native `UINavigationController` (which is part of the native `Frame` implementation). The `Frame` will raise the `Navigated` event, and its state will automatically be updated to reflect the navigation. The navigation can't be intercepted or canceled.
- all non-Windows platforms: `Uno.UI.FeatureConfiguration.Page.IsPoolingEnabled` can be set to enable reuse of `Page` instances. Enabling this allows the pages in the forward stack to be recycled when stack is modified, which can improve performance of `Frame` navigation.
- Android: On mobile, the pages in the back stack are still preserved in the visual tree for performance reasons. This feature can be disabled on Android by setting `Uno.UI.FeatureConfiguration.NativeFramePresenter.AndroidUnloadInactivePages = true`.
- WASM: `SystemNavigationManager.AppViewBackButtonVisibility` needs to be set to `Visible` to intercept the browser back navigation. The intercepted event is forwarded to `SystemNavigationManager.BackRequested`. It's the responsibility of the application's navigation controller to eventually call `Frame.GoBack()`.

## Additional Resources

- [`CommandBar` and `AppBarButton` Uno documentation](../controls/CommandBar.md)
- [How to use native Frame navigation](../guides/native-frame-nav-tutorial.md)
- [Native frame navigation sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/NativeFrameNav)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/native-styles.md

---
uid: Uno.Development.NativeStyles
---

# Using platform-native control styles

By default, controls in Uno Platform applications are rendered exactly the same way on every target platform. But for Android and iOS, an additional set of 'native' [control styles](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/xaml-styles) are included, which customize the [templates of the controls](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/control-templates) to make them look and behave natively. In fact, the native high-level equivalents of each control are placed inside the native control template.

## About native control styles

For supported controls, two pre-defined styles are provided:

* NativeDefault[Control] which is customized to match the UI guidelines of the target platform.
* XamlDefault[Control] which are consistent in look and behavior across platforms.

If native control styles are desired, they can be enabled either globally for the whole application, or individually per control.

In general, control properties like `Button.Command` and `CheckBox.IsChecked` are supported when using native styles, but some properties that normally modify the visual appearance of the control may not be supported.

The full set of native control styles can be found in [Generic.Native.xaml](https://github.com/unoplatform/uno/blob/master/src/Uno.UI/UI/Xaml/Style/Generic/Generic.Native.xaml).

> [!NOTE]
> Third-party libraries can define native variants of default styles for custom controls, using the `not_win:IsNativeStyle="True"` tag in XAML. These will be used if the consuming application is configured to use native styles.

On WASM, the `NativeDefault[Control]` styles are currently only aliases to the `XamlDefault[Control]`, for code compatibility with other platforms.

## Enabling native control styles globally

An application can set native styles as the default for supported controls by setting the static flag `Uno.UI.FeatureConfiguration.Style.UseUWPDefaultStyles = false;` somewhere in app code (typically from the `App()` constructor in `App.cs` or `App.xaml.cs`). It's also possible to configure only certain control types to default to the native style, by adding an entry to `UseUWPDefaultStylesOverride` for that type. For example, to default to native styling for every `ToggleSwitch` in the app, you would add the following code: `Uno.UI.FeatureConfiguration.Style.UseUWPDefaultStylesOverride[typeof(ToggleSwitch)] = false;`

The default Uno app template includes Fluent control styles in the application. If enabling native control styles globally, these Fluent resources **should be removed from `App.xaml`**, by removing `<XamlControlsResources />` from the `Resources.MergedDictionaries` declaration.

In order for the native styles to be used globally by default, you cannot include resources in your `App.xaml` that also contain implicit styles for those same controls. For example, if you are using Uno.Material or Uno.Cupertino, those resources will override the native styles and, therefore, cannot be used if you are planning to enable native styles globally. You should remove the corresponding resource dictionaries from `App.xaml`.

### Native navigation styles

Since there are several controls that participate in navigation (`Frame`, `CommandBar`, `AppBarButton`), which should all be configured in the same way if native Frame navigation is used, there's a convenience method for configuring them all to use native styles:

```csharp
#if !NETFX_CORE
    Uno.UI.FeatureConfiguration.Style.ConfigureNativeFrameNavigation();
#endif
```

### Example

This sample shows how you'd enable native styles globally for your whole app. You need to modify both `App.cs` and `App.xaml`:

`App.xaml.cs`:

```diff
public class App : Application
{
    public static Window? _window;

+    public App()
+    {
+ #if HAS_UNO
+        FeatureConfiguration.Style.UseUWPDefaultStyles = false;
+ #endif
+    }

    protected override void OnLaunched(LaunchActivatedEventArgs args)
    {
        // OnLaunched Logic...
    }
}
```

App.xaml:

```diff
 <ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <ResourceDictionary.MergedDictionaries>
-        <!--  Load WinUI resources  -->
-        <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />

    </ResourceDictionary.MergedDictionaries>
    <!--  Add resources here  -->

 </ResourceDictionary>
```

## Enable native styling on a single control

To enable native styling on a per-control basis, you can set the native style explicitly on the control, referencing the `NativeDefault[Control]` style name.

For example, to use native styling on a single `CheckBox` in XAML:

```xml
<Page x:Class="MyApp.MainPage"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:local="using:MyApp"
      xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
      xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
      xmlns:win="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:not_win="http://uno.ui/not_win"
      mc:Ignorable="d not_win"
      Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

    <Grid>
        <!--  This check box will use a platform-native style on Android and iOS  -->
        <CheckBox IsChecked="{Binding OptionSelected}"
                  not_win:Style="{StaticResource NativeDefaultCheckBox}" />
    </Grid>
</Page>
```

Note the use of the `not_win` prefix - this [conditional XAML prefix](platform-specific-xaml.md) ensures that the code compiles on Windows, where the `NativeDefaultCheckBox` resource doesn't exist.

You can use the native styles as you would any XAML style - you can extend them in your own `Style` definitions using `BasedOn={StaticResource NativeDefaultCheckBox}`, for instance.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/native-views.md

---
uid: Uno.Development.NativeViews
---

# Incorporating native views to the Uno visual tree

The Android, iOS, and macOS targets for Uno support the notion of a purely native view, that is not coming from Uno Platform but instead defined in a third-party library, via a Xamarin binding, or in the native framework itself. Since Uno's views are inheriting from the base native view type on these platforms, you can incorporate native views into your app's visual tree.

## Adding JavaScript views in WebAssembly

On WebAssembly, for both Native and Skia renderers, [Read this guide](xref:Uno.Interop.WasmJavaScript1) to learn how to use native views.

## Adding native views in Skia

On Skia targets, integrating native views is done differently. [Read this guide](xref:Uno.Skia.Embedding.Native) to learn how.

## Native Views for Native iOS/Android

### Adding native views in XAML

There's no special syntax required when adding native views in XAML when using the Native renderer, apart from [platform conditionals](xref:Uno.Development.PlatformSpecificXaml) to ensure that the XAML compiles for all platforms. Uno's XAML parser supplies the needed 'glue', including supplying common constructor parameters (such as the `Context` parameter on Android).

An example:

```xml
Background="{ThemeResource ApplicationPageBackgroundThemeBrush}"
xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
xmlns:android="http://uno.ui/android"
xmlns:androidwidget="using:Android.Widget"
mc:Ignorable="d android"
...

<StackPanel Margin="0,30,0,0">
 <TextBlock Text="Rating" />
 <android:Grid Background="Beige"
      Width="200">
  <androidwidget:RatingBar />
 </android:Grid>
</StackPanel>
```

### Adding native views in code

Adding native views in C# code requires you to first 'wrap' the native view in a special `UIElement`, because 'container' elements like `Panel` and `Border` expect a child of type `UIElement` (as of Uno 3.0 and above). The recommended way to do this is with the `VisualTreeHelper.AdaptNative()` static method:

```csharp
using Windows.UI.Xaml.Media
...

var ratingBar = new Android.Widget.RatingBar(Uno.UI.ContextHelper.Current);
var wrapped = VisualTreeHelper.AdaptNative(ratingBar);
_myBorder.Child = wrapped;
```

Note that `VisualTreeHelper.AdaptNative()` will throw an exception if it receives a `FrameworkElement`. If you're in a context where you don't know if the view you want to display is actually a purely native view or a managed `FrameworkElement` type, you can use `VisualTreeHelper.TryAdaptNative()` instead.

Assigning a native view directly as the `Content` property of `ContentPresenter` or `ContentControl` is also supported (since `Content` is of type `object`).

### Troubleshooting

Uno makes certain assumptions about native views when it displays them, which may not always hold (eg that `SizeThatFits()` is implemented on iOS). Here are some things to try if your view isn't displaying:

- check the documentation and ensure you're configuring the native control correctly.
- try setting a fixed `Width` and `Height` on the outer XAML container.
- try setting the dimensions of the native view via code-behind.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/net-version-support.md

---
uid: Uno.Development.NetVersionSupport
---

<!-- markdownlint-disable MD001 -->

# .NET version support

This page lists supported .NET versions and [C# language versions](https://learn.microsoft.com/dotnet/csharp/language-reference/configure-language-version) for different target platforms.

## Table of supported versions

# [**Uno Platform 6.3 and later**](#tab/uno63)

| Platform                                   | Default .NET version | Default C# version |  Max .NET version | Max C# version |
|--------------------------------------------|:--------------------:|:------------------:|:-----------------:|:--------------:|
| WebAssembly                                | .NET 9               | 13                 | .NET 10           | 14             |
| Skia Desktop                               | .NET 9               | 13                 | .NET 10           | 14             |
| WinAppSDK                                  | .NET 9               | 13                 | .NET 10           | 14             |
| iOS, Android                               | .NET 9               | 13                 | .NET 10           | 14             |

### Notes

- In Uno Platform 6.3, support for .NET 8 has been removed.
- [.NET 9.0](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-9/overview), the successor to .NET 8, has a special focus on cloud-native apps and performance.
  As a Standard Term Support (STS) release, it is now supported for **24 months (until November 10, 2026)**. See the [STS latest announcement](https://devblogs.microsoft.com/dotnet/dotnet-sts-releases-supported-for-24-months/) for more details.

  > [!NOTE]
  > For **mobile workloads**, there is **no change yet**, support remains at **18 months**. See [MAUI support policy](https://dotnet.microsoft.com/en-us/platform/support/policy/maui) for more details.

- [.NET 10.0](https://learn.microsoft.com/en-us/dotnet/core/whats-new/dotnet-10/overview), the successor to .NET 9, includes improvements in performance, C# 14 support, and long-term platform stability.
  As a Long Term Support (LTS) release, it will be supported for **three years (until November 2028)**.
  At the moment, it is in preview and the least stable option for new projects.

# [**Uno Platform 5 and later**](#tab/uno5)

| Platform                                   | Default .NET version | Default C# version |  Max .NET version | Max C# version |
|--------------------------------------------|:--------------------:|:------------------:|:-----------------:|:--------------:|
| WebAssembly                                | .NET 8               | 12                 | .NET 9            | 13             |
| Skia Desktop                               | .NET 8               | 12                 | .NET 9            | 13             |
| WinAppSDK                                  | .NET 8               | 12                 | .NET 9            | 13             |
| iOS, Android                               | .NET 8               | 12                 | .NET 9            | 13             |

### Notes

- In Uno Platform 5.3, support for .NET 7 has been removed.
- In Uno Platform 5.0, support for .NET 6 (iOS, Android, mac Catalyst), Xamarin.Android, Xamarin.iOS, and Xamarin.macOS were removed.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/open-id-connect.md

---
uid: Uno.Tutorials.OpenIDConnect
---

# Authentication using OpenID Connect

OpenID Connect is a layer over OAuth 2.0, allowing a simpler integration into applications, especially when the OpenID  Connect Discovery is used.

This article will document the usage of `IdentityModel.OidcClient` into an Uno application using the [`WebAuthenticationBroker`](../features/web-authentication-broker.md). You can find more in [the IdentityModel.OidcClient documentation](https://identitymodel.readthedocs.io/en/latest/native/overview.html).

> The code of this article can be found in the [Uno Samples GitHub repository](https://github.com/unoplatform/Uno.Samples/tree/master/UI/Authentication.OidcDemo).

## Limitations

- **Platforms**: The `WebAuthenticationBroker` is not supported on all platforms yet. For Uno 3.6 it is implemented only on WebAssembly, Android, iOS and macOS.
- **Return URI on WebAssembly**: Because of browser security restrictions, on WebAssembly, the return URL must be on the same origin as the application. On other platforms the best approach is to use a custom protocol scheme (like `my-application:`). For most applications, you may simply use the automatic discovery of return URLs, which will use the [`WebAuthenticationBroker.GetCurrentApplicationCallbackUri()` method](https://learn.microsoft.com/uwp/api/windows.security.authentication.web.webauthenticationbroker.getcurrentapplicationcallbackuri).
- **Browser Anti-Popup Protection**: On WebAssembly, a foreign/public web site is usually used to authenticate the user. Doing this without losing the application context requires the opening of a new browser window. To ensure the window will open on all browsers without being denied, this new window **must be opened using the handling of a user interaction**. For this reason the IdentityModel.OidcClient's *automatic mode* can't be used because it's doing async processing (fetching the discovery endpoint) before opening the authentication browser.

## Demo Endpoint

This code uses the *IdentityServer* demonstration endpoint with the following parameters:

| Field     | Value                                     |
| --------- | ----------------------------------------- |
| Authority | `https://demo.duendesoftware.com/`        |
| ClientId  | `interactive.confidential`                |
| Secret    | `secret`                                  |
| Scopes    | `openid profile email api offline_access` |

> Note: this endpoint allows any return URIs. It's acceptable for demo purposes, but production application will usually requires to register return addresses.

## Step 0 - Install Uno + Create an Application

Please refer to the [Getting Started documentation](../get-started.md) to install Uno and create a new application. For the sample below, an application named `OidcDemo` has been created.

For platforms supporting it, the custom protocol "oidc-auth:" will be used.

## Step 1 - Add Reference to OidcClient package

Add the package [`IdentityModel.OidcClient`](https://www.nuget.org/packages/IdentityModel.OidcClient) to all relevant *head* projects of the solution.

## Step 2 - Prepare for Return Uri

### Android

Add the following class in the project of the Android Head.

```csharp
[Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
[IntentFilter(
    new[] {Android.Content.Intent.ActionView},
    Categories = new[] {Android.Content.Intent.CategoryDefault, Android.Content.Intent.CategoryBrowsable},
    DataScheme = "oidc-auth")]
public class WebAuthenticationBrokerActivity : WebAuthenticationBrokerActivityBase
{
}
```

Note the `[Activity]` attribute needs to include `Exported = true` if you are targeting Android 12.

This activity will intercept the return URI and forward it to any waiting `WebAuthenticationBroker`.

Note: it's using the system browser. Check the [WebAuthenticationBroker documentation](../features/web-authentication-broker.md) to use another mechanism.

### iOS & macOS

Add the `oidc-auth:` custom scheme in `Info.plist` file.

```xml
<key>CFBundleURLTypes</key>
<array>
 <dict>
  <key>CFBundleURLName</key>
  <string>Authentication Callback</string>
  <key>CFBundleURLSchemes</key>
  <array>
   <string>oidc-auth</string>
  </array>
 </dict>
</array>
```

Alternatively, you can use the editor integrated in Visual Studio to set it, in the *advanced* tab:

![Return Url in iOS](../Assets/features/authenticationbroker/return-url-editor.png)

### WinUI

There's nothing special for WinUI. Any return URI will work.  You can force it to `oidc-auth:` if you want, but you won't have any special registration to do to support it.

### WebAssembly

There's nothing special for WASM. The default *return Uri* of the platform (`WebAuthenticationBroker.GetCurrentApplicationCallbackUri()`) will work with this sample and will default to `<origin>/authentication-callback`. It should be something like `http://localhost:5000/authentication-callback` when running locally using Kestrel.

## Step 3 - Prepare the UI

Add the following lines in your application, in `[Project-name]/MainPage.xaml`:

```xml

<!--Add this line with the other dependencies-->
xmlns:toolkit="using:Uno.UI.Toolkit"

<!--This will replace the initial Grid-->
<Border toolkit:VisibleBoundsPadding.PaddingMask="All">
    <StackPanel Spacing="10" Margin="10">
        <StackPanel Orientation="Horizontal" Spacing="5">
            <Button Click="SignIn_Clicked" x:Name="btnSignin" IsEnabled="False">Sign In</Button>
            <Button Click="SignOut_Clicked" x:Name="btnSignout" IsEnabled="False">Sign Out</Button>
        </StackPanel>
        <TextBlock x:Name="txtAuthResult" />
    </StackPanel>
</Border>
```

## Step 4 - Prepare the Requesting Code

Add the following code to the main page of your application:

```csharp
//add this namespace on top of the class
using IdentityModel.OidcClient;

// Put this code in the class of MainPage.xaml.cs
private OidcClient _oidcClient;
private AuthorizeState _loginState;
private Uri _logoutUrl;

public MainPage()
{
    this.InitializeComponent();
    PrepareClient();
}

private async void PrepareClient()
{
    var redirectUri = WebAuthenticationBroker.GetCurrentApplicationCallbackUri().OriginalString;

    // Create options for endpoint discovery
    var options = new OidcClientOptions
    {
        Authority = "https://demo.duendesoftware.com/",
        ClientId = "interactive.confidential",
        ClientSecret = "secret",
        Scope = "openid profile email api offline_access",
        RedirectUri = redirectUri,
        PostLogoutRedirectUri = redirectUri,
    };

    // Create the client. In production application, this is often created and stored
    // directly in the Application class.
    _oidcClient = new OidcClient(options);

    // Invoke Discovery and prepare a request state, containing the nonce.
    // This is done here to ensure the discovery mechanism is done before
    // the user clicks on the SignIn button. Since the opening of a web window
    // should be done during the handling of a user interaction (here it's the button click),
    // it will be too late to reach the discovery endpoint.
    // Not doing this could trigger popup blocker mechanisms in browsers.
    _loginState = await _oidcClient.PrepareLoginAsync();
    btnSignin.IsEnabled = true;

    // Same for logout url.
    _logoutUrl = new Uri(await _oidcClient.PrepareLogoutAsync(new LogoutRequest()));
    btnSignout.IsEnabled = true;
}
```

## Step 5 - Proceed to Authentication

Add following button handlers:

```csharp
private async void SignIn_Clicked(object sender, RoutedEventArgs e)
{
    var startUri = new Uri(_loginState.StartUrl);

    // Important: there should be NO await before calling .AuthenticateAsync() - at least
    // on WebAssembly, in order to prevent triggering the popup blocker mechanisms.
    var userResult = await WebAuthenticationBroker.AuthenticateAsync(WebAuthenticationOptions.None, startUri);
 
    if (userResult.ResponseStatus != WebAuthenticationStatus.Success)
    {
        txtAuthResult.Text = "Canceled";
        // Error or user cancellation
        return;
    }

    // User authentication process completed successfully.
    // Now we need to get authorization tokens from the response
    var authenticationResult = await _oidcClient.ProcessResponseAsync(userResult.ResponseData, _loginState);

    if (authenticationResult.IsError)
    {
        var errorMessage = authenticationResult.Error;
        // TODO: do something with error message
        txtAuthResult.Text = $"Error {errorMessage}";
        return;
    }

    // That's completed. Here you have to token, ready to do something
    var token = authenticationResult.AccessToken;
    var refreshToken = authenticationResult.RefreshToken;

    // TODO: make something useful with the tokens
    txtAuthResult.Text = $"Success, token is {token}";
}

private async void SignOut_Clicked(object sender, RoutedEventArgs e)
{
    // Important: there should be NO await before calling .AuthenticateAsync() - at least
    // on WebAssembly, in order to prevent triggering the popup blocker mechanisms.
    await WebAuthenticationBroker.AuthenticateAsync(WebAuthenticationOptions.None, _logoutUrl);
}
```

## Step 6 - Finalize & Compile

> [!IMPORTANT]
> On WebAssembly, it's important to configure the linker to prevent the removal of some important part of the *OIDC Connect* client library:
> `LinkerConfig.xml`:
>
> ```xml
> <linker>
>   <assembly fullname="My.Oidc.Client.App.Wasm" />
>   <assembly fullname="Uno.UI" />
>
>   <!-- ADD THE FOLLOWING 2 LINES -->
>   <assembly fullname="IdentityModel" />
>   <assembly fullname="System.IdentityModel.Tokens.Jwt" />
>
>   <assembly fullname="System.Net.Http" />
>
>   <assembly fullname="System.Core">
>  <!-- This is required by JSon.NET and any expression.Compile caller -->
>  <type fullname="System.Linq.Expressions*" />
>   </assembly>
> </linker>
> ```

Now compile & Run!

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/orientation-sensor.md

---
uid: Uno.Features.OrientationSensor
---

# Orientation sensor

> [!TIP]
> This article covers Uno-specific information for SimpleOrientationSensor. For a full description of the feature and instructions on using it, see [SimpleOrientationSensor Class](https://learn.microsoft.com/uwp/api/windows.devices.sensors.simpleorientationsensor).

* The `Windows.Devices.Sensors.SimpleOrientationSensor` class allows you to determine the general orientation of the device.

## Supported features

| Feature              | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|----------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `GetDefault`         | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `OrientationChanged` | ✔       | ✔       | ✔   | ✔          | ✖     | ✖            | ✖            |

> [!IMPORTANT]
> The `OrientationChanged` event is not supported by iOS simulators.

## Using SimpleOrientationSensor with Uno

* The `GetDefault` method is available on all targets and will return `null` on those that do not support `SimpleOrientationSensor` or devices that do not have such a sensor.
* Ensure to unsubscribe from the `OrientationChanged` event when you no longer need the readings so that the sensor is no longer active to avoid unnecessary battery consumption.

## Example

### Capturing sensor readings

```csharp
var simpleOrientationSensor = SimpleOrientationSensor.GetDefault();
simpleOrientationSensor.OrientationChanged += SimpleOrientationSensor_OrientationChanged;

private async void SimpleOrientationSensor_OrientationChanged(object sender, SimpleOrientationSensorOrientationChangedEventArgs args)
{
    // If you want to update the UI in some way, ensure the Dispatcher is used,
    // as the OrientationChanged event handler does not run on the UI thread.
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        switch (orientation)
        {
            case SimpleOrientation.NotRotated:
                tb.Text = "Not Rotated";
                break;
            case SimpleOrientation.Rotated90DegreesCounterclockwise:
                tb.Text = "Rotated 90 Degrees Counterclockwise";
                break;
            case SimpleOrientation.Rotated180DegreesCounterclockwise:
                tb.Text = "Rotated 180 Degrees Counterclockwise";
                break;
            case SimpleOrientation.Rotated270DegreesCounterclockwise:
                tb.Text = "Rotated 270 Degrees Counterclockwise";
                break;
            case SimpleOrientation.Faceup:
                tb.Text = "Faceup";
                break;
            case SimpleOrientation.Facedown:
                tb.Text = "Facedown";
                break;
            default:
                tb.Text = "Unknown orientation";
                break;
        }
    });
}
```

### Unsubscribing from the readings

```csharp
simpleOrientationSensor.OrientationChanged -= SimpleOrientationSensor_OrientationChanged;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/orientation.md

---
uid: Uno.Features.Orientation
---

# Controlling orientation

The application's orientation can be controlled using the [DisplayInformation](https://learn.microsoft.com/uwp/api/windows.graphics.display.displayinformation) class, more specifically, the static [AutoRotationPreferences](https://learn.microsoft.com/uwp/api/windows.graphics.display.displayinformation.autorotationpreferences) property.

## Controlling Orientation on iOS

In order for the DisplayInformation's AutoRotationPreferences to work properly, you need to ensure that all potential orientations are supported within the iOS application's `info.plist` file.

> [!WARNING]
> On iOS 9 and above, the system does not allow iPad applications to dictate their orientation if they support [Multitasking / Split View](https://developer.apple.com/library/archive/documentation/WindowsViews/Conceptual/AdoptingMultitaskingOniPad/). In order to control orientation through the DisplayInformation class, you will need to opt-out of Multitasking / Split View by ensuring that you have defined the following in your `info.plist`:
>
> ```xml
> <key>UIRequiresFullScreen</key>
> <true/>
> ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/concepts/overview/philosophy-of-uno.md

---
uid: Uno.Overview.Philosophy
---

# Philosophy of Uno Platform

## Mission

**To empower developers to build pixel-perfect, single-codebase applications for Windows, WebAssembly, iOS, macOS, Android, and Linux.**

Uno Platform is committed to providing tools for developers to efficiently create high-quality, native-feeling applications across all modern platforms from a unified codebase.

## Vision

Uno Platform strives to be the leading cross-platform UI framework enabling .NET developers to reuse their skills and code, thereby shrinking development time and cost while maximizing reach. Our vision is to make true cross-platform UI/UX parity possible—whether deploying to mobile, web, or desktop—with full support for the latest device capabilities, modern tooling including AI, and next-generation development experiences.

---

## Core Philosophy & Principles

### 1. Leverage Existing Tools and Skills

Uno Platform is built on the foundation of well-established Microsoft technologies—including XAML and C#—so developers can apply the skills they already know instead of learning entirely new paradigms. And because Uno Platform supports development from any operating system, teams can build and ship cross-platform applications using the tools and workflows that fit their environment best.

**Key Benefits:**

- Maximize productivity with cross-OS tooling like C# and XAML Hot Reload, Hot Design for real-time visual editing, AI-powered assistance through Docs MCP and App MCP, and streamlined CLI tools such as uno-check and project templates.
- Build apps using proven Microsoft technologies and deploy to multiple platforms: WebAssembly, iOS, Android, macOS, Windows, and Linux
- Reduce learning curve for .NET developers transitioning to cross-platform development
- Day-0 support for the latest .NET and Visual Studio ecosystems

### 2. AI-Powered Agentic Development

As of 2024-2026, Uno Platform has embraced AI-powered development workflows to dramatically increase developer productivity while maintaining full developer control.

**Innovation Highlights:**

- **Hot Design:** The only visual designer that enables real-time, on-app visual editing and AI-assisted UI creation.
- **AI Agents in Development:** Uno Platform Studio 2.0 (an AI-powered development tool suite) introduces AI assistants like the Hot Design Agent, an AI-powered design assistant that can understand your code, context, and even control the running app to suggest and implement UI changes in real time
- **Human-in-the-Loop:** Developers preview and approve changes, ensuring quality while benefiting from AI assistance
- **MCP Servers:** AI interacts with documentation, APIs, app states, and UI elements live via Model Context Protocol (MCP) servers, providing context-aware assistance
- **App Live Testing:** AI agents can interact with running apps, trigger UI events, and automate testing/debugging with human approval

This approach represents a fundamental shift in how developers work—enabling faster iterations, better design fidelity, and reduced time-to-market without sacrificing code quality or control.

### 3. Pixel-Perfect, Rich, and Responsive UIs

We believe developers shouldn't have to choose between productivity and great design. Uno Platform prioritizes both.

**Our Commitment:**

- Support sophisticated animations, templating, and visual effects
- Achieve responsive, pixel-perfect interfaces that adapt across devices
- Enable designers and developers to work together seamlessly with tools like Figma integration (one-click export from Figma to C# or XAML)
- Provide visual designers with hot reload capabilities on running apps for instant feedback

### 4. Separation of Concerns

Uno Platform advocates a clear separation between model, view, and presentation logic, promoting MVVM (Model-View-ViewModel) principles.

**Architecture Benefits:**

- Clean, maintainable code using features like data binding and attached properties
- Support for both classic MVVM and modern state management approaches (MVUX)
- Scalable application architecture that grows with your team and project
- Testable code with clear boundaries between business logic and UI

### 5. Native Inter-compatibility

While promoting maximum code reuse as the ideal approach, Uno recognizes the need for platform-specific functionality.

**Flexibility Features:**

- Support "escape hatches" for platform-specific code when needed
- Easy integration of native third-party libraries and APIs
- Ability to call platform-specific APIs directly from shared code
- Hybrid UI scenarios combining web and native elements

### 6. Performance as a Feature

Performance is not an afterthought; it's a primary consideration. We prioritize optimization based on real-world profiling and ongoing enhancements to ensure apps are fast and responsive.

**Performance Focus:**

- Optimized Skia rendering engine for smoother performance
- Hardware-accelerated UI features (e.g., hardware-accelerated shadows)
- Optimized image loading (e.g., offloading decoding to WebWorkers for WebAssembly)
- Continuous profiling and performance improvements in every release
- Prevention of poor user experiences and negative reviews through proactive performance work

---

## Comprehensive Cross-Platform Support

Uno Platform enables building applications for all major platforms from a **single codebase**:

- **Windows** (Win32, UWP, WinUI 3)
- **WebAssembly** (Browser-based, no plugins required)
- **iOS** (iPhone and iPad)
- **Android** (Phones and tablets)
- **macOS** (Native Mac applications)
- **Linux** (GTK-based applications)
- **Embedded devices** (IoT and specialized hardware)

This comprehensive support dramatically lowers maintenance costs and reduces time-to-market for updates and new features.

---

## Enterprise-Grade Tooling & Ecosystem

### Development Tools

- **Visual Studio Integration:** Full support for Visual Studio 2026 (and previous versions)
- **Always on the latest .NET:** Day-0 support for new .NET releases, with preview‑specific builds available for teams who want to stay on the bleeding edge.
- **Hot Reload & Real-Time UI Design:** Visual designer lets you tweak XAML and C# on a running app with instant changes
- **Status Indicators:** Enhanced developer experience with environment health monitoring, restore progress, and SDK validation

### Rich Component Ecosystem

- Seamless integration with **WinUI controls**
- **Windows Community Toolkit**
- **Uno Toolkit** for additional controls and extensions
- **.NET MAUI controls** compatibility
- Hundreds of UI components available out of the box
- Extensive open-source and 3rd party libraries support

### Collaboration Features

- **Figma Integration** for rapid prototyping and design handoff
- **Modern Solution Formats:** Support for the human-readable `.slnx` solution format for easier team collaboration and code reviews
- **Source Control Friendly:** Designed with team development and version control in mind

---

## Open Source and Commercial Flexibility

Uno Platform balances open-source principles with commercial sustainability:

- **Open-Source Foundation:** Free and open-source under the Apache 2.0 license
- **Commercial Tools:** Optional AI-powered workflows and visual designers available
- **Community Edition:** Full access to core platform features
- **Professional Edition:** Advanced features for enterprise teams
- **Educational Support:** Discounts for educational institutions and open-source contributors

---

## Why Uno Platform?

### For Organizations

- **Cost Efficiency:** Single codebase significantly reduces development and maintenance costs compared to platform-specific implementations
- **Faster Time-to-Market:** Deploy to all platforms simultaneously rather than building separately
- **Future-Proof:** Active development, regular updates, and commitment to latest technologies
- **Risk Mitigation:** Open-source foundation ensures you're never locked in

### For Developers

- **Leverage Existing Skills:** Use your C# and XAML knowledge immediately
- **Career Growth:** Cross-platform expertise is highly valued in the market
- **Modern Tooling:** AI-assisted development, hot reload, visual designers
- **Community Support:** Active community, extensive documentation, and commercial support options

### For Teams

- **Unified Codebase:** Frontend and backend teams can work in the same language and ecosystem
- **Design-Developer Collaboration:** Figma integration and visual tools bridge the gap
- **Scalable Architecture:** From prototypes to enterprise applications
- **Quality Assurance:** Single codebase means testing once deploys everywhere

---

## Looking Forward

Uno Platform continues to evolve with the industry, embracing:

- **AI Integration:** Making AI-powered development accessible and productive
- **Modern .NET:** Supporting the latest .NET releases on day-0
- **Performance:** Continuous optimization for better user experiences
- **Developer Experience:** Tools that make developers more productive and happier
- **Platform Expansion:** Supporting emerging platforms and form factors

Our philosophy is simple: **empower developers with the best tools, leverage proven technologies, and never compromise on quality, performance, or developer experience.**

---

## Learn More

- **Official Website:** [https://platform.uno](https://platform.uno)
- **Documentation:** [https://platform.uno/docs](https://platform.uno/docs)
- **GitHub:** [https://github.com/unoplatform](https://github.com/unoplatform)
- **Community:** [https://discord.gg/eBHZSKG](https://discord.gg/eBHZSKG)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/platform-specific-csharp.md

---
uid: Uno.Development.PlatformSpecificCSharp
---

# Platform-specific C# code

Uno Platform allows you to reuse views and business logic across platforms. Sometimes though, you may want to write different code per platform. You may need to access platform-specific native APIs and 3rd-party libraries, or want your app to look and behave differently depending on the platform.

> [!Video https://www.youtube-nocookie.com/embed/WgKNG8Yjbc4]

This guide covers multiple approaches to managing per-platform code in C#. See [this guide for managing per-platform XAML](xref:Uno.Development.PlatformSpecificXaml).

## Project structure

There are multiple ways to restrict code or XAML markup to be used only on a specific platform:

* Use conditional code based on the `OperatingSystem.IsXXX` method
* Use [conditionals](https://learn.microsoft.com/dotnet/csharp/language-reference/preprocessor-directives/preprocessor-if) in a source file
* Place the code in a separate file which is only included in the desired platform.

The structure of an Uno Platform app created with the default Visual Studio template is [explained in more detail here](xref:Uno.Development.AppStructure).

### OperatingSystem.IsXXX

The Uno Platform templates differentiate platforms using the current target framework, yet it's possible to determine the running platform at runtime using:

```csharp
if (OperatingSystem.IsBrowser())
{
   // Do something WebAssembly specific
}
```

When building an application that uses the Skia renderer, it is generally best to use such conditionals in order to build for only one target framework in class libraries (e.g., when only targeting `net9.0`, without a platform specifier like `net9.0-ios`).

> [!NOTE]
> [JSImport/JSExport](xref:Uno.Wasm.Bootstrap.JSInterop) and [BrowserHtmlElement](xref:Uno.Interop.WasmJavaScript1) are available on all platforms targeting .NET 7 and later, and code using those APIs to be conditionally excluded at compile time, and should only use `OperatingSystem` conditions.

## `#if` conditionals

The most basic means of authoring platform-specific code is to use `#if` conditionals:

```csharp
#if __UNO__
Console.WriteLine("Uno Platform - Pixel-perfect WinUI apps that run everywhere");
#else
Console.WriteLine("Windows - Built with Microsoft's own tooling");
#endif
```

If the supplied condition is not met, e.g. if `__UNO__` is not defined, then the enclosed code will be ignored by the compiler.

The following conditional symbols are predefined for each Uno platform:

| Platform        | Symbol             | Remarks |
| --------------- | ------------------ | ------- |
| Android         | `__ANDROID__`      | |
| iOS             | `__IOS__`          | |
| tvOS            | `__TVOS__`         | |
| Catalyst        | `__MACCATALYST__`  | |
| iOS or tvOS or Catalyst | `__APPLE_UIKIT__` | |
| WebAssembly     | `__WASM__`         | Only available in the `net9.0-browserwasm` target framework, see [below](xref:Uno.Development.PlatformSpecificCSharp#webassembly-considerations) |
| Desktop         | `__DESKTOP__`      | Only available in the `net9.0-desktop` target framework. |
| Skia            | `__UNO_SKIA__`     | Only available with `SkiaRenderer` feature. |
| _Non-Windows_   | `__UNO__`          | To learn about symbols available when `__UNO__` is not present, see [below](xref:Uno.Development.PlatformSpecificCSharp#windows-specific-code) |

> [!TIP]
> Conditionals can be combined with boolean operators, e.g. `#if __ANDROID__ || __IOS__`. It is also possible to define custom conditional compilation symbols per project in the 'Build' tab in the project's properties.

### Windows-specific code

On `net9.0-windows10.0.xxxxx` target framework, an Uno Platform application isn't using Uno.UI at all. It's compiled using Microsoft's own tooling. For that reason, the `__UNO__` symbol is not defined on Windows. This aspect can optionally be leveraged to write code specifically intended for Uno.

Apps generated with the default `unoapp` solution template use **Windows App SDK** when targeting Windows. While this is the recommended path for new Windows apps, some solutions instead use **UWP** to target Windows. Both app models define a different conditional symbol:

| App model   | Symbol        | Remarks       |
| ----------- | ------------- | ------------- |
| Windows App SDK | `WINDOWS10_0_18362_0_OR_GREATER`  | Depending on the `TargetFramework` value, the _18362_ part may need adjustment |
| Universal Windows Platform         | `NETFX_CORE`  | No longer defined in new apps by default |

## Type aliases

Defining a [type alias](https://learn.microsoft.com/dotnet/csharp/language-reference/keywords/using-directive) with the `using` directive, in combination with `#if` conditionals, can make for cleaner code. For example:

```csharp
#if __ANDROID__
using _View = Android.Views.View;
#elif __IOS__
using _View = UIKit.UIView;
#else
using _View = Windows.UI.Xaml.UIElement;
#endif

...

public IEnumerable<_View> FindDescendants(FrameworkElement parent) => ...
```

## Partial class definitions

Heavy usage of `#if` conditionals in shared code makes it hard to read and comprehend. A better approach is to use [partial class definitions](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods) to split shared and platform-specific code.

Starting from Uno Platform 5.2, in project or class libraries using the `Uno.Sdk`, a set of implicit file name conventions can be used to target specific platforms:

* `*.wasm.cs` is built only for `net9.0-browserwasm`
* `*.desktop.cs` is built only for `net9.0-desktop`
* `*.iOS.cs` is built only for `net9.0-ios` and `net9.0-maccatalyst`
* `*.tvOS.cs` is built only for `net9.0-tvos`
* `*.UIKit.cs` is built only for `net9.0-ios` and `net9.0-maccatalyst` and `net9.0-tvos`
* `*.Apple.cs` is built only for `net9.0-ios` and `net9.0-maccatalyst` and `net9.0-tvos`
* `*.Android.cs` is built only for `net9.0-android`
* `*.WinAppSDK.cs` is built only for `net9.0-windows10` (eg. `net9.0-windows10.0.22621`)

In addition, for class libraries:

* `*.reference.cs` is built only for reference implementation
* `*.crossruntime.cs` is built for WebAssembly, Desktop, and reference implementation

> [!NOTE]
> For backwards compatibility, using `.skia.cs` is currently equivalent to `.desktop.cs`. This might change in the future, so we recommend using the suffixes above instead.

Using file name conventions allows for reducing the use of `#if` compiler directives.

### A simple example

Shared code in `PROJECTNAME/NativeWrapperControl.cs`:

```csharp
public partial class NativeWrapperControl : Control {

...

  protected override void OnApplyTemplate()
  {
    base.OnApplyTemplate();
   
      _nativeView = CreateNativeView();
  }
```

Platform-specific code in `PROJECTNAME/NativeWrapperControl.Android.cs`:

```csharp
#if __ANDROID__
public partial class NativeWrapperControl : Control {

...

  private View CreateNativeView() {
   ... //Android-specific code
  }
```

Platform-specific code in `PROJECTNAME/NativeWrapperControl.iOS.cs`:

```csharp
#if __IOS__
public partial class NativeWrapperControl : Control {

...

  private UIView CreateNativeView() {
   ... //iOS-specific code
  }
```

You can use [partial methods](https://learn.microsoft.com/dotnet/csharp/programming-guide/classes-and-structs/partial-classes-and-methods#partial-methods) when only one platform needs specialized logic.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/platform-specific-xaml.md

---
uid: Uno.Development.PlatformSpecificXaml
---

# Platform-specific XAML markup in Uno

Uno Platform allows you to reuse views and business logic across platforms. Sometimes, though, you may want to write different code per platform, either because you need to access platform-specific native APIs and 3rd-party libraries, or because you want your app to look and behave differently depending on the platform.

> [!Video https://www.youtube-nocookie.com/embed/IZt-ymNZpZw]

This guide covers multiple approaches to managing per-platform markup in XAML. See [this guide for managing per-platform C#](xref:Uno.Development.PlatformSpecificCSharp).

## Project structure

There are two ways to restrict code or XAML markup to be used only on a specific platform:

* Use conditionals within a shared file
* Place the code in a file that is only included in the desired target framework.

The structure of an Uno Platform app created with the default [Visual Studio template](https://marketplace.visualstudio.com/items?itemName=unoplatform.uno-platform-addin-2022) is [explained in more detail here](xref:Uno.Development.AppStructure).

## XAML conditional prefixes

The Uno platform uses pre-defined prefixes to include or exclude parts of XAML markup depending on the target framework being used. These prefixes can be applied to XAML objects or to individual object properties.

Conditional prefixes you wish to use in XAML files must be defined at the top of the file, like other XAML prefixes. They can then be applied to any object or property within the body of the file.

For prefixes which will be excluded on Windows (e.g. `android`, `ios`), the actual namespace is arbitrary, since the Uno parser ignores it. The prefix should be put in the `mc:Ignorable` list. For prefixes which will be included on Windows (e.g. `win`, `not_android`) the namespace should be `http://schemas.microsoft.com/winfx/2006/xaml/presentation` and the prefix should not be put in the `mc:Ignorable` list.

### Examples

#### Example 1

Using the following XAML:

```xml
<Page x:Class="HelloWorld.MainPage"
   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
   xmlns:android="http://uno.ui/android"
   xmlns:ios="http://uno.ui/ios"
   xmlns:wasm="http://uno.ui/wasm"
   xmlns:win="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:not_android="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
   xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
   mc:Ignorable="d android ios wasm">

 <StackPanel Margin="20,70,0,0">
  <TextBlock Text="This text will be large on Windows, and pink on WASM"
       win:FontSize="24"
       wasm:Foreground="DeepPink"
       TextWrapping="Wrap"/>
  <TextBlock android:Text="This version will be used on Android"
       not_android:Text="This version will be used on every other platform" />
  <ios:TextBlock Text="This TextBlock will only be created on iOS" />
 </StackPanel>
</Page>
```

Results in:

![Visual output](Assets/platform-specific-xaml.png)

In this example note how the properties `FontSize` and `Foreground` are selectively used based on platform. The `TextBlock` property `Text` also has two different values based on whether or not the app is running in Android. Finally, an entire `TextBlock` is added if the app is running in iOS. This shows:

 1. How certain properties can be used based on the platform
 2. How the values of certain properties can be changed based on the platform
 3. How entire controls can be added or removed for certain platforms

#### Example 2

Platform-specific XAML also allows you to exclude a parent element and all its children. This is especially useful for cases where children are already part of a namespace but need to be excluded on certain platforms.

Consider the following XAML which is using the Windows Community Toolkit's [Blur](https://learn.microsoft.com/windows/communitytoolkit/animations/blur) animation. While this runs for UWP, it is not currently supported in the Uno Platform and needs to be conditionally disabled. It isn't possible to add something like `<win:interactivity:Interaction.Behaviors>` to disable the behavior itself. Instead, the entire `Grid` is disabled on any platforms except Windows and child elements will be disabled along with it.

```xml
<Page x:Class="HelloWorld.MainPage"
   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
   xmlns:behaviors="using:Microsoft.Toolkit.Uwp.UI.Animations.Behaviors"
   xmlns:toolkit="using:Microsoft.Toolkit.Uwp.UI.Controls"
   xmlns:interactivity="using:Microsoft.Xaml.Interactivity"
   xmlns:win="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
   xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
   mc:Ignorable="d android ios wasm">

 <Grid>
  <win:Grid Background="Gray">
   <interactivity:Interaction.Behaviors>
    <behaviors:Blur Value="7" Duration="0" Delay="0" AutomaticallyStart="True" />
   </interactivity:Interaction.Behaviors>
  </win:Grid>
  <Grid>
   <!-- Other page content -->
  </Grid>
 </Grid>
</Page>
```

### Available prefixes

The pre-defined prefixes are listed below:

> [!NOTE]
> Skia in the context of this table refers to all Skia targets, including when Android, iOS, or Wasm are running with Skia rendering.
>
> [!NOTE]
> Unless explicitly stated, Android, iOS, and web in the context of this table refer specifically to the old native platforms and not when running with Skia rendering.

| Prefix            | Included platforms                             | Excluded platforms                   | Namespace                                                   | Put in `mc:Ignorable`? |
|-------------------|------------------------------------------------|--------------------------------------|-------------------------------------------------------------|------------------------|
| `win`             | WinUI                                          | Android, iOS, web, macOS, Skia       | `http://schemas.microsoft.com/winfx/2006/xaml/presentation` | no                     |
| `not_win`         | Android, iOS, web, macOS, Skia                 | WinUI                                | `http://uno.ui/not_win`                                     | yes                    |
| `android`         | Android                                        | WinUI, iOS, web, macOS, Skia         | `http://uno.ui/android`                                     | yes                    |
| `ios`             | iOS                                            | WinUI, Android, web, macOS, Skia     | `http://uno.ui/ios`                                         | yes                    |
| `wasm`            | web                                            | WinUI, Android, iOS, macOS, Skia     | `http://uno.ui/wasm`                                        | yes                    |
| `macos`           | macOS                                          | WinUI, Android, iOS, web, Skia       | `http://uno.ui/macos`                                       | yes                    |
| `skia`            | Skia                                           | WinUI, Android, iOS, web, macOS      | `http://uno.ui/skia`                                        | yes                    |
| `androidskia`     | Android running with Skia rendering            | Everything else                      | `http://uno.ui/androidskia`                                 | yes                    |
| `iosskia`         | iOS running with Skia rendering                | Everything else                      | `http://uno.ui/iosskia`                                     | yes                    |
| `wasmskia`        | Web running with Skia rendering                | Everything else                      | `http://uno.ui/wasmskia`                                    | yes                    |
| `not_android`     | WinUI, iOS, web, macOS, Skia                   | Android                              | `http://schemas.microsoft.com/winfx/2006/xaml/presentation` | no                     |
| `not_ios`         | WinUI, Android, web, macOS, Skia               | iOS                                  | `http://schemas.microsoft.com/winfx/2006/xaml/presentation` | no                     |
| `not_wasm`        | WinUI, Android, iOS, macOS, Skia               | web                                  | `http://schemas.microsoft.com/winfx/2006/xaml/presentation` | no                     |
| `not_macos`       | WinUI, Android, iOS, web, Skia                 | macOS                                | `http://schemas.microsoft.com/winfx/2006/xaml/presentation` | no                     |
| `not_skia`        | WinUI, Android, iOS, web, macOS                | Skia                                 | `http://schemas.microsoft.com/winfx/2006/xaml/presentation` | no                     |
| `not_androidskia` | All except Android running with Skia rendering | Android running with Skia rendering  | `http://schemas.microsoft.com/winfx/2006/xaml/presentation` | no                     |
| `not_iosskia`     | All except iOS running with Skia rendering     | iOS running with Skia rendering      | `http://schemas.microsoft.com/winfx/2006/xaml/presentation` | no                     |
| `not_wasmskia`    | All except web running with Skia rendering     | web running with Skia rendering      | `http://schemas.microsoft.com/winfx/2006/xaml/presentation` | no                     |

More visually, platform support for the pre-defined prefixes is shown in the below table:

| Prefix        |  Windows  | Android |  iOS  |  Web  | macOS | Skia  |
|---------------|-------|-------|-------|-------|-------|-------|
| `win`         | ✔ | ✖ | ✖ | ✖ | ✖ | ✖ |
| `android`     | ✖ | ✔ | ✖ | ✖ | ✖ | ✖ |
| `ios`         | ✖ | ✖ | ✔ | ✖ | ✖ | ✖ |
| `wasm`        | ✖ | ✖ | ✖ | ✔ | ✖ | ✖ |
| `macos`       | ✖ | ✖ | ✖ | ✖ | ✔ | ✖ |
| `skia`        | ✖ | ✖ | ✖ | ✖ | ✖ | ✔ |
| `not_win`     | ✖ | ✔ | ✔ | ✔ | ✔ | ✔ |
| `not_android` | ✔ | ✖ | ✔ | ✔ | ✔ | ✔ |
| `not_ios`     | ✔ | ✔ | ✖ | ✔ | ✔ | ✔ |
| `not_wasm`    | ✔ | ✔ | ✔ | ✖ | ✔ | ✔ |
| `not_macos`   | ✔ | ✔ | ✔ | ✔ | ✖ | ✔ |
| `not_skia`    | ✔ | ✔ | ✔ | ✔ | ✔ | ✖ |

### XAML prefixes in cross-targeted libraries

For Uno Platform 6.0 and above, XAML prefixes behave differently in class libraries than when used directly in application code. Specifically, it isn't possible to distinguish Skia and Wasm/Native in a library, since both platforms use the `net9.0`/`net10.0` target. The `wasm` and `skia` prefixes will always evaluate to false inside of a library.

The prefix `netstdref` is available and will include the objects or properties in both Skia and Wasm builds. A prefix `not_nestdref` can also be used to exclude them. Since Skia and Wasm/Native are similar, it is often not necessary to make the distinction.

In cases where it is needed (fonts are one example), the XAML files must be placed directly in the app project.

| Prefix          | Namespace                                                   | Put in `mc:Ignorable`? |
|-----------------|-------------------------------------------------------------|------------------------|
| `netstdref`     | `http://uno.ui/netstdref`                                   | yes                    |
| `not_netstdref` | `http://uno.ui/not_netstdref`                               | yes                    |

### Specifying namespaces

Specifying CLR namespaces in platform specific XAML namespace can be done as follows:

```xml
<Page x:Class="HelloWorld.MainPage"
   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   ...
   xmlns:android="http://uno.ui/android#using:My.Custom.Namespace1;My.Custom.Namespace2"
   ...
   mc:Ignorable="d android">
 <android:MyCustomType />
```

In this example, types prefixed in the `android` XAML namespace will be looked up in `My.Custom.Namespace1`, `MyCustomNamespace2` then in all the namespaces defined in default namespace `http://schemas.microsoft.com/winfx/2006/xaml/presentation`.

> [!NOTE]
> When using Uno Platform 4.x and in the absence of CLR namespace specification (using the `#using:` prefix), type matching is done through partial name based matching, without using the namespace information. In Uno Platform 4.8, this partial matching can be controlled by the `UnoEnableXamlFuzzyMatching` msbuild property. Uno Platform 5.0 and later will be setting `UnoEnableXamlFuzzyMatching` to `false` by default and will force explicit type matching.

## XAML Conditional Methods

You can use standard WinUI conditional XAML prefixes with Uno Platform, [as documented here](https://learn.microsoft.com/windows/uwp/debug-test-perf/conditional-xaml).

Currently the following conditional methods are supported:

* IsApiContractPresent(ContractName, VersionNumber)
* IsApiContractNotPresent(ContractName, VersionNumber)
* IsTypePresent(ControlType)
* IsTypeNotPresent(ControlType)

### IsApiContractPresent

The following `ContractName` values are currently supported:

* **"Windows.Foundation.UniversalApiContract"**: resolves to `true` if `VersionNumber` is 10 or below, and `false` otherwise.
* **"Uno.WinUI"**: resolves to `true` if the [`Uno.WinUI` NuGet package](updating-to-winui3.md) (ie the WinUI 3 API mapping) is in use, `false` if the `Uno.UI` NuGet package is in use.

All other contract names will resolve to false.

### IsTypePresent

`IsTypePresent()` will resolve to true if the type is found **and** it isn't marked with the `[NotImplemented]` attribute. This is useful for conditionally enabling XAML in a more declarative way, instead of referring to specific platforms.

#### Limitations in cross-targeted libraries

`IsTypePresent()` is resolved at compile time. In a cross-targeted library, this means that for WebAssembly and Skia, it doesn't use the correct implementation status for those platforms, but instead uses the implementation status reported by the 'reference' Uno.UI .NET Standard 2.0 assembly. Therefore it may report an incorrect status for WebAssembly and/or Skia inside of a cross-targeted library.

### Example

The following example uses `IsTypePresent` to use WebView to display content on platforms where it's available, and a custom control to display the content on platforms where WebView isn't supported:

```xml
<Page x:Class="HelloWorld.MainPage"
   xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
   xmlns:local="using:HelloWorld"
   xmlns:webviewpresent="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsTypePresent(Windows.UI.Xaml.Controls.WebView)"
   xmlns:webviewnotpresent="http://schemas.microsoft.com/winfx/2006/xaml/presentation?IsTypeNotPresent(Windows.UI.Xaml.Controls.WebView)"
   xmlns:local_webviewnotpresent="using:HelloWorld?IsTypeNotPresent(Windows.UI.Xaml.Controls.WebView)"
   xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
   xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
   mc:Ignorable="d">

 <Grid>
  <webviewpresent:WebView Source="{Binding DisplayContent}" />
  <local_webviewnotpresent:WebViewSubstitute ContentSource="{Binding DisplayContent}" />
  <webviewnotpresent:TextBlock VerticalAlignment="Bottom" Text="Showing substitute for WebView">
 </Grid>
</Page>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/pointers-keyboard-and-other-user-inputs.md

---
uid: Uno.Features.UserInputs
---

# Uno support for user inputs

## Supported user inputs

User inputs are usually propagated using `RoutedEvents`. See Uno's [routed events documentation](routed-events.md) to better understand their implementation on Uno.

| Routed Event                  | Android | iOS     | Wasm    | Skia Desktop |     |
| ----------------------------- | ------- | ---------------- | ------- | ------------ | --- |
| **_focus events_**
| `GotFocus`                    | Yes     | Yes (1)          | Yes (1) | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.gotfocus) |
| `LostFocus`                   | Yes     | Yes (1)          | Yes (1) | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.lostfocus) |
| **_keyboard events_**
| `KeyDown`           | Hardware Only (2) | Yes (2)          | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.keydown) |
| `KeyUp`             | Hardware Only (2) | Yes (2)          | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.keyup) |
| **_pointer events_**
| `PointerCanceled`             | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointercanceled) |
| `PointerCaptureLost`          | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointercapturelost) |
| `PointerEntered`              | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerentered) |
| `PointerExited`               | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerexited) |
| `PointerMoved`                | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointermoved) |
| `PointerPressed`              | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerpressed) |
| `PointerReleased`             | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerreleased) |
| `PointerWheelChanged`         | No      | No               | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.pointerwheelchanged) |
| **_manipulation events_**
| `ManipulationStarting`        | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.manipulationstarting) |
| `ManipulationStarted`         | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.manipulationstarted) |
| `ManipulationDelta`           | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.manipulationdelta) |
| `ManipulationInertiaStarting` | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.manipulationinertiastarting) |
| `ManipulationCompleted`       | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.manipulationcompleted) |
| **_gesture events_**
| `Tapped`                      | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.tapped) |
| `DoubleTapped`                | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.doubletapped) |
| `RightTapped`                 | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.righttapped) |
| `Holding`                     | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.holding) |
| **_drag and drop_**
| `DragStarting`                | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dragstarting) |
| `DragEnter`                   | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dragenter) |
| `DragOver`                    | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dragover) |
| `DragLeave`                   | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dragleave) |
| `Drop`                        | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.drop) |
| `DropCompleted`               | Yes     | Yes              | Yes     | Yes          | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.uielement.dropcompleted) |

Notes:

1. **Focus** events:
   * **iOS**: The concept of _focus_ is emulated because it's not supported by the platform, so this event is
     always bubbling in managed code.
   * **Wasm**: Current implementation is not totally reliable and doesn't support _lost focus_ most of the time.
2. **Keyboard** events:
   * **Android**: `KeyDown` and `KeyUp` events are **generated only from hardware keyboards** (Except for the _Editor Action_ on _soft keyboards_,
     those are translated as `KeyUp` with `KeyCode.Enter`). Some soft keyboard **MAY** generate those events, but your code shouldn't rely
     on that. This is a limitation [in the Android platform](https://developer.android.com/training/keyboard-input/commands) (see note on this link content).
     > Because of those limitations, _Key Events_ are not being implemented as _routed events_ on Android, so `AddHandler` & `RemoveHandler`
     > won't work for keyboard events. **They won't bubble in managed code**.
   * **iOS**: `KeyDown` & `KeyUp` routed events are generated from only a `TextBox`. Only character-related keyboard events are generated.
     They are implemented as _Routed Events_ and they are **always bubbling in managed code**.
   * **Skia**: Keyboard events are supported from `CoreWindow.KeyUp` and `CoreWindow.KeyDown` events, as well as `UIElement.KeyUp` and `UIElement.KeyDown` events for Skia Desktop.

## Pointer Events

These events are the base for all other pointing device related events (i.e. Manipulation, Gesture and drag and dop events).
They are directly linked to the native events of each platform:

* `Touches[Began|Moved|Ended|Cancelled]` on iOS
* `dispatchTouchEvent` and `dispatchGenericMotionEvent` on Android
* `pointer[enter|leave|down|up|move|cancel]` on WebAssembly

On Skia however, they are fully managed events.

### Pointers events and the ScrollViewer

Like on WinUI, as soon as the system detects that the user wants to scroll, a control gets a `PointerCancelled` and that control won't receive
any other pointer event until the user releases the pointer. That behavior can be prevented by setting the `ManipulationMode`
to something other than `System` on a control nested in the `ScrollViewer`. For more information, see [Manipulation events](#manipulation-events).

Be aware that on iOS, this will set `DelaysContentTouches` to `false`. So, it means that it will slightly reduce the performance
of the scrolling. For more information, see [`delaysContentTouches`](https://developer.apple.com/documentation/uikit/uiscrollview/1619398-delayscontenttouches).

### Known limitations for pointer events

As those events are tightly coupled to the native events, Uno has to make some compromises:

* On iOS, when tapping with a mouse or a pen on Android, or in a few other specific cases (like `PointerCaptureLost`),
  multiple managed events are raised from a single native event. These have multiple effects:
  * On WinUI if you have a control A and a nested control B, you will get:

    ```output
    B.PointerEnter
    A.PointerEnter
    B.PointerPressed
    A.PointerPressed
    ```

    but with UNO you will get:

    ```output
    B.PointerEnter
    B.PointerPressed
    A.PointerEnter
    A.PointerPressed
    ```

  * If you handle the `PointerEnter` on **B**, the parent control **A** won't get the `PointerEnter` (as expected) nor the  `PointerPressed`.
* On Android with a mouse or a pen, the `PointerEnter` and `PointerExit` are going to be raised without taking clipping in consideration.
  This means that you will get the enter earlier and the exit later than on other platforms.
* On Android if you have an element with a `RenderTransform` which overlaps one of its sibling elements,
  the element at the top will get the pointer events.
* On WASM, iOS, and Android, the `RoutedPointerEventArgs.FrameId` will be reset to 0 after 49 days of running time of the application.
* Unlike on WinUI, controls that are under a `Popup` won't receive the unhandled pointer events.
* On non-Skia-based platforms, unlike WinUI, it's impossible to receive a `PointerReleased` without getting a `PointerPressed` before.
  (For instance if a child control handled the pressed event but not the released event).
  > On WASM as `TextElement` inherits from `UIElement`, it means that, unlike WinUI, `TextBlock` won't raise the
  > `PointerReleased` event when clicking on a `Hyperlink`.
* Unlike WinUI, on the `Hyperlink` the `Click` will be raised before the `PointerReleased`.
* The property `PointerPointProperties.PointerUpdateKind` is not set on Android 5.x and lower (API level < 23)
* On Firefox, pressed pointers are reported as fingers. This means you will receive events with `PointerDeviceType == Pen` only for hovering
  (i.e. `Pointer<Enter|Move|Exit>` - note that, as of 2019-11-28, once pressed `PointerMove` will be flagged as "touch")
  and you won't be able to track the barrel button nor the eraser. For more information, see [Bug report on Bugzilla](https://bugzilla.mozilla.org/show_bug.cgi?id=1449660).
* On WASM, if you touch the screen with the pen **then** you press the barrel button (still while touching the screen), the pointer events will
  have the `IsRightButtonPressed` set (in addition to the `IsBarrelButtonPressed`). On WinUI and Android, you get this flag only if the barrel
  button was pressed at the moment where you touched the screen, otherwise, you will have the `IsLeftButtonPressed` and the `IsBarrelButtonPressed`.
* For pen and fingers, the `Holding` event is not raised after a given delay like on WinUI,
  but instead, we rely on the fact that we usually get a lot of moves for those kinds of pointers,
  so we raise the event only when we get a move that exceeds the defined thresholds for holding.
* On WASM, Shapes must have a non-null Fill to receive pointer events (setting the Stroke is not sufficient).
* On WASM, if the user scrolls diagonally (e.g. with a Touchpad), but you mark as `Handled` pointer events only for vertical scrolling,
  then the events for the horizontal scroll component won't bubble through the parents.

### Pointer capture

The capture of pointer is handled in managed code only. On WebAssembly, Uno however still requests the browser to capture the pointer,
but Uno does not rely on native `[got|lost]pointercapture` events.

### iPadOS mouse support

To differentiate between mouse and touch device type for pointer events, include the following in your app's `Info.plist`:

```xml
  <key>UIApplicationSupportsIndirectInputEvents</key>
  <true/>
```

Without this key, the current version of iPadOS reports mouse interaction as normal touch.

## Manipulation Events

They are generated from the PointerXXX events (using the `Microsoft.UI.Input.GestureRecognizer`) and are bubbling in managed only.

## Gesture Events

They are generated from the PointerXXX events (using the `Microsoft.UI.Input.GestureRecognizer`) and are bubbling in managed only.

Note that `Tapped` and `DoubleTapped` are not linked in any way to a native equivalent, but are fully interpreted in managed code.

In order to match the WinUI behavior, on WASM, the default "Context menu" of the browser is disabled (except for the `TextBox`),
no matter if you use/handle the `RightTapped` event or not.
Be aware that on some browsers (Firefox for example), the user can still request to get the "Context menu" on right click.

### Disabling browser context menu on `<input>-based` elements

While the browser context menu enabled on `TextBox` and `PasswordBox` by default, it will be disabled when `ContextFlyout` is set on the control.

To manually disable the context menu on a `UIElement` which represents a HTML `<input>`, you can manually set the `context-menu-disabled` CSS class:

```csharp
#if __WASM__

MyInputElement.SetCssClasses("context-menu-disabled");
#endif
```

## Drag and drop

Those events are also 100% managed events, built from the PointerXXX events (using the `Microsoft.UI.Input.GestureRecognizer`)

### Inter-app drag and drop support

A _drag and drop_ operation can be used to move content within an app, but it can also be used to **copy** / **move** / **link** between apps.
While intra-app _drag and drop_ is supported on all platforms without limitations, inter-app _drag and drop_ requires platform-specific support.
The table and sections below describe supported functionality and limitations for each platform.

|                       | From uno app to external                         | From external app to uno                        |
| --------------------- | ------------------------------------------------ | ------------------------                        |
| Android               | No                                               | No                                              |
| iOS                   | No                                               | No                                              |
| Wasm                  | No                                               | Yes (Text, Link, Image, File, Html, Rtf)        |
| macOS                 | Yes (Text, Link, Image, Html, Rtf)               | Yes (Text, Link, Image, File, Html, Rtf)        |
| Skia Desktop (Windows) | Yes (Text, Link, Image, File, Html, Rtf)         | Yes (Text, Link, Image, File, Html, Rtf)        |
| Skia Linux            | No                                               | No                                              |

* "Link" may refer to WebLink, ApplicationLink, or Uri formats

#### Wasm Limitations

1. When dragging content from external app to uno, you cannot retrieve the content from the `DataPackage` before the `Drop` event.
   This a limitations of web browsers.
   Any attempt to read it before the `Drop` will result into a timeout exception after a hard coded delay of 10 seconds.
2. When dragging some uris from external app to uno, only the first uri will be accessible through the **WebLink** standard format ID.

#### macOS Limitations

1. Dragging a File (StorageItem) from an Uno Platform App to an external destination is not currently supported.
2. When receiving a drop within an Uno Platform App from an external source, key modifiers are not supported

#### Skia Limitations

1. There is no standard type for **WebLink** (nor **ApplicationLink**) on this platform.
   They are copied to the external app as raw **Text**, and converted back as **WebLink** or **ApplicationLink** from raw text from the external app
   when [`Uri.IsWellFormedUriString(text, UriKind.Absolute)`](https://learn.microsoft.com/dotnet/api/system.uri.iswellformeduristring) returns true.
2. The image content seems to not be readable by common apps, only another Uno app can read it properly.

### Drag and Drop Data Format Considerations

WinUI has the following standard data formats that correspond with a URI/URL:

1. Uri, now deprecated in favor of:
2. WebLink and
3. ApplicationLink

Several platforms such as macOS, iOS, and Android do not differentiate between them and only use a single URI/URL class or string.

When applying data to the native clipboard or dragging/dropping data from a DataPackage, only one URI/URL may be used. Therefore, all URI data formats are merged together into a single URI using the above-defined priority. WebLink is considered more specific than ApplicationLink.

When pulling data from the native clipboard or drag/drop data, this single native URI/URL is separated into the equivalent WinUI data format (since WinUI's direct equivalent standard data format 'Uri' is deprecated). The mapping is as follows:

1. WebLink is used if the given URL/URI has a scheme of "http" or "https"
2. ApplicationLink is used if not #1

For full compatibility, the Uri format within a DataPackage should still be populated regardless of #1 or #2.

### Known issues for drag and drop events

1. If you have 2 nested drop targets (i.e. element flagged with `AllowDrop = true`),
   when the pointer leaves the deepest / top most element but not the parent,
   the parent element will also raise `DragLeave` and immediately after raise `DragEnter`.
1. On WinUI, the default UI will include a tooltip that indicates the accepted drop action,
   and a "screenshot" of the dragged element.
   Currently, Uno will display only the tooltip.
1. The accepted drop action displayed in the tooltip is not localized.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/profiling-applications.md

---
uid: Uno.Tutorials.ProfilingApplications
---

# Profiling Uno Platform Applications

## Profiling .NET Android/iOS applications

.NET provides the ability to do CPU profiling through [`dotnet-trace`](https://learn.microsoft.com/dotnet/core/diagnostics/dotnet-trace) for iOS and Android applications.

### Pre-requisites

Run the following commands

- `dotnet tool update -g dotnet-dsrouter`
- `dotnet tool update -g dotnet-trace`
- `dotnet tool update -g dotnet-gcdump`

## Profiling .NET iOS applications

> [!NOTE]
> This documentation is based on [.NET iOS profiling](https://github.com/xamarin/xamarin-macios/wiki/Profiling) and [.NET Android profiling](https://github.com/dotnet/android/blob/main/Documentation/guides/tracing.md) documentation.

Profiling iOS apps needs to be done on a mac machine.

First, create an alias to `mlaunch`:

```bash
cd [your-folder-with-the-csproj]
alias mlaunch=$(dotnet build -getProperty:MlaunchPath *.csproj -f net9.0-ios)
```

### Profiling on an iOS Simulator

1. Build the app with the following parameters:

    ```dotnetcli
    cd [your-folder-with-the-csproj]
    dotnet build -f net10.0-ios -p:DiagnosticAddress=127.0.0.1 -p:DiagnosticPort=9000 -p:DiagnosticSuspend=true -p:DiagnosticListenMode=listen
    ```

1. Find the simulator you want to run on:

    ```dotnetcli
    $ xcrun simctl list devices
    ```

    Find a device that is shutdown or booted, and take note of its UDID.

1. Launch the app (it will be paused on startup waiting for the .NET tooling to connect):

    ```bash
    mlaunch --device :v2:udid=xxxxxxxx-yyyy-zzzz-aaaa-bbbbbbbbbbbb --wait-for-exit --stdout=$(tty) --stderr=$(tty) --launchsim=[your-app-path]/bin/Debug/net*-ios/*/*.app
    ```

    Replace the UDID with the one you found above.

1. Once the app is waiting, go ahead and start profiling:

    ```dotnetcli
    dotnet-trace collect --dsrouter ios-sim --format speedscope
    ```

1. Optionally take a GC dump:

    ```dotnetcli
    dotnet-gcdump collect --dsrouter ios-sim
    ```

### Profiling on a physical iOS device

1. Build the app with the following parameters:

    ```dotnetcli
    cd [your-folder-with-the-csproj]
    dotnet build -f net10.0-ios -p:DiagnosticAddress=127.0.0.1 -p:DiagnosticPort=9000 -p:DiagnosticSuspend=true -p:DiagnosticListenMode=listen
    ```

1. Install & launch the app:

    ```bash
    mlaunch --installdev bin/Debug/net*/*/*.app --devname ... 
    mlaunch --launchdev bin/Debug/net*/*/*.app --devname ... --wait-for-exit
    ```

1. Start CPU profiling:

    ```dotnetcli
    dotnet-trace collect --dsrouter ios --format speedscope
    ```

1. Optionally take a GC dump:

    ```dotnetcli
    dotnet-gcdump collect --dsrouter ios
    ```

## Profiling on Android

### Enable profiling in your application

In `Platforms/Android/environment.conf`, add **one** of the following lines:

- For devices:

    ```text
    DOTNET_DiagnosticPorts=127.0.0.1:9000,suspend,connect
    ```

- For emulators:

    ```text
    DOTNET_DiagnosticPorts=10.0.2.2:9000,suspend,connect
    ```

The `suspend` directive means that the application will wait for `dotnet-trace` connections before starting, `nosuspend` may also be used.

### Profiling the application

- Start the diagnostics router:

  - For devices, run `adb reverse tcp:9000 tcp:9001` then `dotnet-dsrouter android -v debug`

  - For emulators, run `dotnet-dsrouter android-emu -v debug`

- Run `dotnet-trace`, in the folder where you want your traces to be stored, using the **PID** provided by the `dotnet-dsrouter` output:

    ```dotnetcli
    dotnet-trace collect -p PID --format speedscope
    ```

- Start the `x64` emulator or the `arm64` device
    > Running on a 32 bits device is not supported and will generate unusable traces in SpeedScope

- Build the application with profiling enabled

    ```dotnetcli
    dotnet build -c Release -f net9.0-android -r android-arm64 -t:Run -p:AndroidEnableProfiler=true
    ```

  Use `-r android-x64` for emulators instead.

- The app will start and `dotnet-trace` will display a MB number counting up

- Use the app, once done, stop `dotnet-trace` by pressing `Enter` or `Ctrl+C`

- Open a browser at `https://speedscope.app` and drop the `*.speedscope.json` file in it

### Analyzing the trace data

This section provides insights into what to look for when analyzing flame charts.

- When building without AOT, a lot of the startup traces will show time spent in `System.Private.CoreLib!System.Runtime.CompilerServices.RuntimeHelpers.CompileMethod(object)`, indicating that that the JIT is doing a lot of work. This can make performance improvements harder to find.
- When building with AOT, most of the IL is compiled to native code with some exceptions. You may still find `RuntimeHelpers.CompileMethod` invocations. In such cases, you may need to find what is causing the AOT compiler to skip IL portions. If the JIT still impacts cold paths of your application, you may still need to adjust your code to avoid the JIT. For instance, some generics constructs force the AOT compiler to still use JITing. In other cases, it could be accessing static-type members. The JIT conditions are runtime version dependent, and [looking at the runtime code](https://github.com/dotnet/runtime/blob/9703660baa08914773b26e413e361c8ce04e6d94/src/mono/mono/mini/aot-compiler.c) can help to find out which ones.
- Some of the time is spent in the .NET Android binding framework (e.g. `Android.Runtime.JNIEnv` or `Java.Interop.TypeManager`), operations that cannot be adjusted by the application. One change to consider is to reduce the native code invocations to a strict minimum, where impactful.

## Analyzing GC memory dumps

You can analyze the GC memory `.gcdump` files using the [Visual Studio 2022/2026 memory profiler](https://learn.microsoft.com/en-us/visualstudio/profiling/memory-usage-without-debugging2?view=visualstudio&pivots=programming-language-dotnet#managed-types-reports) by using the File / Open menu and navigating the results.

## Profiling Skia Desktop applications

Profiling Skia-based Uno Platform targets can be done on Windows in Visual Studio 2019 and 2022 using [time and memory profilers](https://learn.microsoft.com/visualstudio/profiling/profiling-feature-tour?view=vs-2019).

## Profiling WebAssembly applications with runtime diagnostics

As of Dotnet 10.0, runtime diagnostics like performance traces and GC dumps can be collected by calling some Javascript methods exposed by the Dotnet runtime. For more details, see the [dotnet 10.0 release notes](https://github.com/dotnet/core/blob/main/release-notes/10.0/preview/preview4/aspnetcore.md#blazor-webassembly-runtime-diagnostics)

## Profiling WebAssembly applications with the browser's DevTools

Profiling WebAssembly applications can be done through the use of AOT compilation, and [browsers' performance tab](https://developer.chrome.com/docs/devtools/evaluate-performance/).

### Setup the WebAssembly application for profiling

- Enable emcc profiling:

    ```xml
    <PropertyGroup>
        <WasmShellEnableEmccProfiling>true</WasmShellEnableEmccProfiling>
    </PropertyGroup>
    ```

- Enable AOT compilation:

    ```xml
    <PropertyGroup>
        <WasmShellMonoRuntimeExecutionMode>InterpreterAndAOT</WasmShellMonoRuntimeExecutionMode>
    </PropertyGroup>
    ```

- Build and deploy the application
- Open the `Performance` tab in your browser
- Use your application or restart your application while recording the trace

### Troubleshooting

- Deep traces found in large async code patterns or complex UI trees may hit [this chromium issue](https://bugs.chromium.org/p/chromium/issues/detail?id=1206709). This generally makes traces very long to load; you'll need to be patient.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/progressring.md

---
uid: Uno.Features.ProgressRing
---

# ProgressRing

## [**WinUI**](#tab/winui)

![MUX `ProgressRing`](../Assets/features/progressring/muxprogressring.png)

This version comes with [WinUI 2.x and WinUI 3](https://learn.microsoft.com/windows/apps/winui/winui2/release-notes/winui-2.4#progressring) and is using an `<AnimatedVisualPlayer />` in its Control Template to display Lottie-based animations.

> [!IMPORTANT]
> To use this Control, you must add a [reference the Lottie package](xref:Uno.Features.Lottie) in your projects, or the ring will not be displayed.

## [**UWP**](#tab/uwp)

![WUX `ProgressRing`](../Assets/features/progressring/wuxprogressring.png)

This control works on all platforms and uses the native progress ring control by default, with the exception of Wasm where there is no native progress ring control.

> [!NOTE]
> In WinUI-based Uno Platform apps, this control is in the `Uno.UI.Controls.Legacy` namespace instead. It is still available as part of Uno Platform 5.x for its support of native styling.

On Android and iOS, the WUX `ProgressRing` uses native controls by default (`UIActivityIndicatorView` on iOS and `ProgressBar` on Android). To use the UWP rendering on these targets, you can explicitly apply the `DefaultWuxProgressRingStyle` Style:

```xaml
<ProgressRing Style="{StaticResource DefaultWuxProgressRingStyle}" />
```

To use the MUX `ProgressRing` on non-Skia targets and WUX `ProgressRing` on Skia targets you can utilize platform-specific XAML syntax:

```xaml
<Page
   ...
   mux="using:Microsoft.UI.Xaml.Controls"
   not_skia="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
   skia="http://uno.ui/skia"
   mc:Ignorable="d skia">
   <Grid>
      <skia:Border>
        <ProgressRing />
      </skia:Border>
      <not_skia:Border>
        <mux:ProgressRing />
      </not_skia:Border>
   </Grid>
</Page>
```

---

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/protocol-activation.md

---
uid: Uno.Features.ProtocolActivation
---

# Custom protocol activation

## Registering custom scheme

### iOS & macOS

Declare your custom URL scheme in `info.plist` in the platform head:

```xml
<key>CFBundleURLTypes</key>
<array>
    <dict>
    <key>CFBundleURLName</key>
    <string>My Useful Scheme</string>
    <key>CFBundleURLSchemes</key>
    <array>
        <string>my-scheme</string>
    </array>
    </dict>
</array>
```

### Android

Register your protocol on the `MainActivity` with the `[IntentFilter]` attribute:

```csharp
[IntentFilter(
    new [] {
        Android.Content.Intent.ActionView
    },
    Categories = new[] {
        Android.Content.Intent.CategoryDefault,
        Android.Content.Intent.CategoryBrowsable
    },
    DataScheme = "my-scheme")]
```

If your target framework is Android 12, you must also add `Exported = true` to the `[Activity]` attribute.

`CategoryDefault` is required (must be included for all implicit intents) and `CategoryBrowsable` is optional (allows opening the custom URI from the browser).

### WASM

WASM implementation uses the [`Navigator.registerProtocolHandler` API](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/registerProtocolHandler).

This has several limitations when using a custom scheme:

- The custom scheme's name must begin with `web+`
- The custom scheme's name must include at least 1 letter after the `web+` prefix
- The custom scheme must have only lowercase ASCII letters in its name.

You can also use one of the following supported schemes instead:

- `bitcoin`
- `ftp`
- `ftps`
- `geo`
- `im`
- `irc`
- `ircs`
- `magnet`
- `mailto`
- `matrix`
- `mms`
- `news`
- `nntp`
- `openpgp4fpr`
- `sftp`
- `sip`
- `sms`
- `smsto`
- `ssh`
- `tel`
- `urn`
- `webcal`
- `wtai`
- `xmpp`

To register the custom theme, call the WASM-specific `Uno.Helpers.ProtocolActivation` API when appropriate to let the user confirm URI handler association:

```csharp
#if __WASM__
   Uno.Helpers.ProtocolActivation.RegisterCustomScheme(
      "web+myscheme",
      new System.Uri("http://localhost:55838/"), 
      "Can we handle web+myscheme links?");
#endif
```

The first argument is the scheme name, the second is the base URL of your application (it must match the current domain to be registered successfully), and the third is a text prompt, which will be displayed to the user to ask for permission (this does not work on all browsers e.g. edge).

When a link with the custom scheme gets executed, the browser will navigate to the URL with an additional `unoprotocolactivation` query string key, which will contain the custom URI. Uno internally recognizes this query string key and executes `OnActivated` appropriately.

### WinUI

Works according to Windows docs. For more information, see [Handle URI activation | Microsoft Docs](https://learn.microsoft.com/windows/uwp/launch-resume/handle-uri-activation).

## Handling protocol activation

Custom URI activation can be handled by overriding the `OnActivated` method in `App.cs` or `App.xaml.cs`:

```csharp
protected override void OnActivated(IActivatedEventArgs e)
{
    // Note: Ensure the root frame is created
    
    if (e.Kind == ActivationKind.Protocol)
    {
        var protocolActivatedEventArgs = (ProtocolActivatedEventArgs)e;
        var uri = protocolActivatedEventArgs.Uri;
        // do something
    }
}
```

Note that in line with WinUI, if the application is not running, the `OnLaunched` method is not called and only `OnActivated` is executed instead. You must perform a similar initialization of the root app frame and activate the current `Window` at the end. If the application is running, this initialization can be skipped.

A full application lifecycle handling with shared logic between `OnLaunched` and `OnActivated` could look as follows:

```csharp
protected override void OnLaunched(LaunchActivatedEventArgs e)
{
    var rootFrame = GetOrCreateRootFrame(e);
    if (e.PrelaunchActivated == false)
    {
        if (rootFrame.Content == null)
        {
            rootFrame.Navigate(typeof(MainPage), e.Arguments);
        }
        Window.Current.Activate();
    }
}

protected override void OnActivated(IActivatedEventArgs args)
{
    var rootFrame = GetOrCreateRootFrame(args);
    if (args.Kind == ActivationKind.Protocol)
    {
        var protocolActivatedEventArgs = (ProtocolActivatedEventArgs)args;
        var uri = protocolActivatedEventArgs.Uri;

        rootFrame.Navigate(typeof(DetailPage), uri.AbsoluteUri);
        Window.Current.Activate();
    }
}

private Frame GetOrCreateRootFrame(IActivatedEventArgs eventArgs)
{
    var rootFrame = Window.Current.Content as Frame;

    if (rootFrame == null)
    {
        rootFrame = new Frame();
        rootFrame.NavigationFailed += OnNavigationFailed;

        if (eventArgs.PreviousExecutionState == ApplicationExecutionState.Terminated)
        {
            // Load state from previously suspended application
        }

        Window.Current.Content = rootFrame;
    }

    return rootFrame;
}
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/proximity-sensor.md

---
uid: Uno.Features.ProximitySensor
---

# Proximity sensor

> [!TIP]
> This article covers Uno-specific information for `ProximitySensor`. For a full description of the feature and instructions on using it, see [ProximitySensor Class](https://learn.microsoft.com/uwp/api/windows.devices.sensors.ProximitySensor).

* The `Windows.Devices.Sensors.ProximitySensor` class allows measuring distance of an object in millimeters.

## Using `ProximitySensor` with Uno

* The sensor is currently only available on Android.
* To retrieve the available sensors, `DeviceInformation.FindAllAsync` method is used.

## Example

### Capturing sensor readings

```csharp
var selector = ProximitySensor.GetDeviceSelector();
var devices = await DeviceInformation.FindAllAsync(selector);
var device = devices.FirstOrDefault();
if (device is not null)
{
    var proximitySensor = ProximitySensor.FromId(device.Id);
    proximitySensor.ReadingChanged += ProximitySensor_ReadingChanged;
}

// ..

private async void ProximitySensor_ReadingChanged(ProximitySensor sender, ProximitySensorReadingChangedEventArgs args)
{
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        uint? distanceInMillimeters = args.Reading.DistanceInMillimeters;
        bool isDetected = args.Reading.IsDetected;
    });
}
```

### Unsubscribing from the readings

```csharp
proximitySensor.ReadingChanged -= ProximitySensor_ReadingChanged;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/contributing/guidelines/pull-requests.md

---
uid: Uno.Contributing.PullRequests
---

# Guidelines for pull-requests

If you don't know what a pull request is, read the [About pull requests documentation from GitHub](https://docs.github.com/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests).

## Creating a PR

If you are an outside contributor, please fork the Uno Platform repository you would like to contribute to your account. See the GitHub documentation for [forking a repo](https://help.github.com/articles/fork-a-repo/) if you have any questions about this.

Make sure the repository can build and all tests pass, as well as follow the current [coding guidelines](code-style.md).

Pull requests should all be made to the **master** branch.

### Updating your branch on top of the latest of the default branch

Make sure to rebase your work on the latest default branch of the Uno repository, when working on a fork:

- Add the official uno repository to your remotes:

    ```bash
    git remote add uno-origin https://github.com/unoplatform/uno
    ```

- Fetch the official repository

   ```bash
    git fetch uno-origin
   ```

- Rebase your work on the default branch

    ```bash
    git rebase uno-origin/master
    ```

- Then push your branch to your fork:

    ```bash
    git push -f
    ```

**Commit/Pull Request Format**

All commits **must** be in the [Conventional Commits format](../../uno-development/git-conventional-commits.md), otherwise the build will fail.

We use this convention to automatically generate release notes for new releases, and means that your commit messages will appear untouched in the release notes.

Make sure that:

- You create only the least possible commits, where each commit details a specific added feature or bug fix.
- Try using the category feature as frequently as possible. (e.g. `feat(NavigationView): Updated the main panel`, or `fix(ProgressRing): Fix visibility`)
- Squash your commits, using interactive rebase:

   ```bash
   git fetch uno-origin
   git rebase uno-origin/master -i # Rebase your branch on top of the latest master, squash using fixups
   git push -f
   ```

- If you're fixing a regression introduced by a PR that has not been released in a stable version yet, use the `reg` category. Example: `fix(reg): Fixing issue of previous PR`.

When opening a PR, you'll see the description is filled by a template. Make sure to read through the template and fill the missing parts in it.

If you haven't [added tests](creating-tests.md) appropriate to your changes, the reviewers will probably ask you to add some.

## Reviewing

Maintainers, contributors, and the community can participate in reviewing pull-requests. We require `two approvals` before the pull-request can be merged. Please apply the appropriate labels to the pull-request when reviewing. If the pull-request requires minor touch ups, consider doing them in the GitHub editor rather than asking the initiator of the pull-request to do them for you.
The history should be squashed to meaningful commits, and the branch should be rebased to a recent commit.

## Merging

Once a PR is reviewed and approved. One of the team members will merge it when it passes CI and is ready to merge.

If the branch is within the `unoplatform/uno` repository then the branch will be automatically deleted after merging by the [delete-merged-branch](https://github.com/apps/delete-merged-branch) robot.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/raspberry-pi/raspberry-pi-intro.md

---
uid: Uno.RaspberryPi.Intro
---

# Getting Started with Uno Platform and the Raspberry Pi

![Uno Hello World](images/00_uno-hello-world.jpg)

## Prerequisites

For this guide, you'll need various pieces of hardware and an Azure Account;

- Raspberry Pi 3b+ and above (I'll be using a [4Gb Pi 4](https://shop.pimoroni.com/products/raspberry-pi-4?variant=29157087445075))
- [Raspberry Pi Power Supply](https://shop.pimoroni.com/products/universal-usb-c-power-supply-5-1v-3a)
- [16GB SD Card](https://amzn.to/2YAI07e)
- SSH Client like [PuTTY](https://putty.org/)(Both Windows and Mac have a built in ssh client)
- Code Editor - [Visual Studio Code](https://code.visualstudio.com)
- Choose the two following options:
  - [LCD Touchscreen](https://amzn.to/3uYSXvt), Keyboard and mouse
  - OR [VNC Viewer](https://www.realvnc.com/en/connect/download/viewer/)

## What we'll be doing

In this guide, we'll be setting up our Raspberry Pi to launch a "Hello World" Uno Application.

For this guide, we'll install all of the requirements to build and run the application directly on the Pi, but I will show you how to do this on your main machine at the end.

There will be a series of steps involved in this;

- [Connect to your Raspberry Pi](#connect-to-your-raspberry-pi)
- [Update Raspberry Pi OS](#update-raspberry-pi-os)
- [Install .NET](#install-net)
- [Install Uno Platform Templates](#install-uno-platform-templates)
- [Create a new Uno Solution](#create-a-new-uno-solution)
- [Give the SSH Session access to use the display](#give-the-ssh-session-access-to-use-the-display)
- [Build and run the application](#build-and-run-the-application)
- [Creating and Building on a PC](#creating-and-building-on-a-pc)
- [Wrap Up](#wrap-up)

## Connect to your Raspberry Pi

Before we go anywhere, let's make sure we can dial in to our Raspberry Pi.

You may need to do this part with a Keyboard, a Mouse and Monitor of course, unless you enabled SSH on the SD card before you installed Raspberry Pi OS.

Firstly, make sure that your Pi is connected to the same network.

We need to enable both SSH and VNC connections, so click the Raspberry Pi OS start button, then go to the Preferences sub menu and hit the "Raspberry Pi Configuration Item";

![Raspberry Pi Configuration Menu Item](images/01_raspberry_pi_configuration_menu_item.png)

Next, click the Interfaces Tab, and make sure that SSH and VNC are enabled;

![Raspberry Pi Configuration](images/02_enabled_ssh_and_vnc.png)

Hit the Ok button, and accept the offer to reboot your Pi.

## Update Raspberry Pi OS

Before we can do anything, assuming you've gotten your Raspberry Pi all set up, we need to make sure that everything is up to date.

Run the following two commands;

```bash
sudo apt update
sudo apt full-upgrade
```

Once those two commands have completed, restart your Pi using;

```bash
sudo reboot
```

## Install .NET

Now that our Pi is all up to date, we're ready to install the .NET.

Normally for the Pi, as there's no `apt-get install dotnet`, we'd need to go through a bunch of steps to get .NET installed.

However, I've created a single line install script for .NET 7 on the Raspberry Pi.

Run the following command;

```bash
wget -O - https://raw.githubusercontent.com/pjgpetecodes/dotnet7pi/main/install.sh | sudo bash
```

You can see the contents of this .NET installation script in [install.sh on GitHub](https://github.com/pjgpetecodes/dotnet7pi/blob/main/install.sh)

![Install .NET](images/03_install-dot-net.gif)

Once the process has completed, go ahead and reboot your Pi again with;

```bash
sudo reboot
```

Once you're finished, you should be able to run the following to check your .NET version;

```dotnetcli
dotnet --info
```

![.NET Installed](images/04_dot-net-info.png)

## Install Uno Platform Templates

Next we can add the Uno Platform Project Templates to our .NET Installation;

```dotnetcli
dotnet new --install Uno.Templates
```

![Install Uno Templates](images/05_install-uno-templates.png)

Once the templates are installed, you can scroll back up and see the list of Uno templates that were installed;

![Uno Templates Installed](images/06_uno-templates-installed.png)

## Create a new Uno Solution

Now we have the moving parts installed on our Pi, we can spin up a brand new Uno solution with the following command;

```dotnetcli
dotnet new unoapp -o HelloPi && cd HelloPi
```

You should now find yourself in the solution directory for your new Uno App. If we have a look at the folder contents with;

```bash
dir
```

![Uno Templates Installed](images/07_uno-app-directory.png)

The directory we're interested in is the `HelloPi` directory. This directory contains the project which we'll build and run on the Raspberry Pi.

## Give the SSH Session access to use the display

Before we can launch our application, we need to give our SSH session access to the display.

If we don't do this, we'll get an error like;

```console
Unable to init server: Could not connect: Connection refused

(HelloPi:18530): cannot open display:
```

We can sort this out using the following command:

```bash
export DISPLAY=:0
```

You won't get any response to this message, so don't worry.

You'll need to remember do this every time you launch a new SSH session currently, but don't worry too much about that for now.

## Build and run the application

We're now ready to run our application.

Firstly, we need to navigate to the HelloPi directory;

```bash
cd HelloPi
```

We can now run our application with;

```dotnetcli
dotnet run -f net9.0-desktop
```

This will take quite some time to run this command the first time as the Pi isn't as powerful as a desktop PC of course.

You may also see some errors, but don't worry about those, as they're complaining that we're not running this from Visual Studio for XAML Hot reload to connect to.

To be able to see your app running, you're going to need to either connect a Monitor or VNC, but all being well, after a minute or so, you should see the Uno Hello World application running happily on your Pi;

![Uno App Running](images/09_uno-app-running.png)

## Creating and Building on a PC

We've performed most of this on the Pi itself of course. However, you can actually create and build the whole application on your PC and copy the built files to your Pi using;

```dotnetcli
dotnet publish -r linux-arm -o bin\linux-arm\publish --no-self-contained
```

You can copy the contents of the `bin\linux-arm\publish` directory to your Pi in whatever way takes your fancy.

You then need to navigate to the directory where you've copied the files and make the main application executable with;

```bash
chmod +x HelloPi
```

Don't forget that, if you've just dialled in you'll need to give access to the Display;

```bash
export DISPLAY=:0
```

If you are using a 64-bit version of the Raspberry Pi OS, you need to run the following commands to be able to run 32-bit executable :

```bash
sudo apt-get install ia32-libs-multiarch
sudo apt-get install ia32-libs
```

You can then run the application with;

```bash
./HelloPi
```

See [Developing UWP Apps for the Raspberry Pi with Uno Platform](https://www.petecodes.co.uk/developing-uwp-apps-for-the-raspberry-pi-with-uno-platform/) blog post for how you can actually automate Building, Deploying, and even debugging from your Windows machine using VS Code.

## Wrap Up

With that, we've gotten our first Hello World application up and running on the Raspberry Pi.

Thanks.

[Pete Gallagher](https://www.twitter.com/pete_codes)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/raygun-monitoring.md

---
uid: Monitoring.Raygun
---

# Error Monitoring & Crash Reporting with Raygun

> [!TIP]
> This article covers the basic setup and Uno-specific information for using Raygun with Uno. For a full description of the feature and instructions on using it, see the [official .NET 6+ | Raygun documentation](https://raygun.com/documentation/language-guides/dotnet/crash-reporting/net-core/).

Crash reporting is crucial for developing mobile and desktop applications. It ensures you are alerted when exceptions occur, whether they are unhandled or caught exceptions you want to report. With Visual Studio App Center's retirement on the horizon, what diagnostic tool should we turn to?

Raygun provides various products, including crash reporting, real user monitoring, and application performance monitoring (APM). It supports a wide range of frameworks, including .NET.

## Setting Up Raygun

Raygun offers a free trial, allowing you to explore its features before committing to a subscription. Follow these steps to get started:

### Create a Raygun Account

Visit the [Raygun website](https://raygun.com) and sign up for an account.

### Create Your Application

1. Log in to your Raygun account.
2. Create a new application and name it.
3. Select C#/.NET as the language and choose .NET 6+ as the framework.

## Integrating Raygun into Your Uno Platform Application

Let's start with a new Uno Platform application using the default template provided by the Uno Template Wizard.

### Step 1 – Create a New Uno Platform Project

Start by creating a new Uno Platform project using your preferred development environment.

### Step 2 - Install the NuGet Package

Install the Raygun package in your Uno Platform application. Use the Manage NuGet Packages option or the following dotnet CLI command:

```sh
dotnet add package Mindscape.Raygun4Net.NetCore
```

### Step 3 - Create a RaygunClient

Create an instance of `RaygunClient` by passing it a `RaygunSettings` object with your application API key. You can also enable automatic catching of unhandled exceptions:

```csharp
using Mindscape.Raygun4Net;

private static RaygunClient _raygunClient = new RaygunClient(new RaygunSettings()
{
    ApiKey = "YOUR_API_KEY_HERE",
    CatchUnhandledExceptions = true // Enable to log all unhandled exceptions
});
```

Replace `"YOUR_API_KEY_HERE"` with the actual API key provided by Raygun when you created your application.

### Step 4 - Release and Test

Deploy Raygun into your production environment for optimal results. To test the integration, you can raise a test exception:

```csharp
try
{
    throw new Exception("Temporary example exception to send to Raygun");
}
catch (Exception ex)
{
    _raygunClient.SendInBackground(ex);
}
```

> [!IMPORTANT]
> If you are setting up Raygun on Wasm, you need to either enable support for multithreading (see the [Wasm threading documentation](https://platform.uno/docs/articles/external/uno.wasm.bootstrap/doc/features-threading.html) for more information) or use the `SendAsync` method instead of `SendInBackground`.

### Step 5 - Observe the Website

Once Raygun detects your first error event, the dashboard will automatically update, allowing you to start monitoring.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/release-procedure.md

---
uid: Uno.Contributing.ReleaseProcedure
---

# Uno.UI release procedure

Uno.UI uses [NBGV](https://github.com/dotnet/nbgv) for its versioning.

Tagging is the main driver for planning releases.

## Branches

- On the `master` branch, the main development is happening and is considered unstable. The nuget packages produced end with `-dev.X`, where X is the number of commits since the last initiated release.
- On the `release/beta` branch, stabilization occurs to get a stable release. The version is inherited from the branch point from master. The nuget packages produced end with `-beta.X`, where X is the number of commits since the last stable release.
- On the `release/stable` branch, stable nuget packages are produced for each pushed merge or commit. The **Patch** number is increased by the number of commits since the release tagging occurred.
- On `dev`, `feature`, and `project` branches, the behavior is to inherit from the base branch it was created from and create a nuget package with an experimental tag. Those branches must not be tagged.

## Creating a release

### When planning for a beta

- Once a release is planned, make a branch in `release/beta` (e.g. `release/beta/1.29`), and tag the commit using the requested version (e.g. `1.29`). Do not include the patch number, as it will be added by GitHub when publishing a release. Tagging will automatically increased the version in the `master` branch by a **minor** number.
- Make stabilization fixes to the `release/beta/1.29` branch.
- Once the stabilization fixes are done, take the last `release/beta/1.29` commit and make a `release/stable/1.29` branch. Commits to this branch will automatically keep the `1.29` version, as the base **beta branch** was tagged `1.29`.
- Publish the release on GitHub using the patch number (e.g. `1.29.0` if there where no changes)

### When planning for a release without a beta

- Once a release is planned, make a branch in `release/stable` (e.g. `release/stable/1.29`), and tag the commit using the requested version (e.g. `1.29`). Tagging will automatically the version in the `master` increased by a **minor** number.
- Commits to `release/stable/1.29` will automatically keep the `1.29` version.
- Publish the release on GitHub using the patch number (e.g. `1.29.0` if there where no changes)

## Canaries

A 'canary' in Uno parlance is a version of a real-world application (or class library) that is used to test changes to Uno. There are continuous integration (CI) pipelines configured that consume the latest development builds of Uno and produce new nightly canary versions of applications (eg [Calculator](https://github.com/unoplatform/calculator), [UADO](https://github.com/unoplatform/uado) etc). If the builds of these applications fail then then it's an early signal that overnight a breaking compilation change may have been accidentally introduced into Uno. This style of regression (binary breaking change) is rare as there are API approval tests that are run on every pull-request to master. Typically if a regression slips in then it's something that only integration testing would have picked up - ie. package incompatibility between dependencies.

The Uno team does manual QA on canary failures to determine the differences between the canary build and the previous stable version of Uno. Fixes to regressions are resolved as quickly as possible by the team.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/getting-started/requirements.md

---
uid: Uno.GettingStarted.Requirements
---

# Supported platforms

Uno Platform applications run on [Android](#android), [iOS](#ios), [Web](#webassembly), [macOS (Desktop)](#macos---desktop), [Linux](#linux), and [Windows](#windows).

See below for the minimum supported versions for each platform.

## WebAssembly

Uno Platform runs in browsers that support WebAssembly, including Chrome, Edge, Edge Dev, Opera, Firefox, and Safari. Desktop and mobile browser versions are supported, using the `net9.0-browserwasm` target framework. See the official WebAssembly site for [more details](https://webassembly.org/roadmap).

Uno Platform runs in browsers that support WebAssembly, including Chromium-based browsers (e.g., Chrome, Edge, Arc, Opera etc.), as well as Firefox and Safari. Desktop and mobile browser versions are supported, using the `net9.0-browserwasm` target framework. See the official WebAssembly site for [more details](https://webassembly.org/roadmap).

## Windows

Two paths are available:

- Applications built with Uno Platform's [Skia Desktop](xref:Uno.Skia.Desktop) target framework, supporting Windows 7 and above, using the `net9.0-desktop` target framework.
- Running apps built with WinAppSDK or WinUI run on Windows 10. Currently Uno.UI's API definition is aligned with [Windows 10 2004 (19041)](https://learn.microsoft.com/windows/uwp/whats-new/windows-10-build-19041), using the `net9.0-windows10.0.19041` target framework. Lower versions can be targeted.

## Android

Uno Platform apps run on devices running Android 5 and above, using the `net9.0-android` target framework.

At compile time, Uno Platform typically supports two versions of the Android SDK, the latest and the immediately previous (e.g. Android 15 and Android 14). It's generally recommended to use the latest version of the SDK.

> [!NOTE]
> This **does not** affect the runtime version. Apps compiled with Android 15 will run properly on devices running Android 10.

## iOS

Uno Platform apps run on iOS 11 and above, using the `net9.0-ios` target framework.

## macOS - Desktop

Uno Platform applications run on all macOS versions supported by .NET, currently macOS 10.15 and above, using the `net9.0-desktop` target framework.

## Linux

Uno Platform applications run on Linux distributions and versions where latest .NET versions are supported, [listed here](https://learn.microsoft.com/dotnet/core/install/linux), using the `net9.0-desktop` target framework. Supported environments are X11 and Framebuffer.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/resources-trimming.md

---
uid: Uno.Features.ResourcesTrimming
---

# XAML Resource Trimming

XAML Resource and Binding trimming is an optional feature used to reduce the size of the final payload of an Uno Platform application.

The trimming phase happens after the compilation phase and tries to determine which UI controls are not used explicitly, and removes the associated XAML styles. The XAML styles are found through the value specified in the `TargetType` attribute.

As of Uno Platform 6.0, XAML Resources Trimming is available for apps targeting WebAssembly, iOS, and Desktop.

## Using XAML Resources trimming for applications

In order for an application to enable resources trimming, the following needs to be added to all projects of your solution that reference the Uno.WinUI (or Uno.UI) package, as well as the WebAssembly head project:

```xml
<PropertyGroup>
    <UnoXamlResourcesTrimming>true</UnoXamlResourcesTrimming>
</PropertyGroup>
```

Make sure to update your dependencies:

- If you're using the .NET SDK 8.0.200 or later, you'll need to use the [Uno.Wasm.Bootstrap](https://www.nuget.org/packages/Uno.Wasm.Bootstrap) package 8.0.9 or later.
- With .NET SDK 8.0.10x or earlier, you will also need to add the following package to your `.Wasm.csproj`:

    ```xml
    <ItemGroup>
        <PackageReference Include="Microsoft.NET.ILLink.Tasks" Version="8.0.0" />
    </ItemGroup>
    ```

## Enabling XAML Resources trimming for libraries and NuGet Packages

For libraries to be eligible for resources trimming, the `UnoXamlResourcesTrimming` tag must also be added.

## Troubleshooting

### Aggressive trimming

The XAML trimming phase may remove controls for which the use cannot be detected statically.

For instance, if your application relies on the `XamlReader` class, trimmed controls will not be available and will fail to load.

If XAML trimming is still needed, the [IL Linker configuration](xref:uno.articles.features.illinker) can be adjusted to keep controls individually or by namespace.

### Size is not reduced even if enabled

The IL Linker tool is used to implement this feature, and can be [controlled with its configuration file](xref:uno.articles.features.illinker).

For instance, if the linker configuration file contains `<assembly fullname="uno.ui" />`, none of the UI Controls will be excluded, and the final app size will remain close as without trimming.

## Size reduction statistics

As of Uno Platform 6.0, for a `dotnet new unoapp` created app:

|                      | without XAML Trimming | with XAML Trimming |
| -------------------- | --------------------- | ------------------ |
| Total IL Payload     |               12.9 MB |            9.12 MB |
| dotnet.wasm          |                 53 MB |            28.9 MB |
| iOS IPA              |                 93 MB |               73MB |
| Win32 Desktop        |                200 MB |              52 MB |
| macOS Desktop        |                200 MB |              58 MB |

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.toolkit.ui/refs/heads/main/doc/helpers/responsive-extension.md

---
uid: Toolkit.Helpers.ResponsiveExtension
---

# ResponsiveExtension

The `ResponsiveExtension` class is a markup extension that enables the customization of `UIElement` properties based on screen size.
This functionality provides a dynamic and responsive user interface experience.

## Platform limitation (UWP-desktop)

`ResponsiveExtension` relies on `MarkupExtension.ProvideValue(IXamlServiceProvider)` to find the target control and property for continuous value updates, and to obtain the property type to apply automatic type conversion, as its value properties are parsed as `string` by the XAML engine. Since this overload is a recent addition exclusive to WinUI, UWP projects targeting Windows won't have access to these features. Uno UWP projects targeting non-Windows platforms do not face this limitation. However, the Windows app may crash or present unexpected behavior if you attempt to use this markup on a non-`string` property.

```xml
<Border Background="{utu:Responsive Narrow=Red, Wide=Blue}"
        Tag="This will not work on Uwp for windows" />
```

You can workaround this by declaring the values as resources and using {StaticResource} to refer to them:

```xml
<Page.Resources>
    <SolidColorBrush x:Key="RedBrush">Red</SolidColorBrush>
    <SolidColorBrush x:Key="BlueBrush">Blue</SolidColorBrush>
...

<Border Background="{utu:Responsive Narrow={StaticResource RedBrush},
                                    Wide={StaticResource BlueBrush}}" />
```

## Properties

| Property    | Type               | Description                                                |
|-------------|--------------------|------------------------------------------------------------|
| `Narrowest` | `object`           | Value to be used when the screen size is at its narrowest. |
| `Narrow`    | `object`           | Value to be used when the screen size is narrow.           |
| `Normal`    | `object`           | Value to be used when the screen size is normal.           |
| `Wide`      | `object`           | Value to be used when the screen size is wide.             |
| `Widest`    | `object`           | Value to be used when the screen size is at its widest.    |
| `Layout`    | `ResponsiveLayout` | Overrides the screen size thresholds/breakpoints.          |

### ResponsiveLayout

Provides the ability to override the default breakpoints (i.e., the window widths at which the value changes) for the screen sizes.
This is done using an instance of the `ResponsiveLayout` class.

#### Properties

| Property    | Type     | Description            |
|-------------|----------|------------------------|
| `Narrowest` | `double` | Default value is 150.  |
| `Narrow`    | `double` | Default value is 300.  |
| `Normal`    | `double` | Default value is 600.  |
| `Wide`      | `double` | Default value is 800.  |
| `Widest`    | `double` | Default value is 1080. |

#### Resolution Logics

The layouts whose value(ResponsiveExtension) or template(ResponsiveView) is not provided are first discarded. From the remaining layouts, we look for the first layout whose breakpoint at met by the current screen width. If none are found, the first layout is return regardless of its breakpoint.

Below are the selected layout at different screen width if all layouts are provided:

| Width          | Layout    |
|----------------|-----------|
| 149            | Narrowest |
| 150(Narrowest) | Narrowest |
| 151            | Narrowest |
| 299            | Narrowest |
| 300(Narrow)    | Narrow    |
| 301            | Narrow    |
| 599            | Narrow    |
| 600(Normal)    | Normal    |
| 601            | Normal    |
| 799            | Normal    |
| 800(Wide)      | Wide      |
| 801            | Wide      |
| 1079           | Wide      |
| 1080(Widest)   | Widest    |
| 1081           | Widest    |

Here are the selected layout at different screen width if only `Narrow` and `Wide` are provided:

| Width              | Layout |
|--------------------|--------|
| 149                | Narrow |
| 150(~~Narrowest~~) | Narrow |
| 151                | Narrow |
| 299                | Narrow |
| 300(Narrow)        | Narrow |
| 301                | Narrow |
| 599                | Narrow |
| 600(~~Normal~~)    | Narrow |
| 601                | Narrow |
| 799                | Narrow |
| 800(Wide)          | Wide   |
| 801                | Wide   |
| 1079               | Wide   |
| 1080(~~Widest~~)   | Wide   |
| 1081               | Wide   |

## Usage

> [!TIP]
> It is not necessary to define every template or layout breakpoint: Narrowest, Narrow, Normal, Wide, Widest. You can just define the bare minimum needed.

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<TextBlock Background="{utu:Responsive Narrow=Red, Wide=Blue}" Text="Asd" />
```

> [!NOTE]
> The `ResponsiveExtension` requires a `FrameworkElement` to initialize. In the case of non-`FrameworkElement`, like `ColumnDefinition` or `TextBlock` inlines, it uses the xaml root-object to initialize. Because of this, it will not work on non-FE defined inside a `ResourceDictionary` file, but res-dicts defined within a `Page`/`Control` are not affected.

### Custom thresholds

```xml
xmlns:utu="using:Uno.Toolkit.UI"
...

<Page.Resources>
    <utu:ResponsiveLayout x:Key="CustomLayout"
                          Narrow="400"
                          Wide="800" />
</Page.Resources>
...

<TextBlock Text="{utu:Responsive Layout={StaticResource CustomLayout}, Narrow=Narrow, Wide=Wide}" />
```

> [!NOTE]
> The `ResponsiveLayout` can also be provided from different locations. In the order of precedences, they are:
>
> - from the `Layout` property
> - in the property owner's parent `.Resources` with `x:Key="DefaultResponsiveLayout"`, or the property owner's parent's parent's...
> - in `Application.Resources` with `x:Key="DefaultResponsiveLayout"`
> - from the hardcoded `ResponsiveHelper.DefaultLayout` which is defined as [150/300/600/800/1080]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/other/rider-eula.md

---
uid: Uno.Rider.EULA
---

# End-User License Agreement (EULA) for Uno Platform for Rider Plugin

## 1. IMPORTANT: READ CAREFULLY

This End-User License Agreement ("EULA") is a legal agreement between you ("Licensee" or "You") and Uno Platform ("Licensor" or "We") for the use of the Uno Platform Plugin for Rider ("Software"). By installing, copying, or otherwise using the Software, you agree to be bound by the terms of this EULA.

## 2. LICENSE GRANT

### 2.1 License

Subject to the terms of this EULA, Licensor hereby grants you a non-exclusive, non-transferable, revocable license to use the Software, free of charge, solely for your personal or internal business purposes.

## 3. LICENSE RESTRICTIONS

### 3.1 No Distribution

You may not distribute, sublicense, rent, lease, lend, or otherwise transfer the Software to any third party.

### 3.2 Modifications

You may not modify, adapt, translate, reverse engineer, decompile, or disassemble the Software, or create derivative works based on the Software.

### 3.3 Proprietary Notices

You may not remove or alter any proprietary notices or labels on the Software.

## 4. OWNERSHIP

### 4.1 Intellectual Property

The Software is licensed, not sold. All rights, title, and interest in and to the Software, including all intellectual property rights therein, remain with Licensor.

## 5. DISCLAIMER OF WARRANTIES

### 5.1 No Warranties

The Software is provided "AS IS" and "AS AVAILABLE" without warranty of any kind, whether express, implied, or statutory, including but not limited to the implied warranties of merchantability, fitness for a particular purpose, title, and non-infringement.

## 6. LIMITATION OF LIABILITY

### 6.1 No Liability for Damages

In no event shall Licensor be liable for any damages (including, without limitation, lost profits, business interruption, or lost information) arising out of your use of or inability to use the Software, even if Licensor has been advised of the possibility of such damages.

## 7. TERMINATION

### 7.1 Termination by You

You may terminate this EULA at any time by uninstalling and destroying all copies of the Software.

### 7.2 Termination by Licensor

Licensor may terminate this EULA immediately upon notice if:

1. You breach any term of this EULA,
2. Licensor is required to do so by law (for example, where the provision of the Software to Licensor is, or becomes, unlawful),
3. Licensor elects to discontinue providing the Software, in whole or in part.

### 7.3 Effect of Termination

Upon termination, you must immediately cease all use of the Software and destroy all copies of the Software. Licensor will make reasonable efforts to notify you about Software license termination.

## 8. COLLECTION AND USE OF DATA

Uno Platform uses tools to deliver certain Software features and extensions, identify trends and bugs, collect activation information, usage statistics, and track other data related to your use of the Software as further described in the most current version of Uno Platform’s Privacy Policy (located at: [https://platform.uno/privacy-policy/](https://platform.uno/privacy-policy/)). By your acceptance of the terms of this Agreement and/or use of the Software, you authorize the collection, use, and disclosure of this data for the purposes provided for in this Agreement and/or the Privacy Policy.

## 9. GOVERNING LAW

### 9.1 Governing Law

This EULA shall be governed by and construed in accordance with the laws of Quebec, Canada, without regard to its conflict of law principles.

## 10. MISCELLANEOUS

### 10.1 Severability

If any provision of this EULA is held to be unenforceable, such provision shall be reformed only to the extent necessary to make it enforceable, and the remaining provisions of this EULA shall remain in full force and effect.

### 10.2 Entire Agreement

This EULA constitutes the entire agreement between you and Licensor with respect to the Software and supersedes all prior or contemporaneous understandings or agreements, written or oral, regarding such subject matter. By installing or using the Software, you acknowledge that you have read this EULA, understand it, and agree to be bound by its terms and conditions.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/routed-events.md

---
uid: Uno.Features.RoutedEvents
---

# Uno Platform Support for Routed Events

Per the WinUI contract, Uno Platform provides support for [routed events](https://learn.microsoft.com/windows/uwp/xaml-platform/events-and-routed-events-overview), events which are 'bubbled' from a child object to each of its successive parents in the XAML object tree. In most cases, you can expect routed events to behave the same way on Windows and non-Windows platforms.

This article covers some of the finer technical details of Uno Platform's routed events implementation that may be relevant in advanced scenarios, eg those involving custom native (non-WinUI) views in your visual tree.

## Event Bubbling Flow

```plain
[1]---------------------+
| An event is fired     |
+--------+--------------+
         |
[2]------v--------------+
| Event is dispatched   |
| to corresponding      |                    [12]
| element               |                      ^
+-------yes-------------+                      |
         |                             [11]---no--------------+
         |<---[13]-raise on parent---yes A parent is          |
         |                             | defined?             |
[3]------v--------------+              |                      |
| Any local handlers?   no--------+    +-------^--------------+
+-------yes-------------+         |            |
         |                        |    [10]----+--------------+
[4]------v--------------+         |    | Event is bubbling    |
| Invoke local handlers |         |    | to parent in         <--+
+--------+--------------+         |    | managed code (Uno)   |  |
         |                        |    +-------^--------------+  |
[5]------v--------------+         |            |                 |
| Is the event handled  |         v    [6]-----no-------------+  |
| by local handlers?    no------------>| Event is coming from |  |
+-------yes-------------+              | platform?            |  |
         |                             +------yes-------------+  |
[9]------v--------------+                      |                 |
| Any parent interested |              [7]-----v--------------+  |
| by this event?        yes-+          | Is the event         |  |
+-------no--------------+   |          | bubbling natively?   no-+
         |                  |          +------yes-------------+
[12]-----v--------------+   |                  |
| Processing finished   |   v          [8]-----v--------------+
| for this event.       |  [10]        | Event is returned    |
+-----------------------+              | for native           |
                                       | bubbling in platform |
                                       +----------------------+
```

 1. **An event is fired**: when an event is intercepted from the platform.
 2. **Event dispatcher**: the source element in visual tree receive the event through its event handler.
 3. **Local handlers?**: check if there is any local handlers for the event.
 4. **Invoke handlers**: they are invoked one after the other, taking care of the "IsHandled" status.
 5. **Handled?**: check if any of the local handlers marked the event as _handled_.
 6. **Originating from platform?**: check if the source of the event is from native code.
 7. **Bubbling natively?**: check if the bubbling should be done natively for this event.
    bubbling natively will let controls not implemented in Uno the ability to intercept the event.
 8. **Returned for native bubbling**: let the event bubbling in the platform.
 9. **Any Parent Interested?**: check if any parent control is interested by a "handled" version of this event
    (using `AddEventHandler(<evt>, <handler>, handledEventsToo: true)`).
 10. **Bubbling in managed code**: propagate the event in Uno to parents (for events not bubbling natively
    or `handledEventsToo: true`).
 11. **Parent defined?**: if the element is connected to any parent element.
 12. **Processing finished**: no more handlers is interested by this event. Propagation is stopped.
    Native bubbling is stopped too because the event is fully handled.

## Native bubbling vs Managed bubbling

A special property named `EventsBubblingInManagedCode` is used to determine how properties are propagated through
the platform. This value of this property is inherited in the visual tree.

This value is set to `RoutedEventFlag.None` by default, so all routed events are bubbling natively by default
(except for those which can't bubble natively like `LostFocus` on iOS or `KeyDown` on Android).

Bubbling natively will improve interoperability with native UI elements in the visual tree by letting the
platform propagate the events. But this will cause more interop between managed and unmanaged code.

You can control which events are bubbling in managed code by using the `EventsBubblingInManagedCode`
dependency property. The value of this property is inherited to children. Example:

```csharp
  // Make sure PointerPressed and PointerReleased are always bubbling in
  // managed code when they are originating from myControl and its children.
  myControl.EventsBubblingInManagedCode =
      RoutedEventFlag.PointerPressed | RoutedEventFlag.PointerReleased;
```

### Limitations of managed bubbling

When using a managed bubbling for a routed event, you'll have a the following limitations:

* Native container controls (scroll viewer, lists...) won't receive the event, so they can stop
  working properly.
* Once an event is converted for _managed_ bubbling, it cannot be switched back to native
  propagations : it will bubble in managed code to the root, no matter how the bubbling mode is
  configured for this event type.

### Limitations of native bubbling

* Registering handler using  `handledEventsToo: true` won't receive events if they are _consumed_
  (marked as _handled_) in platform components. If it's a problem, you must switch to managed bubbling
  for those events. If the event is _consumed_ before reaching the first managed handler, you must
  add a handler in one one the children to give Uno a way to intercept the event and make it bubble
  in managed code.
* Bubbling natively can lead to many back-in-forth between managed and native code, causing a lot
  of interop marshalling.

## Guidelines for performance

1. When you can, prefer _managed_ bubbling over _native_ to reduce crossing the interop boundary
   many times for the same event.
2. Try to reduce the usage of `handledEventsToo: true` when possible.

## Differences from UWP/WinUI 3

Due to serious differences between various platforms, some compromises were done during the
implementation of RoutedEvents:

### Property `OriginalSource` might not be accurate on _RoutedEventArgs_

In some cases/events, it's possible that the `OriginalSource` property of the _RoutedEventArgs_ is `null`
or referencing the element where the event crossed the _native-to-managed_ boundary.

This property is however always accurate for "Pointers", "Manipulation", "Gesture", and "Drag and drop" events.

### Resetting `Handled` to false won't behave like in UWP

There's a strange behavior in UWP where you can switch back the `event.Handle` to `false` when
intercepted by a handler with `handledEventsToo: true`. In UWP, the event will continue to bubble normally.
Trying to do this in Uno can lead to unreliable results.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.wasm.bootstrap/refs/heads/main/doc/runtime-execution-modes.md

---
uid: Uno.Wasm.Bootstrap.Runtime.Execution
---

# Runtime Execution Modes

The mono for WebAssembly runtime provides three execution modes, Interpreter, and Mixed Mode Interpreter/AOT (Ahead of Time).

The execution mode can be set as follows:

```xml
<WasmShellMonoRuntimeExecutionMode>Interpreter</WasmShellMonoRuntimeExecutionMode>
```

The possible values are:

- `Interpreter` (the default mode)
- `InterpreterAndAOT`

## Interpreter mode

This mode is the slowest but allows for great flexibility and debugging, as well as an efficient payload size.

The linker mode can also be completely disabled for troubleshooting, as this will not impact the wasm payload size.

## Jiterpreter mode

This mode is a hybrid between the interpreter and the AOT modes, where the interpreter is used to execute the code, but the JIT engine is used to generate some WebAssembly code on the fly. This mode is generally faster than the interpreter, but slower than the AOT mode.

To enable this mode, use the following option:

```xml
<PropertyGroup>
    <WasmShellEnableJiterpreter>true</WasmShellEnableJiterpreter>
</PropertyGroup>
```

Additionally, some options can be used to fine-tune the Jiterpreter mode, using options found [in this file](https://github.com/dotnet/runtime/blob/6a047a9aec7a36039cffac61186b04bd3f16dbe0/src/mono/mono/utils/options-def.h#L86-L114):

```xml
<PropertyGroup>
    <WasmShellRuntimeOptions>--jiterpreter-stats-enable --jiterpreter-estimate-heat</WasmShellRuntimeOptions>
</PropertyGroup>
```

Finally, runtime statistics are maintained by the jiterpreter and can be displayed by running `INTERNAL.jiterpreter_dump_stats()` in the browser debugger console.

## Mixed Interpreter and AOT Mode

This mode enables AOT compilation for most of the assemblies, with [some specific exceptions](https://github.com/dotnet/runtime/issues/50609).

This mode is only active when running `dotnet publish`, `dotnet build -r Release` or any other build mode will not activate it.

To enable AOT compilation on normal builds, use the following:

```xml
<PropertyGroup>
  <RunAOTCompilationAfterBuild>true</RunAOTCompilationAfterBuild>
</PropertyGroup>
```

### Required configuration for Mixed AOT Mode or static linking on Linux

- Ubuntu 20.04+ or a [container](https://hub.docker.com/r/unoplatform/wasm-build)
- A [.NET SDK](https://docs.microsoft.com/en-us/dotnet/core/install/linux-ubuntu) >= 6.0

## Profile Guided AOT

This mode allows for the AOT engine to selectively optimize methods to WebAssembly, and keep the rest as interpreted. This gives a very good balance when choosing between performance and payload size. It also has the advantage of reducing the build time, as less code needs to be compiled down to WebAssembly.

This feature is used in two passes:

- The first pass needs the creation of a profiled interpreted build, which records any methods invoked during the profiling session.
- The second pass rebuilds the application using the Mixed AOT/Interpreter mode augmented by the recording created during the first pass.

This mode gives very good results, where the RayTracer sample of this repository goes from an uncompressed size of 5.5MB to 2.9MB.

To create a profiled build:

- In your Wasm csproj, add the following:

  ```xml
  <WasmShellGenerateAOTProfile>true</WasmShellGenerateAOTProfile>
  ```

- Run the application once, without the debugger (e.g. Ctrl+F5)
- Navigate throughout the application in high-usage places.
- Once done, either:
  - Press the `Alt+Shift+P` key sequence
  - Launch App.saveProfile()
- Download the `aot.profile` file next to the csproj file
- Comment the `WasmShellGenerateAOTProfile` line
- Add a reference to the generated file:
  - If you're using the [Uno.Sdk](xref:Uno.Features.Uno.Sdk), place the file in the `Platforms/WebAssembly` folder
  - If you're not using the Uno.Sdk, add the following lines:

    ```xml
    <ItemGroup>
      <WasmShellEnableAotProfile Include="aot.profile" />
    </ItemGroup>
    ```

- Make sure that Mixed mode is enabled:

  ```xml
  <WasmShellMonoRuntimeExecutionMode>InterpreterAndAOT</WasmShellMonoRuntimeExecutionMode>
  ```

- Publish your application again, using `dotnet publish`. (`dotnet build` does not activate AOT)

Note that the AOT profile is a snapshot of the current set of assemblies and methods in your application. If that set changes significantly, you'll need to re-create the AOT profile to get optimal results.

### AOT Profile method exclusion

The generated profile contains all the methods found to be executed during the profiling session, but some methods may still need to be manually excluded for some reasons (e.g. runtime or compile time errors).

The `WasmShellAOTProfileExcludedMethods` property specifies a semi-colon separated list of regular expressions to exclude methods from the profile:

```xml
<PropertyGroup>
    <WasmShellAOTProfileExcludedMethods>Class1\.Method1;Class2\.OtherMethod</WasmShellAOTProfileExcludedMethods>

    <!-- use this syntax to separate the list on multiple lines -->
    <WasmShellAOTProfileExcludedMethods>$(WasmShellAOTProfileExcludedMethods);Class3.*</WasmShellAOTProfileExcludedMethods>
</PropertyGroup>
```

The `MixedModeExcludedAssembly` is also used to filter the profile for assemblies, see below for more information.

Dumping the whole list of the original and filtered lists is possible by adding:

```xml
<PropertyGroup>
    <WasmShellGenerateAOTProfileDebugList>true</WasmShellGenerateAOTProfileDebugList>
</PropertyGroup>
```

This will generate files named `AOTProfileDump.*.txt` in the `obj` folder for inspection.

### Mixed AOT/Interpreter Mode

This mode allows for the WebAssembly generation of parts of the referenced assemblies and falls back to the interpreter for code that was excluded or not known at build time.

This allows for a fine balance between payload size and execution performance.

At this time, it is only possible to exclude assemblies from being compiled to WebAssembly through the use of this item group:

```xml
<ItemGroup>
  <MonoRuntimeMixedModeExcludedAssembly Include="Newtonsoft.Json" />
</ItemGroup>
```

Adding assemblies to this list will exclude them from being compiled to WebAssembly.

### Troubleshooting Mixed AOT/Interpreter Mode

When using the Mixed AOT/Interpreter mode, it is possible that some methods may not be compiled to WebAssembly for a variety of reasons. This can cause performance issues, as the interpreter is slower than the AOT-generated code.

In order to determine which methods are still using the interpreter, you can use the following property:

```xml
<PropertyGroup>
  <WasmShellPrintAOTSkippedMethods>true</WasmShellPrintAOTSkippedMethods>
</PropertyGroup>
```

The logs from the AOT compiler can be found in [binlogs generated](https://aka.platform.uno/msbuild-troubleshoot) from the build.

### Increasing the Initial Memory Size

When building with Mixed AOT/Interpreter modes, the initial memory may need to be adjusted in the project configuration if the following error message appears:

```text
wasm-ld: error: initial memory too small, 17999248 bytes needed
```

In order to fix this, you'll need to set the [`INITIAL_MEMORY`](https://emscripten.org/docs/tools_reference/settings_reference.html?highlight=initial_memory#initial-memory) emscripten parameter, this way:

```xml
<ItemGroup>
  <WasmShellExtraEmccFlags Include="-s INITIAL_MEMORY=64MB" />
</ItemGroup>
```

which will set the initial memory size accordingly. Note that setting this value to a sufficiently large value (based on your app's usual memory consumption) can improve the startup performance.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/samples-tutorials-overview.md

---
uid: Uno.SamplesTutorials.Overview
---

# Samples & Tutorials

Welcome to the Uno Platform Samples & Tutorials section!

Here, you'll find a collection of resources designed to help you learn and explore the capabilities of Uno Platform. Whether you're a beginner looking to get started with your first app, or an experienced developer seeking to expand your knowledge, we have something for everyone.

## Getting Started

[**Counter App Tutorial**](xref:Uno.Workshop.Counter): Learn the basics of Uno Platform by creating a simple counter app. There are four variants of the Counter tutorial, combining markup language ([XAML](https://learn.microsoft.com/en-us/visualstudio/xaml-tools/xaml-overview) or [C# Markup](xref:Uno.Extensions.Markup.Overview)) and presentation framework ([MVVM](https://learn.microsoft.com/en-us/windows/apps/develop/data-binding/data-binding-and-mvvm) or [MVUX](xref:Uno.Extensions.Mvux.Overview)). Also, you can build the Counter tutorial using our visual designer, [Hot Design](xref:Uno.HotDesign.GetStarted.CounterTutorial).

## Workshops

Dive into these hands-on workshops that guide you through building applications with the Uno Platform.
These workshops will help you learn more about the tools, libraries, and patterns available in the Uno Platform, which are there to help you rapidly build high-quality applications. Finally, these workshops have been set up to provide you with optional content, allowing you to tailor the experience to your needs.

- [**SimpleCalc Workshop**](xref:Workshop.SimpleCalc.Overview): A step-by-step tutorial to build a fully functional calculator. There are four paths possible for this workshop, combining markup language ([XAML](https://learn.microsoft.com/en-us/visualstudio/xaml-tools/xaml-overview) or [C# Markup](xref:Uno.Extensions.Markup.Overview)) and presentation framework ([MVVM](https://learn.microsoft.com/en-us/windows/apps/develop/data-binding/data-binding-and-mvvm) or [MVUX](xref:Uno.Extensions.Mvux.Overview)).
- [**TubePlayer Workshop**](xref:Workshop.TubePlayer.Overview): A step-by-step tutorial to build an app that allows the user to search for, and stream, YouTube videos. By the end of this workshop, you'll have built a multi-platform application using Uno Platform features like [C# Markup](xref:Uno.Extensions.Markup.Overview) and [MVUX](xref:Uno.Extensions.Mvux.Overview). You'll have the option to import a UI from [Figma](https://aka.platform.uno/uno-figma) or to continue following the steps to build the UI for the application.

## In-Depth Tutorials

Expand your skills with these in-depth tutorials.

[**Tutorials Overview**](xref:Uno.Tutorials.Intro): A collection of tutorials to delve deeper into specific features and concepts that will show you how to use Uno Platform and solve specific problems.

## Sample Projects

Explore a range of sample projects showcasing the versatility of Uno Platform.

[**Chefs**](xref:Uno.Chefs.Overview): A recipe app that combines recipe browsing with interactive features, allowing users to explore step-by-step instructions, video tutorials, nutritional information, user reviews, and even create their own personalized cookbooks, all while showcasing powerful features of the Uno Platform in a practical, real-world scenario.

[**Samples Repository**](xref:Uno.Samples): A curated list of sample projects that demonstrate various functionalities and use cases ranging from small single-feature samples to larger showcase applications.

## Additional Resources

Further your knowledge and discover more about Uno Platform.

[**Next Steps in Learning**](xref:Uno.GetStarted.NextSteps): Resources for advancing your understanding of Uno Platform, including documentation, community links, and more.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/external/uno.samples/doc/samples.md

# Source: https://raw.githubusercontent.com/unoplatform/uno.samples/refs/heads/master/doc/samples.md

---
uid: Uno.Samples
---

# Uno.Samples

The [Uno.Samples repository](https://github.com/unoplatform/Uno.Samples) gathers various working examples for Uno Platform, ranging from small single-feature samples to larger showcase applications.

Browse the complete list below:

## Reference Samples

### Counter App

Experience the simplicity and power of Uno.Extensions through the Counter App, a straightforward yet powerful demonstration of both basic and advanced features of the Uno Platform. This app provides a hands-on experience with fundamental concepts such as state management, user interaction, and real-time UI updates.
This sample app was built using the four variants of the [Counter workshop](https://aka.platform.uno/counter-tutorial), combining markup language (XAML or C# Markup) and presentation framework (MVVM or MVUX).

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Counter)

### SimpleCalc App

The SimpleCalc App is a sample application designed to perform basic arithmetic operations. App was built using the four variants of the [Simple Calc workshop](https://aka.platform.uno/simplecalc-workshop), combining different markup languages (XAML or C# Markup) and presentation frameworks (MVVM or MVUX).

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/reference/SimpleCalc)

### TubePlayer App

The TubePlayer App is a sample application that allows users to search for, and stream Youtube videos. This app was created using the tools, libraries, and patterns provided by the Uno Platform, designed to facilitate the rapid development of high-quality applications.
This sample app was built following the [Tube Player workshop](https://aka.platform.uno/tubeplayer-workshop).

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/reference/TubePlayer)

### Chefs App

The [Chefs app](xref:Uno.Chefs.Overview) is an engaging recipe platform where you can explore a wide variety of recipes with step-by-step instructions, video tutorials, nutritional details with charts, and user reviews. You can save your favorite recipes, filter options based on your preferences, and even discover nearby contributors on the maps. The app also offers an exciting opportunity to learn from the [Recipe Books](xref:Uno.Recipes.Overview) section, where you'll find specially selected collections that show how powerful Uno Platform features are applied in real-world scenarios, providing you with practical insights and examples to enhance your development skills.

[Browse source](https://github.com/unoplatform/uno.chefs)

### Commerce App

The Commerce App is a sample application that demonstrates the use of ListFeed pagination, Feedviews, and other features provided by Uno.Extensions. It illustrates how these features can be applied to create an application complete with a shopping cart, products, and more.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/reference/Commerce)

### ToDo App

Dive into the essentials of task management with the ToDo App, a meticulously crafted sample application that highlights the power and flexibility of Uno.Extensions. By emphasizing the creation and organization of to-do lists, this app showcases practical applications of essential Uno.Extensions features, offering a hands-on experience in crafting responsive and user-friendly interfaces across multiple platforms.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/reference/ToDo)

### Other Samples

### Advanced XBind

The {x:Bind} markup extension (new for Windows 10) is an alternative to {Binding}. {x:Bind} runs in less time and less memory than {Binding} and supports better debugging.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/AdvancedXBind)

### Android Custom Camera

An Android-specific sample that shows how to start a camera capture intent, and display the result in an `Image` control.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/AndroidCustomCamera)

### Authentication with OpenID Connect (OIDC)

This sample application demonstrates the usage of the `WebAuthenticationBroker` in Uno with an OpenID Connect endpoint.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/Authentication.OidcDemo) | [Follow the tutorial](https://aka.platform.uno/auth-open-id-connect)

### Auto-Suggest

An implementation of the XAML `AutoSuggest` control, showing how to autofill suggestions for user input.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/AutoSuggestSample)

### Benchmark

An implementation of the .NET Benchmark Control, a performance comparison tool.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/Benchmark)

### BluetoothExplorer

A sample that allows the user to search for nearby Bluetooth connections and connect to a device of their choice. Uses [InTheHand.BluetoothLE](https://www.nuget.org/packages/InTheHand.BluetoothLE).

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/BluetoothExplorer) 

### Camera Capture UI

A cross-platform implementation of the UWP `CameraCaptureUI` class that allows the user to capture audio, video, and photos from the device camera.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/CameraCaptureUI)

### CardView Migration

An Uno conversion of the Xamarin `CardView` sample showing how to migrate a custom control.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/CardViewMigration)

### ChatGPT

A ChatGPT sample using OpenAI SDK with C# Markup, MVUX, and immutable records.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/ChatGPT)

### Chat SignalR

Demonstrates the use of [SignalR](https://docs.microsoft.com/en-us/aspnet/core/signalr/introduction?view=aspnetcore-3.1) in an Uno Platform application.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/ChatSignalR)

### ChatUI

A chat app featuring a UI template that's ready to connect to a service with real data. The app leverages MVUX to manage incoming data efficiently.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/ChatUI)

### Control Library

An example of creating a custom control library and calling a control from your shared project.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/ControlLibrary)

### Country Data

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/CountryDataSample)

### Custom Sorting

Sample app to accompany "Adding Custom Sorting Logic" blog post.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/CustomSorting)

### Dual-Screen

A simple example using the `TwoPaneView` control spanned across dual screens (such as Neo or Duo dual-screen devices for example).

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/DualScreenSample)

### EmbeddedResources

An example that demonstrates the use of embedded resources and how to read them from your app.
Note that the [`Default namespace`](https://stackoverflow.com/questions/2871314/change-project-namespace-in-visual-studio) property of all projects is the same in order for the embedded resource names to be the same on all platforms.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/EmbeddedResources)

### Entity Framework Core Demo

An example of Entity Framework Core 7 with a SQLite storage for WebAssembly, WinAppSDK, iOS, and Android.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/EFCoreSQLiteSample)

### FileSavePicker iOS

A working implementation of a folder-based save file picker for iOS. See [the 'iOS' section in the Windows.Storage.Pickers Uno documentation](https://platform.uno/docs/articles/features/windows-storage-pickers.html#ios) for more information.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/FileSavePickeriOS)

### Food Delivery

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/FoodDeliveryUI)

### HtmlControls

This is a WASM-only sample. It is creating _native_ HTML elements that can be used directly in XAML.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/HtmlControls)

### LiteDB

This is an example that utilizes the [LiteDB NuGet package](http://www.litedb.org/) to save data.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/LiteDB)

### Inserting Separators

This example demonstrates the dynamic creation of a menu incorporating nested items as well as items with separators.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/InsertingSeparators)

### Localization Samples

A pair of samples related to localization:

- Localization: A sample showcasing the basics of localization.

  [Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/LocalizationSamples/Localization) | [Follow the tutorial](https://aka.platform.uno/how-to-localize)

- RuntimeCultureSwitching: An example of changing app language while it is running.

  [Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/LocalizationSamples/RuntimeCultureSwitching) | [Follow the tutorial](https://aka.platform.uno/how-to-hotswap-app-language)

### Map Control

An implementation of the UWP `Maps` control with a custom slider that binds the value of the slider to the `ZoomLevel` property of the control.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MapControlSample)

### Media Gallery

Implementation of a class that enables saving media files into a gallery on Android, iOS, and Mac Catalyst.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MediaGallery)

### MVUX Samples

An implementation of simple, to-the-point code samples for [MVUX](https://aka.platform.uno/mvux) topics.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MVUX)

### .NET MAUI Embedding

Multiple samples that demonstrate third-party control libraries embedded in Uno Platform applications using .NET MAUI Embedding.
Note that these controls work only for target platforms .NET MAUI reaches – iOS, Android, MacOS, and Windows.

#### Esri ArcGIS Maps SDK for .NET

Embeds the [Esri ArcGIS Maps SDK for .NET](https://aka.platform.uno/maui-embedding-tutorial-arcgis) in an Uno Platform application.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/ArcGisApp)

#### DevExpress .NET MAUI Controls

Embeds the [DevExpress .NET MAUI Controls](https://aka.platform.uno/maui-embedding-tutorial-devexpress) in an Uno Platform application.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/DevExpressApp)

### GLCanvasElement Samples

Samples showcasing the usage of GLCanvasElement:

- GLCanvasElementSimpleTriangle: A sample that draws a simple triangle with GLCanvasElement.

  [Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/GLCanvasElementSamples/GLCanvasElementSimpleTriangle)

- GLCanvasElementRotatingCube: A sample that draws a continuously-rotating 3D cube.

  [Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/GLCanvasElementSamples/GLCanvasElementRotatingCube)

#### MESCIUS ComponentOne .NET MAUI Controls

Embeds the MESCIUS (formerly GrapeCity) [ComponentOne .NET MAUI Controls](https://aka.platform.uno/maui-embedding-tutorial-grapecity) in an Uno Platform application.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/GrapeCityApp)

#### Grial UI Kit

Embeds the [Grial UI Kit](https://aka.platform.uno/maui-embedding-tutorial-grialkit) in an Uno Platform application.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/GrialKitApp)

#### .NET MAUI Community Toolkit

Embeds the [.NET MAUI Community Toolkit](https://aka.platform.uno/maui-embedding-tutorial-mauicommunitytoolkit) in an Uno Platform application.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/MauiCommunityToolkitApp)

#### Syncfusion .NET MAUI Controls

Embeds the [Syncfusion .NET MAUI Controls](https://aka.platform.uno/maui-embedding-tutorial-syncfusion) in an Uno Platform application.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/SyncfusionApp)

#### Telerik UI for .NET MAUI

Embeds the [Telerik UI for .NET MAUI](https://aka.platform.uno/maui-embedding-tutorial-telerik) in an Uno Platform application.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MauiEmbedding/TelerikApp)

### Migrating Xamarin.Forms Animations

Code to accompany the [blog post](https://platform.uno/blog/migrating-animations-from-xamarin-forms-to-uno-platform/) on migrating animations from Xamarin Forms to Uno.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MigratingAnimations)

### Migrating Xamarin.Forms Effects

Code samples to accompany the [blog post](https://platform.uno/blog/xamarin-forms-migration-to-uno-platform-effects-and-alternative-approaches/) on Migrating from Xamarin.Forms Effects:

- XamarinFormsEffect: A reference implementation of an effect with an Android implementation.

  [Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MigratingEffects/XamarinFormsEffect)

- UnoEffectSample: Showcasing how to replace Effects with either ControlTemplates or custom code accessing the native control.

  [Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/MigratingEffects/UnoEffectsSample)

### Native Frame Navigation

An example showcasing how to set up the native frame navigation for iOS and Android, and frame navigation in general for Uno.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/NativeFrameNav) | [Follow the tutorial](https://aka.platform.uno/how-to-use-native-frame-nav)

### Native Style Switch

An example of a toggle that allows you to switch between Native UI Controls and UWP UI Controls. The sample includes a checkbox, slider, button, and toggle.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/NativeStylesSwitch)

### Navigation (Uno.Extensions)

An example series demonstrating the use of various Navigation features.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/Navigation)

### Neumorphism

An example of an app containing an animated lock that you can unlock.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/Neumorphism)

### Package Resources

An example that demonstrates the use of package assets and how to read them from your app.

Note that WebAssembly assets are downloaded on demand, as can be seen in the browser's network tab.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/PackageResources)

### Pet Adopt

An example that demonstrates the use of `PipsPager` with a `FlipView`, in an app created with the help of the [Uno Platform (Figma to C# or XAML) plugin](https://aka.platform.uno/uno-figma-plugin).

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/PetAdoptUI)

### Uno PongWars

Uno PongWars is a simple minigame that draws inspiration from the [PongWars HTML/JavaScript sample](https://github.com/vnglst/pong-wars), reimagined with the modern capabilities of [Uno Platform](https://platform.uno). Set in the backdrop of the eternal conflict between day and night, good and bad. This sample showcases Material design for a visually appealing experience. It demonstrates the use of [C# Markup](https://aka.platform.uno/csharp-markup) for UI development and [MVUX](https://aka.platform.uno/mvux) for state management, highlighting how Uno Platform enables building responsive games across Web (WebAssembly), Windows, Linux, Mac Catalyst, iOS, and Android from a single codebase. Explore interactive elements like a speed slider and adaptable theme colors, all running natively across platforms.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/PongWars)

### ScottPlot

[ScottPlot](https://scottplot.net/) is a free and open-source plotting library for .NET that makes it easy to interactively display large datasets. Line plots, bar charts, pie graphs, scatter plots, and more can be created with just a few lines of code.

Three sample apps are available:

1. **Quickstart sample**  
   This sample app was created by following the [ScottPlot Uno Platform Quickstart documentation](https://scottplot.net/quickstart/unoplatform).

2. **Signal plot with 5 million points sample**  
   This sample app was created the same way by following the [ScottPlot Uno Platform Quickstart documentation](https://scottplot.net/quickstart/unoplatform).  
   Only the code-behind differs to display a signal plot with 5 million random points.

3. **SQLite Data Persistence and Large Dataset Visualization Sample**  
   This sample demonstrates how to combine SQLite for database-driven data persistence with ScottPlot for visualizing large datasets.  
   It showcases how to handle and visualize different plot types while persisting the data in a database for long-term storage.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/ScottPlot) | [Follow the quickstart tutorial](https://scottplot.net/quickstart/unoplatform)

### SKCanvasElement Showcase

A sample demonstrating how to use `SKCanvasElement`.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SKCanvasElementShowcase) | [Read the documentation](https://aka.platform.uno/skcanvaselement)

### SkiaSharp Test

An example of the Uno implementation of SkiaSharp creating a basic canvas with text.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SkiaSharpTest)

### SkiaSharp Skottie: Lottie file player

This sample shows the use of the SkiaSharp.Skottie component, which allows the playback of [lottie files](https://airbnb.design/lottie).

This component provides Lottie support for all available Uno Platform targets.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SkottieSample)

### Splash Screen Sample

An example showing how to set the splash/launch screen in Uno.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SplashScreenSample) | [Follow the tutorial](https://aka.platform.uno/how-to-manually-add-splashscreen)

### SQLite

This is a simple standalone app demonstrating the use of SQLite in an Uno application, including WebAssembly. It uses Erik Sink's [SQLitePCLRaw](https://github.com/ericsink/SQLitePCL.raw), and Frank Krueger's [sqlite-net](https://github.com/praeclarum/sqlite-net) libraries.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SQLiteSample)

### StatusBar Theme Color

An example showing how to adjust the `StatusBar` and `CommandBar` dynamically based on the current light/dark theme.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/StatusBarThemeColor) | [Follow the tutorial](https://aka.platform.uno/how-to-update-status-bar-theme-color)

### The Cat API Client

An example demonstrating an approach to consuming REST web services in Uno using HttpClient.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/TheCatApiClient) | [Follow the tutorial](https://aka.platform.uno/how-to-consume-webservices)

### Time Entry

Code for the Silverlight migration tutorial.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/TimeEntry) | [Follow the tutorial](https://aka.platform.uno/silverlight-migration-landing)

### Toy Car

A proof of concept of a car animation using the `TwoPaneView` control spanned across dual screens (such as Neo or Duo dual-screen devices for example).
Inspiration from Justin Liu's [demo app](https://twitter.com/justinxinliu/status/1281123335410049027).

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/ToyCar)

### Travel UI

A sample travel app that shows how a user could 1) search for locations, 2) favorite locations, and 3) view their profile as well as others' profiles. For the layout, showcases many ListViews coupled with Grids.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/TravelUI)

### Uno BackgroundWorker: Background Work

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoBackgroundWorker)

### Uno Cakes Mobile

A port of Shaw Yu's Cakes Mobile App from [XampleUI](https://github.com/shawyunz/XampleUI) to Uno Platform.
Used to demonstrate simple page navigation from View and ViewModel.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoCakesMobile)

### Uno Contoso

A port of Microsoft's Contoso Enterprise UWP app to Uno Platform, using Prism.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoContoso)

### Uno Cupertino Theme

An example showing how to set up the [`Uno.Cupertino`](https://github.com/unoplatform/Uno.Themes) library.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoCupertinoSample) | [Consult the documentation](https://aka.platform.uno/cupertino-getting-started)

### Uno Ethereum+Blockchain

A sample showing how to integrate smart contracts on the Ethereum blockchain with a multi-targeted Uno Platform application.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoEthereumBlockChain)

### Uno GoodReads

A sample showing how to make an app containing several pages in a TabView, as well as fake data generation to populate those pages. The blog post series for this app includes parts on [creating the home page](https://platform.uno/blog/recreating-amazon-goodreads-app-home-page-using-material-ui-figma-and-uno-platform/), [creating the author page](https://platform.uno/blog/how-to-quickly-build-goodreads-author-page-with-figma-and-uno-platform/), [creating the books page](https://platform.uno/blog/replicating-goodreads-detail-page-in-figma-with-uno-platform/), and [code generation with Figma](https://platform.uno/blog/from-figma-to-visual-studio-adding-back-end-logic-to-goodreads-app/).

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoGoodReads)

### Uno Islands

This sample shows how you can integrate Uno Platform XAML controls into existing WPF applications using Uno Islands. This feature allows you to enhance WPF apps with Uno Platform features by hosting Uno Platform XAML files in a Shared project and adding an Uno Island using the UnoXamlHost control.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoIslandsSampleApp) | [Follow the tutorial](https://aka.platform.uno/uno-islands)

### Uno Material Theme

An example showing how to set up the [`Uno.Material`](https://github.com/unoplatform/Uno.Themes) library.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoMaterialSample) | [Consult the documentation](https://aka.platform.uno/uno-material-colors)

### Uno Onnx

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/OnnxSamples)

### Uno Scroll Reveal

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoScrollReveal)

### Uno SQlite One Drive Invoice

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoSQLiteOneDriveInvoiceSample)

### Uno Toolkit Material

An example showing how to set up the [`Uno.Toolkit.Material`](https://github.com/unoplatform/uno.toolkit.ui/tree/main/src/library/Uno.Toolkit.Material) library.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoMaterialToolkitSample) | [Consult the documentation](https://aka.platform.uno/toolkit-material-getting-started)

### Windows Community Toolkit

The [Windows Community Toolkit](https://learn.microsoft.com/windows/communitytoolkit/) is a collection of helper functions, custom controls, and app services. It simplifies and demonstrates common developer patterns when building experiences for Windows.

> [!IMPORTANT]
> **Here is the [Migration Guide from v7 to v8 for Windows Community Toolkit](https://github.com/CommunityToolkit/Windows/wiki/Migration-Guide-from-v7-to-v8) for additional information on what changed lately between these versions.**
>
> For some controls (`DataGrid`, `Carousel`, ect...) you will need to use **version 7.x** for them as they are no longer available in the latest 8.x version of Windows Community Toolkit. The complete list of changes is available in the [migration guide](https://github.com/CommunityToolkit/Windows/wiki/Migration-Guide-from-v7-to-v8).
>
> For additional information, here are the releases notes for Windows Community Toolkit:
>
> - [Release notes for version 7.x](https://github.com/CommunityToolkit/WindowsCommunityToolkit/releases)
> - [Release notes for version 8.x](https://github.com/CommunityToolkit/Windows/releases)

Depending on the version of the Windows Community Toolkit you want to use, the samples below provide examples of implementation.

#### For WCT version 8.x

This sample showcases the `SettingsCard` control, that can be used to display settings in your experience. It uses the default styling found in Windows 11 and is easy to use, meets all accessibility standards and will make your settings page look great!

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-8.x/UnoWCTSettingsCardSample) | [Follow the tutorial](https://aka.platform.uno/install-uno-community-toolkit)

#### For WCT version 7.x

This sample showcases the `DataGrid` control, a dynamic grid view ported from the Windows Community Toolkit that allows for x:Bind.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-7.x/UnoWCTDataGridSample) | [Follow the tutorial](https://aka.platform.uno/install-uno-community-toolkit)

### WCT DataGrid, TreeView, TabView

A combined Windows Community Toolkit sample showing the DataGrid, TreeView, and TabView controls in action.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WCTDataTreeTabSample)

### WebRTC

Demo of the usage of WebRTC in Uno WebAssembly. This sample establishes a direct WebRTC connection between 2 browsers and uses it to send messages between peers.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WebRTC)

### Windowing samples

Provides examples of the usage of multi-window APIs in Uno Platform apps.

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowingSamples)

### XAML Basics: ListView

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/XamlBasics/ListViewSample)

### XamlBrewer SkiaSharp

Port of the XAML Brewer WinUI3 SkiaSharp Sample application ([blog post](https://xamlbrewer.wordpress.com/2023/09/25/getting-started-with-skiasharp-in-winui-3/) and [source code](https://github.com/XamlBrewer/XamlBrewer.WinUI3.SkiaSharp.Sample)).

[Browse source](https://github.com/unoplatform/Uno.Samples/tree/master/UI/XamlBrewerUnoApp)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/settings.md

---
uid: Uno.Features.Settings
---

# Settings

> [!TIP]
> This article covers Uno-specific information for managing user preferences. For a full description of the feature and instructions on using it, see [Save and load settings in a WinUI app](https://learn.microsoft.com/windows/uwp/get-started/settings-learning-track).

* Settings API allows you to store the preferences of the user and preserve them across the launches of the application.

## Supported features

| Feature                                   | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|-------------------------------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `ApplicationData.Current.LocalSettings`   | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `ApplicationData.Current.RoamingSettings` | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |

## Using Settings with Uno

* On each target platform, the native user preferences APIs are used for storage.
* `RoamingSettings` are not roamed across devices, as this feature has been disabled by WinUI.

## Examples

### Storing a Setting

```csharp
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
localSettings.Values["MySettingName"] = "A user setting";
```

### Reading a setting

```csharp
ApplicationDataContainer localSettings = Windows.Storage.ApplicationData.Current.LocalSettings;
var localValue = localSettings.Values["MySettingName"] as string;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/shapes-and-brushes.md

---
uid: Uno.Features.ShapesAndBrushes
---

# Shapes & Brushes

## Implemented Shapes

| Shape       | Android | iOS     | macOS   | Wasm (1) |                                                              |
| ----------- | ------- | ------- | ------- | -------- | ------------------------------------------------------------ |
| `Ellipse`   | Yes     | Yes     | Yes     | Yes      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.ellipse) |
| `Line`      | Yes     | Yes     | Yes     | Yes      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.line) |
| `Path`      | Yes     | Yes     | Yes     | Yes (2)  | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.path) |
| `Polygon`   | Yes     | Yes     | Yes     | Yes      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.polygon) |
| `Polyline`  | Yes     | Yes     | Yes     | Yes      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.polyline) |
| `Rectangle` | Yes (3) | Yes (3) | Yes (3) | Yes      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.rectangle) |

Notes:

1. All shapes on _Wasm_ platform (including `Rectangle`) are rendered as `SVG` elements.

2. On _Wasm_, only the `Data=` text format is implemented.
   On other platforms, you can use either the _data_ or the geometries.

3. Rectangles on _Android_, _iOS_, and _macOS_ are rendered as a simple border.

## Implemented Shapes properties

| Shape                | Android | iOS  | macOS | Wasm    |                                                              |
| -------------------- | ------- | ---- | ----- | ------- | ------------------------------------------------------------ |
| `Fill` (1)           | Yes     | Yes  |       | Yes     | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.fill) |
| `GeometryTransform`  | No      | No   |       | No      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.geometrytransform) |
| `Stretch`            | Yes     | Yes  |       | Yes     | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.stretch) |
| `Stroke` (1)         | Yes     | Yes  |       | Yes     | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.stroke) |
| `StrokeDashArray`    | No      | Yes  |       | No      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.strokedasharray) |
| `StrokeDashCap`      | No      | No   |       | No      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.strokedashcap) |
| `StrokeDashOffset`   | No      | No   |       | No      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.strokedashoffset) |
| `StrokeEndLineCap`   | No      | No   |       | No      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.strokeendlinecap) |
| `StrokeLineJoin`     | No      | No   |       | No      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.strokelinejoin) |
| `StrokeMiterLimit`   | No      | No   |       | No      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.strokemiterlimit) |
| `StrokeStartLineCap` | No      | No   |       | No      | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.strokestartlinecap) |
| `StrokeThickness`    | Yes     | Yes  |       | Yes     | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.shapes.shape.strokethickness) |

Notes:

1. See next section for _fill_ & _stroke_ brushes limitations.

## Implemented Brushes / Properties

| Brush                              | Android | iOS     | macOS | Wasm | Skia Desktop |                                                             |
| ---------------------------------- | ------- | ------- | ---- | ------------------------------------------------------------ | ---------------------------------- |
| `AcrylicBrush`                     | Yes (3) | Yes (3) | Yes (3) | Yes   | Yes | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.acrylicbrush) |
| `ImageBrush`                       | Yes (1) | Yes (1) |  | No   | Yes | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.imagebrush) |
| `LinearGradientBrush` | Yes (2) | Yes (2) | Yes  | Yes | Yes | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.lineargradientbrush) |
| `RadialGradientBrush` (WinUI 2.4+) | Yes | Yes  | Yes  | Yes | Yes | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.radialgradientbrush) |
| `RevealBrush` (WinUI 2.0+) | No     | No     | No   | No  | No  | [Documentation](https://learn.microsoft.com/windows/winui/api/microsoft.ui.xaml.media.revealbrush) |
| `SolidColorBrush`                  | Yes     | Yes     | Yes  | Yes  | Yes | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.solidcolorbrush) |
| `XamlCompositionBrushBase`         | No      | No      | No    | No   | Yes | [Documentation](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.media.xamlcompositionbrushbase) |

Notes:

1. `ImageBrush` on Android & iOS can only be used as a `Fill` / `Background` brush; it is not supported for `Stroke`  / `BorderBrush` properties and **the image needs to be a local asset**. They are not supported as text's `Foreground`.
2. On Android and iOS, gradient brushes (`LinearGradientBrush` & `RadialGradientBrush`) are only used as a `Fill` / `Background` brush.
3. On Android, iOS, and macOS `AcrylicBrush` has some limitations. Please see the following section for details.

## AcrylicBrush

Uno Platform supports the `Backdrop` version of `AcrylicBrush` (blurring in-app content behind element) on all targets. In addition, on macOS we support the `HostBackdrop` acrylic (blurring content behind the app window).

The brush currently has an important limitation on Android, iOS, and macOS: it can be used **only on elements which have no children**. Eg., if you wanted to have an acrylic effect in the background of a `Grid` with child content, then you would add a `Border` with no inner child behind the other content in the `Grid` and set the acrylic background on the `Border`, rather than set it directly on the `Grid`:

```xml
<Grid>
    <Grid.RowDefinitions>
        <RowDefinition />
        <RowDefinition />
    </Grid.RowDefinitions>
    
    <!-- This border represents the background, 
        it covers the entire parent area -->
    <Border Grid.RowSpan="2">
        <Border.Background>
            <AcrylicBrush 
                AlwaysUseFallback="False" 
                TintColor="Red" 
                TintOpacity="0.8" />
        </Border.Background>
    </Border>
    
    <TextBox Text="Some input" />
    <Button Grid.Row="1">My content</Button>
</Grid>

```

Because many WinUI styles use `AcrylicBrush` on elements which violate this condition, we made the brush use solid fallback color by default on targets other than WASM. To enable the brush, you need to explicitly set the `AlwaysUseFallback` property to `false`:

```xml
<AcrylicBrush x:Key="MyAcrylicBrush" AlwaysUseFallback="False" ... />
```

## Brushes Usages

Where you can use which brushes

| Usage                                        | SolidColorBrush | ImageBrush           | GradientBrush   |
| -------------------------------------------- | --------------- | -------------------- | --------------- |
| `Background` property (many controls/panels) | Yes             | Yes (except on Wasm) | Yes             |
| `BorderBrush` (`Border`, `Panel`)            | Yes             | No                   | Yes (Skia, Android), partial (iOS, WASM) [see below] |
| `Foreground` (`TextBlock`)                   | Yes             | No                   | Yes (Wasm only) |
| `Fill` (Shapes)                              | Yes             | Yes (except on Wasm) | Yes             |
| `Stroke` (Shapes)                            | Yes             | No                   | Yes (Wasm only) |

## Gradient border brush limitations on WASM and iOS

There are limitations to support for gradient border brushes on some targets. Currently these are:

- WebAssembly - gradient borders cannot be applied properly on an element which uses `CornerRadius`
- iOS/macOS - gradient borders cannot be applied reliably when `RelativeTransform` is applied on it

If these conditions apply, the border will instead be rendered using `SolidColorBrush` provided by the `FallbackColor` property.

As default WinUI Fluent styles are using `ElevationBorder` brushes in many places, so we created a presenter that provides a "fake" gradient for these cases - `Uno.UI.Controls.FauxGradientBorderPresenter`. For custom styles we suggest you provide a custom "layered" approach that simulates the border, as this presenter is specifically built to support WinUI style-specific scenarios where:

- Exactly two gradient stops are present
- `FallbackColor` of the brush is equal to the "major" gradient stop
- The brush is applied "vertical" - so the "minor" stop is either on top or on the bottom of the control

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/signalr.md

---
uid: Uno.Development.SignalR
---

# SignalR

[SignalR](https://learn.microsoft.com/aspnet/core/signalr/introduction?view=aspnetcore-7.0) is an ASP.NET Core library that allows server-side code to be instantly pushed to the client.

## Prerequisites

- Visual Studio 2019 or higher
- Azure account (to publish SignalR service)

## Steps

1. Create `ASP.NET Core web application` in Visual Studio and name it `UnoChat.Service`.

    ![project-template](Assets/project-structure.JPG)

2. Add [SignalR Hub](https://learn.microsoft.com/aspnet/core/tutorials/signalr?view=aspnetcore-7.0&tabs=visual-studio#create-a-signalr-hub) to your `[YourProjectName].Service` project in a `Hubs` folder.

3. In your `Startup.cs` file, add your `SignalR` service and a `CORS policy` to the `ConfigureServices` method.

    ```csharp
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddRazorPages();
        services.AddSignalR();
        
        services.AddCors(o => o.AddPolicy(
            "CorsPolicy",
            builder => builder
                .AllowAnyOrigin()
                .AllowAnyMethod()
                .AllowAnyHeader()
        ));
    }
    ```

4. In your `Configure` method, add your CORS policy and `Hubs` endpoint

    ```csharp
    app.UseCors("CorsPolicy");

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapRazorPages();
        endpoints.MapHub<Hubs.[YourProjectHub]>("/yourProjectHub");
    });
    ```

You now have a SignalR service that you can use with your Uno application!

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/silverlight-migration/silverlight-migration-landing.md

---
uid: Uno.SilverlightMigration.Landing
---

# Migrating from Silverlight to WinUI and Uno Platform Documentation

Silverlight will reach the end of support  on October 12, 2021. As luck would have it, a new Windows UI framework is about to RTM in March 2021 – WinUI – the modern native UI platform of Windows. And with WinUI launch there is a renewed desire by C# and XAML developers to write single codebase applications for Windows and the Web.

Enter Uno Platform. Hello “Rich Internet Applications (RIA)” again!

There are a number of pages of Silverlight migration documentation to help you with migration – accompanying source code, techniques and considerations you need to make when migrating your Silverlight application.

## Table of contents

* [Silverlight to Uno Migration Introduction](00-overview.md)
* [Create the Uno solution for UWP and WASM](01-create-uno-solution.md)
* [Considering navigation – comparing Silverlight and UWP navigation](02-considering-navigation.md)
* [Reviewing the app startup – comparing Silverlight and UWP app lifecycle](03-review-app-startup.md)
* [Migrating the home page XAML and styles – comparing XAML](04-migrate-home-page-xaml-and-styles.md)
* [Switching to string resources – comparing the Silverlight and UWP approach to resources](05-string-resources.md)
* [Dialogs and errors – Silverlight ChildWindow to UWP ContentDialog and console logging](07-dialogs.md)
* [Data access services – high-level review of alternatives to WCF RIA Services, data and authentication](08-data-access-overview.md)
* [Client Authentication – securing access to data APIs](09-client-auth-service.md)
* [Implementing a singleton token service – pattern for implementing singletons and creating a token service to secure data APIs](10-implementing-singleton-token-service.md)
* [Implementing an identity service client – implementing an authentication service](11-implementing-identity-service-client.md)
* [Migrating the authentication UI – migrating the Silverlight login UI, alternative to Silverlight DataForm](12-migrate-auth-ui.md)
* [Integrating authentication and navigation – WIP – will migrate the role check before navigating](13-integrating-auth-and-navigation.md)
* [Implement the time entry service – WIP – will implement the Time Entry Service client](14-implement-timeentry-services.md)
* [Migrating the time entry UI – WIP – will look at alternatives to the Silverlight DataGrid](15-migrate-timeentry-ui.md)
* [Wrap-up – WIP – will summarize the key migration activities](20-wrap-up.md)
* [The TimeEntry Sample apps – overview of sample apps and build instructions](98-timeentry-samples.md)
* [Useful resources](99-useful-resources.md)

## Next unit: Silverlight to Uno Migration

[![button](assets/NextButton.png)](00-overview.md)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/skia-libraries-trimming.md

---
uid: Uno.Features.SkiaLibrariesTrimming
---

# Skia Native Libraries Trimming [Desktop only]

Starting with Uno 6.2, we are trimming rare Skia/HarfBuzz build variants by default.

Skia/HarfBuzz build variants were taking over 75% of the total published application size when doing a generic build.

By default, we now bundle win-x64, win-arm64, osx (includes arm64 + x64), linux-x64, linux-arm64 and linux-arm.

You may disable this behavior by adding a `<UnoIncludeAllSkiaNativeLibraries>true</UnoIncludeAllSkiaNativeLibraries>` property to your csproj.

You can also customize the build variant list by adding a `<UnoSkiaNativeLibraries>...</UnoSkiaNativeLibraries>` property to your csproj.

Where `...` is a semi-colon delimited list of the following values:

- win-arm64
- win-x64
- win-x86
- osx
- linux-arm
- linux-arm64
- linux-loongarch64
- linux-musl-arm
- linux-musl-arm64
- linux-musl-loongarch64
- linux-musl-riscv64
- linux-musl-x64
- linux-riscv64
- linux-x64
- linux-x86

For example, you may use: `<UnoSkiaNativeLibraries>win-arm64;win-x64</UnoSkiaNativeLibraries>`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/solution-building-single-targetframework.md

---
uid: Build.Solution.TargetFramework-override
---
# Improve Build Times with Visual Studio

The Uno Platform template **prior to Uno Platform 5.2** provides a cross-targeted Class library that includes multiple target frameworks, and your application may contain your own cross-targeted projects as well. This document explains how to make your builds faster.

> [!NOTE]
> For projects created with Uno Platform 5.2 or later, the Uno.Sdk takes care of building appropriate target frameworks for the selected debugger target when starting a debugging session. Optionally, you can follow [our migration guide](xref:Uno.Development.MigratingToSingleProject) to use the new project structure. If you want to always build one target framework you can follow the guide below.

## Reduce the number of built TargetFrameworks (5.2 templates and later)

When using an Uno Platform 5.2 template or later, in the **Folder Explorer**, you can apply the following steps to build only a subset of target frameworks using a configuration file.

To do so:

- Create a file named `solution-config.props.sample` next to your `.sln` file, with this content:

    ```xml
    <Project>
        <!--
            This file is used to control the platforms compiled by Visual Studio, and allow for a faster
            build when testing for a single platform. This will also result in better intellisense, as
            the compiler will only load the assemblies for the platform that is being built. You do not
            need to use this when compiling from Visual Studio Code, the command line or other IDEs.

            Instructions:
            1) Copy this file and remove the ".sample" name
            2) Uncomment the single property below for the target you want to build
            3) Make sure to do a Rebuild, so that nuget restores the proper packages for the new target

            Notes:
            - You may optionally close the solution before making changes and reload the solution afterwards. This will avoid Visual Studio
            asking you to reload any projects, it will also ensure that the changes are picked up by Visual Studio, and trigger a restore of
            the packages.
            - You may want to unload the platform heads that you are not going to build for. This will ensure that Visual Studio does not
            try to build them, and will speed up the build process.
        -->

        <PropertyGroup>
            <!-- Uncomment each line for each platform that you want to build: -->

            <!-- <OverrideTargetFramework Condition="''!='hint: Windows App Sdk (WinUI)'">net9.0-windows10.0.19041.0</OverrideTargetFramework> -->
            <!-- <OverrideTargetFramework Condition="''!='hint: Webassembly'">net9.0-browserwasm</OverrideTargetFramework> -->
            <!-- <OverrideTargetFramework Condition="''!='hint: Desktop'">net9.0-desktop</OverrideTargetFramework> -->
            <!-- <OverrideTargetFramework Condition="''!='hint: iOS'">net9.0-ios</OverrideTargetFramework> -->
            <!-- <OverrideTargetFramework Condition="''!='hint: Android'">net9.0-android</OverrideTargetFramework> -->
            <!-- <OverrideTargetFramework Condition="''!='hint: TvOS'">net9.0-tvos</OverrideTargetFramework> -->
        </PropertyGroup>
    </Project>
    ```

    Make sure to replace `net9.0` and `-windows10.0.19041.0` with the appropriate version from your `.csproj` project.

- You can commit `solution-config.props.sample` to your source control.
- Next, make a copy of `solution-config.props.sample` to `solution-config.props`. This file is [automatically loaded](https://github.com/unoplatform/uno/blob/71f1d5ab067c0dcfad2f4cccd310e506cdeaf6bf/src/Uno.Sdk/targets/Uno.Import.SolutionConfig.props#L9) by the `Uno.Sdk`.
- If you're using git, add this `solution-config.props` to your `.gitignore`.

  > [!NOTE]
  > This avoids altering the target frameworks or your own CI, as well as other clones made by other developers.

- Follow the directives from the file, uncommenting one of the `OverrideTargetFramework` to your choosing.
- In the project head, as well as any other libraries using the `Sdk="Uno.Sdk"`, add the following block immediately below the last `<TargetFrameworks>` line:

    ```xml
    <TargetFrameworks Condition=" '$(OverrideTargetFramework)' != '' ">$(OverrideTargetFramework)</TargetFrameworks>
    ```

- Once done, if you're in Visual Studio, you may need to close and re-open your solution or otherwise click the reload button. For other IDEs, the projects will reload automatically.

At this point, you'll notice that the list of target frameworks available in the debugger will have been reduced to the list you added in `OverrideTargetFramework`.

## Improve performance using the Uno Platform templates (5.1 and earlier)

When using an Uno Platform 5.0 template, in the **Solution Explorer**, you'll find a folder named **Solution Items**, and a file named `solution-config.props.sample`.

You can follow the directions specified in this file, or follow them here:

- Right-click on the root item (your solution name) and **Open in file explorer**
- Locate the `solution-config.props.sample` and make a copy named `solution-config.props` in the same folder
- Back in Visual Studio, and for your convenience you can right-click on `Solution Items` and add `solution-config.props`

Now that we have configured this file, let's say that you want to debug for WebAssembly:

- In the `solution-config.props` file, uncomment the line that mentions `Wasm` or `WebAssembly` then save it.
- For the change to take effect, close and reopen the solution, or restart Visual Studio.

Repeat this process when changing your active development platform.

> [!NOTE]
> The `solution-config.props` is automatically included in a `.gitignore` file to avoid having your CI environment build only for one target.

## Cross-targeted library builds in Visual Studio

While building with the command line `dotnet build -f net7.0-ios` only builds the application's head and the class library for `net7.0-ios`, as of Visual Studio 17.8, class library builds are considering all target frameworks, [regardless of the project head's target framework](https://developercommunity.visualstudio.com/t/Building-a-cross-targeted-project-with-m/651372) being built. _(Please help the Uno Platform community by upvoting the issue!)_

Considering that during development, it is common to work on a single platform at a given time, the two sections below contain a suggested set of changes to the Uno Platform solution that can be performed on the solution to restrict the active build platform, and therefore significantly speed up build times and make intellisense respond faster.

Choose the section covering your cases, whether you're using a solution built using Uno Platform 5.0 templates or created with an earlier version.

## Improve your own solution (4.9 and earlier)

If you created your solution with an earlier version of Uno Platform, you can make some modifications to make your build faster:

1. Let's create a set of solution filters to ensure that individual project heads can be loaded:

    1. Create a new app template with **iOS**, **Android**, **WebAssembly** and **Windows** targets   selected.
    1. Right click on the **.Mobile** and **.Wasm** projects and select **Unload Project**
    1. On the top level Solution node, right-click to select **Save As Solution Filter**, name the    filter **MyApp-Windows-Only.slnf**
    1. Right-click on the **Mobile** project, select **Reload Project**
    1. Unload the **.Windows** project, then save a new solution filter called **MyApp-Mobile-Only.slnf**
    1. Repeat the operation with the **.Wasm** project, with a solution filter called **MyApp-Wasm-Only.slnf**

    These solution filters will prevent Visual Studio to restore NuGet packages for TargetFrameworks that will be ignored by the configuration done below.

1. Now, next to the solution file, create a file named `targetframework-override.props`:

    ```xml
    <Project>
        <Import Project="solution-config.props" Condition="exists('solution-config.props')" />

        <!-- Override the TargetFrameworks list with the one specified in MyAppTargetFrameworkOverride -->
        <PropertyGroup Condition="'$(MyAppTargetFrameworkOverride)'!=''">
            <TargetFrameworks>$(MyAppTargetFrameworkOverride)</TargetFrameworks>
        </PropertyGroup>
    </Project>
   ```

1. Also next to the solution file, create a file named `solution-config.props.sample`:

    ```xml
    <Project>
        <PropertyGroup>
            <!--
            Uncomment the following line to enable single-target framework builds
            in order to get faster performance when debugging for a single platform.

            Once this file is modified, use the appropriate solution filter to avoid
            NuGet restore issues.

            Available target frameworks can be found in the project heads of your solution.
            -->
            <!-- <MyAppTargetFrameworkOverride>net7.0-ios</MyAppTargetFrameworkOverride> -->
        </PropertyGroup>
    </Project>
    ```

1. Next, in all projects of the solution which are cross-targeted (with multiple TargetFrameworks values), add the following lines right after the `PropertyGroup` which defines `<TargetFrameworks>`:

    ```xml
    <!-- Import the TargetFramework override configuration -->
    <Import Project="../../targetframework-override.props" />
    ```

    The file should then look like this:

    ```xml
    <Project Sdk="Microsoft.NET.Sdk">
        <PropertyGroup>
            <TargetFrameworks>net7.0-windows10.0.19041;net7.0;net7.0-ios;net7.0-android</TargetFrameworks>
        </PropertyGroup>
    </Project>
    <!-- Import the TargetFramework override configuration -->
    <Import Project="../../targetframework-override.props" />
    ```

    > [!NOTE]
    > If the template is created with `dotnet new`, the path will instead be `../targetframework-override.props`

1. Create a copy of the file `solution-config.props.sample` next to itself, and name it `solution-config.props`
1. If using git, add this specific file to the `.gitignore` so it never gets committed. This way, each developer can keep their own version of the file without corrupting the repository.
1. Commit your changes to the repository.

At this point, your solution is ready for single-TargetFramework use.

For example, to work on `net7.0-ios`:

1. Before opening the solution, open the `solution-config.props` file and uncomment `MyAppTargetFrameworkOverride` to contain `net7.0-ios`
1. Open the `MyApp-Mobile-Only.slnf` solution filter in Visual Studio
1. You should only see the **.Mobile** and **Class Library** projects in your solution
1. When building and debugging the app, you'll only now build for the target specified in `solution-config.props`.

> [!IMPORTANT]
> When changing the `MyAppTargetFrameworkOverride` value, make sure to close the solution and reload it so the build system recognizes properly the change.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/splash-screen.md

---
uid: Uno.Development.SplashScreen
---

# How to manually add a splash screen

Projects created using Uno Platform 4.8 or later have the Uno.Resizetizer [package](https://www.nuget.org/packages/Uno.Resizetizer) installed by default. Simply provide an SVG file, and the tool handles the task of generating various image sizes. That package updates the build process to automate configuring a splash screen for each platform.

While the new templates simplify adding a splash screen, this article covers how to add one to your application manually if using Uno.Resizetizer is not warranted.

> [!TIP]
> If your solution was generated using the older templates, it is possible to configure these projects to use Uno.Resizetizer instead. That process makes the steps below unnecessary.
>
> See the guide [How-To: Get Started with Uno.Resizetizer](xref:Uno.Resizetizer.GettingStarted#unosplashscreen) for more information.

## Step-by-step instructions

### 1. Shared splash screen image resources

* Review [Assets and image display](xref:Uno.Features.Assets) to understand the present support for various image asset types

* Prepare your images intended for the splash screen under different resolutions, eg:

    | File name | Width | Height |
    |----------------------------|:---:|:---:|
    | SplashScreen.scale-100.png | 216 | 148 |
    | SplashScreen.scale-125.png | 270 | 185 |
    | SplashScreen.scale-150.png | 324 | 222 |
    | SplashScreen.scale-200.png | 432 | 296 |
    | SplashScreen.scale-300.png | 648 | 444 |
    | SplashScreen.scale-400.png | 864 | 592 |

* Refer to this [table](xref:Uno.Features.Assets#table-of-scales) to see values for the different scales required.

  * You can instead provide only a single image named `SplashScreen.png` without the `scale-000` qualifier.

    > [!NOTE]
    > Regardless if you provide a single image or multiple images, you would always refer to this image as `SplashScreen.png`.

* Add these images under the `Assets\` folder of the `MyApp` project, right-click on each image, go to `Properties`, and set their build action as `Content`.

### 2. Windows

* In the `MyApp` project, open the file `Package.appxmanifest` and navigate to `Visual Assets > SplashScreen`.

* Make sure the value for `Preview Images > Splash Screen` is set to `Assets\SplashScreen.png`

    ![uwp-splash-screen](Assets/uwp-splash-screen.JPG)

### 3. Android

* In the `MyApp` project, open the subfolder for `Platforms/Android`

* Navigate further to the file at `Resources/values/Styles.xml`

* `Styles.xml` contains Android-specific customizations for the splash screen. Inside, look for the `AppTheme` style and add an `<item>` under it:

    ```xml
    <item name="android:windowBackground">@drawable/splash</item>
    ```

* Navigate upward to `Resources/drawable`, and create a new XML file named `splash.xml`:

    ```xml
    <?xml version="1.0" encoding="utf-8"?>
        <layer-list xmlns:android="http://schemas.android.com/apk/res/android">
        <item>
            <!-- background color -->
            <color android:color="#101010"/>
        </item>
        <item>
            <!-- splash image -->
            <bitmap android:src="@drawable/assets_splashscreen"
                    android:tileMode="disabled"
                    android:gravity="center" />
        </item>
    </layer-list>
    ```

    > [!IMPORTANT]
    > Before Uno.UI 4.5, the `@drawable/assets_splashscreen` source should be `@drawable/splashscreen`.
    > See the [breaking changes](https://github.com/unoplatform/uno/releases/tag/4.5.9) section of that release.

* Make sure `splash.xml` is added as an `AndroidResource` in the Droid project file: `[Project-name].Droid.csproj`.

  * This is not always done automatically and may occur if `splash.xml` was created and added outside the IDE.

    ```xml
    <ItemGroup>
      <AndroidResource Include="Resources\drawable\splash.xml" />
    </ItemGroup>
    ```

    > [!TIP]
    > After modifying `splash.xml`, you may run into errors like these while trying to debug:
    >
    > ```console
    > Resources\drawable-mdpi\SplashScreen.png : error APT2126: file not found.
    > Resources\drawable-hdpi\SplashScreen.png : error APT2126: file not found.
    > ```
    >
    > Simply rebuild the Android target to get rid of these errors.

### 4. iOS

* In the `MyApp` project, open the subfolder for `Platforms/iOS`

  * Delete the old splash screen files:
    * `Resources\SplashScreen@2x.png`
    * `Resources\SplashScreen@3x.png`
    * `LaunchScreen.storyboard`

* Create a new **StoryBoard** named `LaunchScreen.storyboard`:
  * Right-click the project subfolder you're working with (ex: `MyApp/Platforms/iOS`)
  * Select **Add** > **New Item...**
  * Create a **Visual C#** > **Apple** > **Empty Storyboard**

* In the **Toolbox** window, drag and drop a **View Controller** and then an **ImageView** inside the **View Controller**

  * Enable the **Is initial View Controller**-flag on the **View Controller**.

    ![`viewcontroller-imageview`](Assets/viewcontroller-imageview.png)

  * To have an image fill the screen, set your constraints as below

    ![ios-constraints](Assets/ios-constraints.png)

  * Set the **Content Mode** to **Aspect Fit**

    ![ios-content-fit](Assets/ios-content-fit.png)

  * In the **Properties** > **Storyboard Document** window, select the **Can be Launch Screen** checkbox.

    ![can-be-launch](Assets/can-be-launch.png)

* Close the designer and open the `.storyboard` file.

  * Add your image path to the `Image View`

    ```xml
    <imageView ... image="Assets/SplashScreen">
    ```

* Open `info.plist` and update the `UILaunchStoryboardName` value to `LaunchScreen`.

    > [!TIP]
    > iOS caches the splash screen to improve the launch time, even across re-installs. In order to see the actual changes made, you need to restart the iPhone or simulator. Alternatively, you can rename the `CFBundleIdentifier` in `info.plist` incrementally (eg: MyApp1 -> MyApp2) before each build.

### 5. WebAssembly

* The default splash screen configuration for WebAssembly is to use the Uno Platform logo as a placeholder.

* An `Platforms/WebAssembly/WasmScript/AppManifest.js` file contains some app settings, including properties to customize its splash screen. This file is found in the `MyApp` project.

#### General properties

You can customize the splash screen image and background color by adjusting several key properties:

  | Property | Description | Notes |
  |----------|-------------|-----|
  | `accentColor` | Color of the progress indicator's filled-in portion displayed during application launch | Default value is `#F85977` |
  | `displayName` | Default name visible in the browser window's title to represent the application | N/A |
  | `splashScreenColor` | Background color of the screen displayed during application launch | Any values assigned to the theme-aware properties are ignored unless this property is set to `transparent`. <br><br>If the theme-aware properties are unassigned, the default browser background color will be used instead. |
  | `splashScreenImage` | Path to an image that will be visible on the screen displayed during application launch | You currently need to set an explicit scale for the image |

  > [!TIP]
  > `splashScreenColor` allows you to maintain a background color regardless of the system theme. However, a simple method to make the splash screen theme-aware is to assign `transparent` as its value or by omitting that property altogether.

#### Theme-aware properties

  > [!NOTE]
  > The section below contains optional properties. If nothing is assigned to them, the value of `splashScreenColor` will be used under both themes as the background color.

  Uno Platform supports theme-aware backgrounds as an optional customization for splash screens. Set the following properties to adjust the splash screen based on a system theme:

  | Property | Description | Notes |
  | --- | --- | --- |
  | `lightThemeAccentColor` | Color of the progress indicator's filled-in portion displayed during application launch if a system light theme is enabled | Default value is `#F85977` |
  | `darkThemeAccentColor` | Color of the progress indicator's filled-in portion displayed during application launch if a system dark theme is enabled | Default value is `#F85977` |
  | `lightThemeBackgroundColor` | Background color of the screen displayed during application launch if a system light theme is enabled | Default value is `#F3F3F3` |
  | `darkThemeBackgroundColor` | Background color of the screen displayed during application launch if a system dark theme is enabled | Default value is `#202020` |

* Code example:

  ```javascript
  var UnoAppManifest = {
      splashScreenImage: "Assets/SplashScreen.scale-200.png",
      splashScreenColor: "transparent",
      displayName: "SplashScreenSample"
  }
  ```

## See also

* [Completed sample on GitHub](https://github.com/unoplatform/Uno.Samples/tree/master/UI/SplashScreenSample)
* [Ask for help on Discord](https://www.platform.uno/discord)
* [Uno.Resizetizer repository](https://github.com/unoplatform/uno.resizetizer)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/step-counter.md

---
uid: Uno.Features.StepCounter
---

# Step counter (Pedometer)

> [!TIP]
> This article covers Uno-specific information for Pedometer. For a full description of the feature and instructions on using it, see [Pedometer Class](https://learn.microsoft.com/uwp/api/windows.devices.sensors.pedometer).

* The `Windows.Devices.Sensors.Pedometer` class allows counting steps taken with the device.

## Supported features

| Feature           | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|-------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `GetDefaultAsync` | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `ReadingChanged`  | ✔       | ✔       | ✔   | ✖          | ✖     | ✖            | ✖            |
| `ReportInterval`  | ✔       | ✔       | ✔   | ✖          | ✖     | ✖            | ✖            |

## Using Pedometer with Uno

* The `GetDefault` method is available on all targets and will return `null` on those which do not support `Pedometer` or devices that do not have such a sensor.
* Ensure to unsubscribe from the `ReadingChanged` event when you no longer need the readings, so that the sensor is no longer active to avoid unnecessary battery consumption.
* `ReportInterval` property on WASM is currently not supported directly. Uno uses an approximation in the form of raising the `ReadingChanged` event, only when enough time has passed since the last report. The event is raised a bit more often to make sure the gap caused by the filter is not too large, but this is in line with the behavior of Windows' `Pedometer`.
* `DirectionalAccuracy` is not reported on iOS, so it will always return `Unknown`.

## Platform-specific requirements

### [**Android**](#tab/Android)

On Android, the first reading returns the cumulative number of steps since the device was first booted up. The sensor may not correctly respect the requested reporting interval, so the implementation does this manually to make sure the `ReadingChanged` events are triggered only after the `ReportInterval` elapses.

Since Android 10, your application must declare the permission to use the step counter sensor by adding the following `uses-feature` declaration to the `AndroidManifest.xml` in your project:

```xml
<uses-permission android:name="android.permission.ACTIVITY_RECOGNITION" />
```

### [**iOS**](#tab/iOS)

The first reading on iOS returns the cumulative number of steps from 24 hours back to the current moment. Unfortunately, in case the tracking was not enabled before, this will likely return 0 steps. Once the tracking is enabled, `ReadingChanged` will be triggered and the step count will be updated appropriately.

Make sure to add the following capability declaration to your `Info.plist` file, otherwise, the API will crash at runtime.

```xml
<key>NSMotionUsageDescription</key>
<string>Some reason why your app wants to track motion.</string>
```

---

## Example

### Capturing sensor readings

```csharp
var pedometer = await Pedometer.GetDefaultAsync();
pedometer.ReportInterval = 10000;
pedometer.ReadingChanged += Pedometer_ReadingChanged;

private async void Pedometer_ReadingChanged(Pedometer sender, PedometerReadingChangedEventArgs args)
{
    // If you want to update the UI in some way, ensure the Dispatcher is used,
    // as the ReadingChanged event handler does not run on the UI thread.
    await Dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
    {
        CumulativeSteps = args.Reading.CumulativeSteps;
        CumulativeStepsDurationInSeconds = args.Reading.CumulativeStepsDuration.TotalSeconds;
        Timestamp = args.Reading.Timestamp.ToString("R");
    });
}
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/studio/studio-feedback.md

---
uid: Uno.Platform.Studio.Feedback
---

# Providing Feedback for Uno Platform Studio

We deeply value your feedback for **Uno Platform Studio** and its tools ([**Hot Design<sup>®</sup>**](xref:Uno.HotDesign.Overview), [**Hot Reload**](xref:Uno.Platform.Studio.HotReload.Overview), and [**Design-to-Code**](xref:Uno.Figma.GetStarted)) to ensure we can deliver the best possible experience.

> [!IMPORTANT]
> To start using **Hot Design**, ensure you are signed in with your Uno Platform account. **Follow [these instructions](xref:Uno.GetStarted.Licensing) to register and sign in**.
>
> - Hot Design is available on all platforms. See the list of **[current known issues](xref:Uno.HotDesign.Troubleshooting)**.
> - Hot Design **does not support C# Markup** and is **only available with XAML and .NET 9+**.
> - Hot Design is **not available for the WinAppSDK target framework (`netX.0-windowsX.X.X`)** at this time.
> - Hot Design relies on **[Hot Reload](xref:Uno.Platform.Studio.HotReload.Overview)** for updates, so be sure to check the [current support for your OS, IDE, and target platforms](xref:Uno.Platform.Studio.HotReload.Overview#supported-features-per-os) before testing.

Here’s how you can share your feedback:

## 1. GitHub Feedback

Navigate to the [Uno Platform Studio GitHub repository](https://github.com/unoplatform/studio) to:

- **Report issues or bugs**: Share any unexpected behavior or issues you encounter with the tools or documentation.
- **Propose enhancements**: Suggest features or improvements to enhance Uno Platform Studio, its tools, and its documentation.
- **Start discussions**: Engage in conversations about Uno Platform Studio and its tools.

For more details, refer to the [feedback guidelines](https://github.com/unoplatform/studio/blob/main/README.md).

## 2. Hot Design Feedback Menu

You can also provide feedback directly while using **Hot Design** in a live, running application. Use the **Feedback** menu to:

- **Report an issue/bug**
- **Suggest a feature**
- **Ask a question**

Follow these steps to access the feedback menu:

1. Click on the three-dot button in the [Hot Design Toolbar](xref:Uno.HotDesign.GetStarted.Guide#toolbar).
2. Navigate to **Help** > **Feedback**.
3. Choose one of the following options:
   - **Report an issue/bug**
   - **Suggest a feature**
   - **Ask a question**

Refer to the image below for guidance:

![Hot Design Feedback Menu](Hot%20Design/Assets/hot-design-feedback-menu.png)

## Additional Support

For further assistance, visit our [Discord Server](https://platform.uno/uno-discord), where our engineering team and community will be happy to assist you.

For organizations seeking a deeper level of support beyond our community support, please [contact us](https://platform.uno/contact).

We look forward to your feedback and thank you for helping us improve Uno Platform Studio and its tools!

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/studio/studio-overview.md

---
uid: Uno.Platform.Studio.Overview
---

# Uno Platform Studio Overview

**Uno Platform Studio** is a set of productivity tools designed to enhance developer productivity, be it for design handoff, to radically improving developer inner dev loop with Hot Reload and the industry-first, cross-platform runtime visual designer for .NET, Hot Design<sup>®</sup>. **Uno Platform Studio** empowers developers to stay in their flow, enabling seamless cross-platform app development for every platform .NET runs on.

![Introducing Uno Platform Studio](Assets/Introducing-Uno-Platform-Studio.png)

## New in Uno Platform Studio 2.0:  Hot Design<sup>®</sup> Agent + Uno MCP + App MCP

**Hot Design<sup>®</sup> Agent** is an AI-powered assistant designed for rapid UX/UI creation and enhancement within your application. It leverages data contexts and live previews to help developers design, refine, and interact with user interfaces in real time. Built on deep knowledge of Uno Platform and your running app, it simplifies cross-platform .NET design, enabling intuitive and efficient workflows. [Learn more](xref:Uno.HotDesign.Agent)

**Uno MCP** provides structured, semantic access to Uno Platform’s complete knowledge base—covering documentation, APIs, and best practices—empowering AI agents and developers with the intelligence they need to build better experiences. Meanwhile, **App MCP** brings intelligent automation to life by enabling AI agents to interact directly with live Uno Platform applications, creating a seamless bridge between design, development, and execution. [Learn more](xref:Uno.Features.Uno.MCPs)

**Uno Platform Studio** revolutionizes how developers design, build, and iterate on their applications by leveraging purpose-built tools that streamline your workflow:

- **[Hot Design<sup>®</sup>](xref:Uno.HotDesign.Overview)**
  The industry-first, runtime visual designer, for cross-platform .NET Applications. Hot Design<sup>®</sup> transforms your running app into a Designer, from any IDE, on any OS, to create polished interfaces with ease. [Get started](xref:Uno.HotDesign.GetStarted.Guide)
  
- **[Hot Reload](xref:Uno.Features.HotReload)**  
  Reliably update any code in your app and get instant confirmation your changes were applied, with a new Hot Reload Indicator to monitor changes while you develop. [Get started](xref:Uno.HotReload.GetStarted.Guide)

- **[Design-to-Code](xref:Uno.Figma.GetStarted)**
  Generate ready-to-use, well-structured XAML or C# Markup directly from your Figma designs with one click, completely eliminating manual design handoff. [Get started](xref:Uno.Figma.GetStarted)

## Why Choose Uno Platform Studio?

**Uno Platform Studio** is designed to make cross-platform development fast, seamless, and enjoyable:

- Stay in your flow by working directly in your preferred IDE and Figma design tool on any OS.
- Build apps for every platform .NET runs on.
- Streamline workflows with tools that integrate design, development, and iteration.

## What's the difference between Uno.Sdk and Uno Platform Studio?

**Uno.Sdk** is the core SDK that powers the Uno Platform, enabling you to build cross-platform applications using C# and XAML from a single project. **Uno Platform Studio** is a suite of productivity tools that enhance your development experience, including Hot Design<sup>®</sup>, Hot Design<sup>®</sup> Agent, Uno MCPs, Hot Reload, and Design-to-Code.

As the **Uno Platform Studio** is built on top of **Uno.Sdk**, it's only available to applications that have been created, or updated, to use the **Uno.Sdk**. If you haven't updated your project to use the **Uno.Sdk**, you can do so by following the [migration guide](xref:Uno.Development.MigratingFromPreviousReleases).

Start your journey with **Uno Platform Studio** today by **[registering an account](https://platform.uno/my-account/)**, and take your app development productivity to the next level!

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/supported-features.md

---
uid: Uno.Development.SupportedFeatures
---

# Uno Platform Features

> [!NOTE]
> If you are looking for `UnoFeature` reference, check the [Using the Uno.Sdk article](xref:Uno.Features.Uno.Sdk) instead.

## Development Flow

- Uno Platform's WinUI/UWP XAML
  - **Windows-first development**
  - **Faster compilation** for most of the development cycle, including UI code. iOS, Android, WebAssembly, macOS and Linux can be tested for platform-specific features.
  - Ability to develop responsive layout in Windowed mode using Windows 10.
  - Allows for **edit and continue** support from VS2017+
  - Allows for **UI and Non-UI code edit and continue** support
- Conditional platform features access
  - All XAML controls have **access to native properties** through conditional XAML
  - Ability to **add native controls in XAML**
- Full WinUI/UWP availability at compile time
  - Allows for the **compilation of open-source libraries** that depend only on WinUI/UWP and multi-targeted nuget packages
    - **XamlBehaviors library** support
- macOS Compilation

## Features List

### Animations

- Animations on any DependencyProperty and AttachedProperty
- Visual States (declared animations, advanced setters)
- Visual State Groups (multi-state controls)
- StateTriggers (Orientation-based responsive design)
- Custom StateTriggers (e.g network state-based states)
- XAML-defined animation storyboards
- Binding expressions to Attached properties (Storyboard setters)

### Styling

- Attached Property Style binding (advanced styling, control reuse)
- Control templating (without the need of renderers) (control reuse, white-labeling)
- TemplateBinding  (control reuse)

### Data Binding

- Value Precedence
- Inheritance
- Mode
- Trigger
- x:Bind with support functions
- Converters
- Attached Properties binding
- RelativeSource.Self

### Design Fidelity

- Text Inlines Binding
- Text Independent trimming and wrapping
- Text Character Spacing
- Text Spans (Bold, Italic, Underline)
- [Path & Shapes support](features/shapes-and-brushes.md)
- Updatable Shapes support
- Image Brush support in shapes
- `FontIcon` support
- Merged Dictionary support

### Responsive Design

- Layout constraints \[Min/Max][Width/Height]
- Binding SourceTriggers (TextBox immediate vs. focus lost interactions)
- DependencyProperty Inheritance (Color, text style propagation)

### Runtime Performance

- CoreDispatcher Priority support (Large UIs performance)
- `x:DeferLoadStrategy="Lazy"`, `x:Load="false"` and `x:Load="{x:Bind ...}" support (responsive design performance)
- Image explicit size support (performance)
- Event tracing (sub-millisecond [ETL performance profiling](Assets/diagnostics.PNG))
- Internal logging
- Reflection-less bindings (complex UI performance)
- Binding suspension and restoration
- Expando Binding
- DynamicObject Binding
- DataTemplate and ControlTemplate reuse, pooling, and prefetching

### ListView

- `Selector`
- Any `ItemsPanel` support
- `ItemsStackPanel`
- `ItemsWrapGrid`
- Group sticky headers
- Group collection tracking
- Variable item size
- Snap points (with ScrollIntoView support)
- `ISupportIncrementalLoading` support
- `ICollectionView` support with SelectedItem

### Command Bar

- WinUI/UWP Command bar support
- Native Command bar support (Image, title, back, Opacity, ...)
- Global back button support

### Media

- `SolidColorBrush`
- `ImageBrush`
- `LinearGradientBrush`, with animations support.
- Local assets support with automatic conversion from WinUI conventions

### Others

- Native property access from any XAML control
- Localization for any property via x:Uid, using scoped or unscoped `.resw` files (Size localization)
- FocusManager (advanced large forms navigation, dynamic UIs)
- Advanced WebView support (scripting, scrolling, string, custom agent)
- Automatic asset generation from WinUI assets
- Native element embedding
- Panels (Grid, StackPanel with `Spacing`, RelativePanel, Canvas)
- Custom Panels
- Popups/Dialogs
- Work with the usual Windows tooling
- Animations
  - Easing functions
  - Theme Transitions
  - Entrance animations
- XAML Behaviors
- AttachedProperty Binding
- AttachedProperty Styling
- Custom `MarkupExtension` support
- Brightness Control
- Native and Custom dialogs
- Support for StateTriggers
- ProgressBar
- [Pointer Events](features/routed-events.md)
- [Routed Events](features/routed-events.md)
- GeneralTransform.TransformBounds
- Window.Services.Store (Store ID and links)
- Windows.ApplicationModel.Package (InstallDate)
- `ApplicationData.LocalSettings` and `RoamingSettings` support
- Windows.UI.ViewManagement.ApplicationView.VisibleBounds (Rounded corner/notched screen support)  - `SimpleOrientationSensor`
- ApplicationData Folders
- ScrollViewer Snap Points, Extent, Viewport Properties
- ScrollViewer MakeVisible, BringIntoView
- InputPane (Occlusion, Visibility, Events, ...)
- [Pointer Capture](features/routed-events.md)
- Slider
- FlipView
- Customizable Date and Time Pickers
- Orientation management
- Accessibility (Font Scaling, screen readers)
- Xamarin UITest support and full _Dependency Property_ access
- StatusBar management (occlusion, color, events)
- Runtime XAML reader
- Phased binding (x:Phase)
- XAML code-behind event registration
- WriteableBitmap
- NavigationView
- BitmapIcon
- MediaPlayer
- ViewBox
- PersonPicture
- ScrollBar

## WinUI Specific Controls (Pre 3.0)

- [NumberBox](https://learn.microsoft.com/uwp/api/microsoft.ui.xaml.controls.numberbox?view=winui-2.3)
- [TwoPaneView](https://learn.microsoft.com/uwp/api/microsoft.ui.xaml.controls.twopaneview?view=winui-2.3)

### Non-UI Features

- Windows.UI.Storage (StorageFile, StorageFolder, Settings)
- Windows.UI.Application
- Windows.UI.CoreDispatcher
  - UI Priority dispatch
- Windows.Graphics.Display.DisplayInformation orientation
- Windows.Media.SpeechRecognition
- Windows.Media.Capture.CameraCaptureUI

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/supported-libraries.md

---
uid: Uno.Development.SupportedLibraries
---

# Supported 3rd-party libraries

This article lists some of the 3rd-party libraries supported by Uno Platform.

## Control libraries

* [Windows Community Toolkit](uno-community-toolkit.md)
* [Syncfusion](https://github.com/syncfusion/Uno.SfChart)
* [Lightning Chart](https://platform.uno/blog/lightningchart-introduces-uno-platform-support/)
* [Live Charts](https://platform.uno/blog/livecharts-announces-support-for-uno-platform/)
* [ScottPlot](https://scottplot.net/quickstart/unoplatform/)
* [OxyPlot](https://github.com/HavenDV/H.OxyPlot)

## Presentation frameworks

* [CommunityToolkit.Mvvm](https://learn.microsoft.com/dotnet/communitytoolkit/mvvm/)
* [Prism](https://prismlibrary.com/)
* [ReactiveUI](https://www.reactiveui.net/)
* [MVVMCross](https://www.mvvmcross.com/)

## Design and theming

* [Uno.Material](external/uno.themes/doc/material-getting-started.md)
* [Uno.Cupertino](external/uno.themes/doc/cupertino-getting-started.md)

## HTTP and API clients

* [Refit](xref:Uno.Extensions.Http.Overview#refit) - Strongly-typed REST API client
* [Kiota](xref:Uno.Extensions.Http.Overview#kiota) - OpenAPI/Swagger client generator

## Data and storage

* [SQLite](https://www.sqlite.org/) - Local database for all platforms including WebAssembly
* [LiteDB](https://www.litedb.org/) - Embedded .NET NoSQL database
* [Json.NET (Newtonsoft.Json)](https://www.newtonsoft.com/json) - Popular JSON framework for .NET

## Logging

* [Serilog](https://serilog.net/) - Flexible logging library

## Other libraries

* [SkiaSharp](https://www.nuget.org/packages/SkiaSharp.Views.Uno)
* [Shiny .NET](https://shinylib.net/mediator/extensions/unoplatform/)

If we're missing a library here, [drop us a line](https://github.com/unoplatform/uno/issues/new/choose) or [create a Pull Request](https://github.com/unoplatform/uno/blob/master/doc/articles/supported-libraries.md)!

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/svg.md

---
uid: Uno.Features.SVG
---

# Using SVG images

Uno Platform supports using vector SVG graphics inside of your cross-platform applications, using the `SvgImageSource` class. SVG Images can also be used through [`UnoImage` with Resizetizer](xref:Uno.Resizetizer.GettingStarted).

![Uno SVG sample](../Assets/features/svg/heliocentric.png)

## How to use SVG

## [**Single Project**](#tab/singleproject)

To use an SVG, for iOS and Android, you'll need to add the `Svg` [Uno Feature](xref:Uno.Features.Uno.Sdk#uno-platform-features) as follows:

```xml
<UnoFeatures>
    ...
    Svg;
    ...
</UnoFeatures>
```

On Desktop Skia and WebAssembly, the feature is enabled by default.

To include an SVG file, you will need to place it in a folder named `Svg` (e.g. `Assets\Svg\MyFile.svg`). This is required in order to avoid [Uno.Resizetizer](xref:Uno.Resizetizer.GettingStarted) transform the file into a set of scaled PNGs files.

Now, you can display the SVG image in an `Image` by referencing it from the `Source` property. For example:

```xml
<Image Source="ms-appx:///Assets/Svg/test.svg" Stretch="UniformToFill" Width="100" Height="100" />
```

## [**Legacy Project**](#tab/legacyproject)

To use SVG, install the following NuGet packages into the iOS, macOS, Android, and Skia projects:

* `Uno.WinUI.Svg`
* `SkiaSharp.Views.Uno.WinUI`
* `Svg.Skia` (required only for the Skia project)

> [!NOTE]
> If the `Uno.[UI|WinUI].Svg` package is not installed, you will get a warning when an `.svg` image is loaded.
> If the `Svg.Skia` package is not installed, you will get an error when an `.svg` image is loaded for the Skia project.
> [!IMPORTANT]
> The `Uno.[UI|WinUI].Svg` package is not needed for WebAssembly, and must only be installed on the Mobile and Skia heads. It must not be in any other class libraries of your solution.

Add the SVG Image to the app project and make sure that the build action is set to Content.

Now, you can display the SVG image in an `Image` by referencing it from the `Source` property. For example:

```xml
<Image Source="ms-appx:///Assets/test.svg" Stretch="UniformToFill" Width="100" Height="100" />
```

---

You can also explicitly use `SvgImageSource`:

```xml
<Image>
  <Image.Source>
    <SvgImageSource UriSource="https://example.com/test.svg" />
  </Image.Source>
</Image>
```

## Supported features by platform

SVG is supported on all Uno Platform targets.

* On Android, iOS, macOS, and Skia, Uno Platform uses SkiaSharp to render the SVG graphics.
* On WebAssembly, the browser renders the SVG images directly.
* On Windows, the OS is responsible for SVG rendering (and complex SVG files may not render properly).

## When to use SVG

Because SVG requires to be parsed initially before rendering and its vector-based form needs to re-render each time the size of the image changes, it may not be suitable for all scenarios. For ideal performance, we recommend using SVG for in-app vector graphics and icons but prefer bitmap image formats in other cases. In case you run into performance issues, test switching from SVG to a bitmap image format to see if it alleviates the problem. You may also consider using SVG rasterization (see below).

If you need to keep your Android or iOS app package size as small as possible, it is also preferable to avoid using SVG, as the package depends on SkiaSharp.

## SVG rasterization support

For improved performance, you can use the `RasterizePixelHeight` and `RasterizePixelWidth` properties of `SvgImageSource` to rasterize the SVG image when first loaded. When rasterized, the image will always scale this rasterized version of the SVG image instead of rendering the vector-based graphics.

For example:

```xml
<Image Stretch="UniformToFill" Width="100" Height="100">
  <Image.Source>
    <SvgImageSource 
      UriSource="ms-appx:///Assets/couch.svg" 
      RasterizePixelHeight="10" 
      RasterizePixelWidth="10" />
  </Image.Source>
<Image>
```

Will render as:

![Scaled up](../Assets/features/svg/rasterized.png)

> [!NOTE]
> This feature is not available on WebAssembly where the rendering is handled directly by the browser.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/themeresource-internals.md

---
uid: Uno.Contributing.ThemeResource
---

# Theme resource internals for contributors

This article looks at the way theme resources are handled under the hood, including the way that resource assignations are resolved, and the way that assigned resources are updated, for example when the active theme changes in the running application (from light to dark or vice versa). It's aimed at Uno Platform contributors looking to better understand the internals of the feature.

From hereon, an understanding of the contract and consumer-visible behavior of [XAML resources](https://learn.microsoft.com/windows/apps/design/style/xaml-resource-dictionary) and [ThemeResource markup extensions](https://learn.microsoft.com/windows/apps/design/style/xaml-theme-resources) is assumed. Review those links if you need a refresher on how the feature is expected to behave.

## Resource resolution

When a theme resource or static resource assignation is resolved, the framework looks through all ResourceDictionaries that are in scope from the point of assignation, in a defined order, for a resource with a matching key.

### Priority of ResourceDictionaries

Scope and priority are determined by the following rules:

- if the `{ThemeResource}` assignation is itself inside a dictionary, other than inside a template, then the containing dictionary is checked first.
- if the assignation is on a `frameworkElement` or the logical child of a `frameworkElement`, and the `frameworkElement` is in the visual tree, then the `Resources` of the `frameworkElement` and its visual ancestors are checked in order, outwards from the `frameworkElement`. This typically occurs when the element is first loaded into the visual tree, or when the active theme changes (see below).
- the `Application.Resources` dictionary is checked next.
- if the XAML containing the assignation comes from an external assembly (ie, a class library), then next the dictionaries within that assembly are checked. (Note that Uno's behavior departs somewhat from WinUI here, because only the `Themes/Generic.xaml` dictionary from that assembly should be checked - see [issue #4424](https://github.com/unoplatform/uno/issues/4424).)
- finally, 'system level' resources are checked. This simply means the resources that are defined within the Uno.UI assembly.

### Searching within a ResourceDictionary

Resolving a resource within a `ResourceDictionary` is a somewhat complex operation in its own right, because a `ResourceDictionary` may contain nested dictionaries within its `MergedDictionaries` and `ThemeDictionaries` collection properties, those dictionaries may in turn contain dictionaries, and so on recursively. This can be thought of as a 'resource tree' that is traversed in order to find a match for a given resource key.

The matching resource is determined according to the following priority:

- the key-value pairs directly added to the `ResourceDictionary` are considered first.
- ResourceDictionaries in the `MergedDictionaries` collection are searched, in reverse order, in other words the last dictionary added has first priority.
- The `ResourceDictionary` in `ThemeDictionaries` whose key matches the active theme will be searched. This will either be the dictionary whose key exactly matches the active theme (eg "Dark" key when dark theme is active), or the "Default"-keyed dictionary if it exists and no exact match is found. Note that if an exact-match dictionary is found, the "Default" dictionary will be ignored, even if the resource key is not found within the exact-match dictionary.
- finally, if the search was initiated from consumer code, eg via indexing or the public `TryGetValue()` method, then system level resources will be checked, as defined above.

Searching for a resource is a very frequently performed operation and a bottleneck during page loading, and as such is heavily optimized within `ResourceDictionary`, via caching, dedicated internal resource keys, and other mechanisms. It may also be optimized 'outside' `ResourceDictionary` by using a tool to create a single flat merged dictionary out of multiple top-level ControlName.xaml files, which is faster to search (`O(1)`) than many nested MergedDictionaries.

## Resource updates

The resource update machinery can be broadly split into two parts: registering resource assignations for updates; and propagating updates to assigned values when the active theme changes.

### Registering assignations for updates

ThemeResource assignments can only be created in XAML - WinUI provides no way to create them in code. Thus, in Uno, all assignations come ultimately from either [XamlFileGenerator](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator/XamlFileGenerator.cs) or XamlReader/[XamlObjectBuilder](https://github.com/unoplatform/uno/blob/master/src/Uno.UI/UI/Xaml/Markup/Reader/XamlObjectBuilder.cs).

There are 3 cases for ThemeResource assignations that are handled differently:

1. Assigning an ordinary dependency property to a ThemeResource reference.
2. Assigning an ordinary non-dependency property to a ThemeResource reference.
3. Assigning the Value property of a [Setter](https://learn.microsoft.com/uwp/api/windows.ui.xaml.setter) to a ThemeResource reference.

In case 1., we create a `ResourceBinding`, an internal Uno-only type that inherits from `BindingBase`, that binds the property to the ThemeResource, allowing its value to be subsequently reevaluated when the owner enters the live visual tree and also when the active theme changes. This is done through the `ResourceResolver` static class. As much as possible, XAML-generated code should use helper intermediaries that will not change when the underlying implementation evolves. XAML-generated code compiled with older versions of Uno may run against newer Uno versions, in the case of 3rd-party libraries, and we don't want to introduce breaking changes that could be avoided.

In case 2. we can't create a binding because we don't have a dependency property to bind to. The best we can do in this case is to do a one-time resolution of the value.

In case 3., the details of the ThemeResource reference are captured on the `Setter` (via the `ApplyThemeResourceUpdateValues()` extension method). When the setter is later applied, either within a `Style` or within a `VisualState`, then the ThemeResource assignation will be applied according to either case 1. or case 2. depending on whether the target property is a DependencyProperty or not.

In cases 1. and 3., at the time of registration we capture the 'context'. This is an instance of `XamlParseContext`, which captures the assembly in which the ThemeResource reference is declared, and is used to determine the scope which should be used when resolving it.

### Propagating updates on theme change

A theme change update is propagated whenever the active theme changes. This may be because a change in the system theme was detected (eg the user enabled dark mode in their system settings, or perhaps it changed automatically based on the time of day), or because the `RequestedTheme` property on the root element of the visual tree was programmatically changed (eg to support an in-app light/dark mode toggle).

In either case, the `Application.OnResourcesChanged()` method will be called. It will:

1. Update all items in the tree of ResourceDictionaries rooted by `Application.Resources`.
2. Update all items in system resources, ie ResourceDictionaries defined within the Uno.UI assembly.
3. Update all items within the active visual tree.

Cases 1. and 2. are functionally identical, operating on different root dictionaries.

Note that changing the active theme is something that we expect to happen relatively rarely during any given app session, and usually due to explicit user input. The relevant code nonetheless sits alongside and interacts with code paths that are very heavily used during any app session: loading controls, applying bindings, resolving resources etc, which all have an important impact on perceived performance. As much as possible, the theme change machinery has been and should be architected to place its 'performance burden' upon the update itself, rather than the code supporting the update which is called frequently during ordinary activities of the app.

#### Updating resource bindings

Resource bindings are managed by `DependencyObjectStore`. It checks if any properties of its parent instance are resource-bound, by checking if it has a non-empty resource bindings list.

If so, for each binding, it tries to re-resolve the correct theme value from the ResourceDictionaries currently in its scope. If it can, it will then set the value, with the correct precedence as captured when the binding was created.

The `DependencyObjectStore` will also propagate the resource binding update to any 'logical children' that are also DependencyObjects, but not FrameworkElements. (Child FrameworkElements will be updated during the traversal of the visual tree.) For performance reasons, the `DependencyObjectStore` does not explicitly maintain a list of logical children. Instead, the `InnerUpdateChildResourceBindings()` method looks at all current property values and pushes the update to those that are either DependencyObjects or collections of DependencyObjects. In case this is inadequate, it also tries to cast to the `IAdditionalChildrenProvider` internal interface, which allows a type to explicitly specify its logical child dependency objects.

#### Update other FrameworkElement properties

The `FrameworkElement.UpdateThemeBindings()` method is virtual. In addition to updating resource bindings, some controls override it to perform specific updates required when the theme changes. For example, `TextBlock` and `Control` set the default-precedence value of Foreground to the appropriate one for the current theme.

#### Updating 'theme-change-aware' entities

Some non-FrameworkElement types may also need to react to the theme change. This is supported by the `IThemeChangeAware` internal interface, whose `OnThemeChanged()` method is invoked after resource bindings are applied. For example, `Storyboard` implements this interface in order to re-apply long-running animations with the correct updated values.

## Hot reload updates

The ResourceBinding machinery is reused for supporting XAML Hot Reload on standalone ResourceDictionaries. When an application is run in debug with XAML Hot Reload enabled, ResourceBindings are created for all resources assignations, including StaticResource assignations. When a standalone ResourceDictionary XAML file is edited, the file is re-parsed and then an update is triggered in much the same way as if the active theme had changed, so that any modified resources will be reapplied.

To support these different use cases whilst preserving correct semantics, resource bindings have a `ResourceUpdateReason` flag associated them. This ensures that static resources are not updated when they shouldn't be while hot reload is operating.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.themes/refs/heads/master/doc/themes-overview.md

---
uid: Uno.Themes.Overview
---

# Themes Overview

<p align="center">
  <img src="assets/themes-design-systems.png" alt="Themes design systems" />
</p>

## Summary

- [Material Overview](material-getting-started.md)
- [Cupertino Overview](cupertino-getting-started.md)
- [Fluent Overview](fluent-getting-started.md)

## Uno Themes Styles

[Uno Themes](https://github.com/unoplatform/Uno.Themes) is the repository for add-ons NuGet packages that can be added to any new or existing Uno solution.

It contains three libraries:

- `Uno Themes`: a library that contains the base resources, extensions, and helper classes for the different design system libraries
- `Uno Material`: a library that contains styles following the [Material 3](https://m3.material.io/) Design System
- `Uno Cupertino`: a library that contains styles following the [Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines)

Both `Material` and `Cupertino` libraries help you style your application with a few lines of code including:

- Color system for both Light and Dark themes
- Styles for existing WinUI controls like Buttons, TextBox, etc.

## Fluent Controls Styles

Uno Platform 3.0 and above supports control styles conforming to the [Fluent design system](https://www.microsoft.com/design/fluent).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/troubleshooting-memory-issues.md

---
uid: Uno.Contributing.MemoryIssues
---

# Troubleshooting Memory Issues

Uno Platform provides a set of classes aimed at diagnosing memory issues related to leaking controls, whether it be from
an Uno.UI issue or from an invalid pattern in user code.

## WebAssembly memory profiling

Starting from [Uno.Wasm.Bootstrap](https://github.com/unoplatform/Uno.Wasm.Bootstrap) 3.2, the Xamarin Profiler can be used to profile memory usage. See [this documentation](https://github.com/unoplatform/Uno.Wasm.Bootstrap#memory-profiling) for additional details.

## Enable Memory instances counter

1. Install the `Uno.Core` NuGet package;
2. In your application, as early as possible in the initialization (generally in the `App.cs` or `App.xaml.cs` constructor), add and call the following method:

    ```csharp
    using Uno.UI.DataBinding;
    using Uno.UI.DataBinding;
    using System.Threading.Tasks;
    using Uno.Extensions;
    using Uno.Logging;

    // ....
    private void EnableViewsMemoryStatistics()
    {
    //
    // Call this method to enable Views memory tracking.
    // Make sure that you've added the following :
    //
            //  builder.AddFilter("Uno.UI.DataBinding", LogLevel.Information );
    //
    // in the logger settings, so that the statistics are showing up.
    //

    var unused = Windows.UI.Xaml.Window.Current.Dispatcher.RunAsync(
      CoreDispatcherPriority.Normal,
      async () =>
      {
      BinderReferenceHolder.IsEnabled = true;

      while (true)
      {
        await Task.Delay(1500);

        try
        {
        BinderReferenceHolder.LogReport();

        var inactiveInstances = BinderReferenceHolder.GetInactiveViewBinders();

        // Force the variable to be kept by the linker so we can see it with the debugger.
        // Put a breakpoint on this line to dig into the inactive views.
        inactiveInstances.ToString();
        }
        catch (Exception ex)
        {
        this.Log().Error("Report generation failed", ex);
        }
      }
      }
    );
    }
    ```

    You'll also need to add the following logger filter:

    ```csharp
    builder.AddFilter("Uno.UI.DataBinding.BinderReferenceHolder", LogLevel.Information );
    ```

    As well as this package NuGet (you will need to update to the latest Uno.UI nuget version):

    ```xaml
    <PackageReference Include="Uno.UI.Adapter.Microsoft.Extensions.Logging" Version="4.0.13" />
    ```

It is also possible to create diffs between memory snapshots by using the `BinderReferenceHolder.LogInactiveViewReferencesStatsDiff` method.

## Interpreting the statistics output

The output provides two sets of DependencyObject in memory:

- Active, for which the instances have a parent dependency object (e.g. an item in a Grid)
- Inactive, for which the instances do not have a parent dependency object

When doing back and forth navigation between pages, instances of the controls in the dismissed pages should
generally be collected after a few seconds, once those have been cleared from the `Frame` control's forward
stack (done after every new page navigation).

Searching for inactive objects first is generally best, as those instances are most likely kept alive by
cross references.

This can happen when a Grid item has a strong field reference to its parent:

```csharp
var myItem = new Grid(){ Tag = grid };
grid.Children.Add(myItem);
```

For Xamarin.iOS specifically, see [this article about performance tuning](https://learn.microsoft.com/xamarin/ios/deploy-test/performance).

## Profiling on Desktop (Skia)

On the Desktop target, the Visual Studio diagnostic session can be used to investigate application memory to find issues such as memory leaks. Follow [this guide from Microsoft](https://learn.microsoft.com/en-us/visualstudio/profiling/memory-usage-without-debugging2?view=vs-2022&pivots=programming-language-dotnet).

> [!TIP]
> If the "Memory Usage" is not listed under the Available Tools of the Performance Profile. Make sure "YourProjectName (Desktop)" is selected as the target. If that still doesn't work, open the `YourProjectName.csproj` and manually replace the following line temporarily:
>
> ```xml
> <!--<TargetFrameworks>net9.0-android;net9.0-ios;net9.0-browserwasm;net9.0-desktop</TargetFrameworks>-->
> <TargetFrameworks>net9.0-desktop</TargetFrameworks>
> ```
>
> You may need to close and re-open the solution after making the change.

---

> [!TIP]
> During profiling, you may use `GC.Collect()` to forces an immediate GC(Garbage Collection) without having to wait. It should be noted that the GC does not take effect immediately, and sometimes it may take more than one GC call for all loose objects to be collected. For rigorousness, it is recommended to call GC twice and wait a few seconds before taking a memory snapshot when troubleshooting memory leaks.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/troubleshooting-source-generation.md

---
uid: Uno.Contributing.SourceGeneration
---

# Troubleshooting Source Generation

Before Uno 5.0, Source Generation in Uno was done in one of two ways:

- Using [C# 9.0 source generators](https://devblogs.microsoft.com/dotnet/introducing-c-source-generators/)
- Using [Uno.SourceGeneration](https://github.com/unoplatform/uno.sourcegeneration) generators

C# 9.0 generators are enabled automatically when using .NET 5 and up projects, otherwise Uno.SourceGeneration generators are used.

It is possible to enable C# 9.0 generators for non .NET 5+ projects by adding this:

```xml
<PropertyGroup>
  <LangVersion>9.0</LangVersion>
  <UnoUIUseRoslynSourceGenerators>true</UnoUIUseRoslynSourceGenerators>
</PropertyGroup>
```

Conversely, Uno.SourceGeneration generators can be used by setting this:

```xml
<PropertyGroup>
  <UnoUIUseRoslynSourceGenerators>false</UnoUIUseRoslynSourceGenerators>
</PropertyGroup>
```

Starting with Uno 5.0, the only way for source generation is using Roslyn source generators, and setting `UnoUIUseRoslynSourceGenerators` has no effect.

## Adding generated files C# pragma

In some cases, the generated code may use patterns that cause C# to raise warnings, and in order to silence those warnings, the generated code can contain a set of custom C# pragma.

The MSBuild `XamlGeneratorAnalyzerSuppressions` item is used to configure suppressions, with the format `CATEGORY-CODE_TEXT`:

1. Starting with Uno Platform 5.3, the generator will create a `#pragma warning CODE_TEXT` entry at the top of the generated files.
1. Prior to Uno Platform 5.3, the generation depends on the category:

    - If `CATEGORY` is `csharp`, the generator will create a `#pragma warning CODE_TEXT` entry at the top of the generated files
    - If `CATEGORY` is anything else, `SuppressMessageAttribute` attributes will be applied on generated classes.

To define a pragma, in your csproj add the following:

```xml
<ItemGroup>
 <XamlGeneratorAnalyzerSuppressions Include="csharp-618 // Ignore obsolete members warnings" />
</ItemGroup>
```

It is also possible to have `SuppressMessageAttribute` specified in the code, by using the following syntax:

```xml
<ItemGroup>
    <XamlGeneratorAnalyzerSuppressions Include="mycategory.subcategory-CAT0042" />
</ItemGroup>
```

## Debugging the XAML Source Generator

It is possible to step into the XAML generator by adding the following property:

```xml
<PropertyGroup>
  <UnoUISourceGeneratorDebuggerBreak>True</UnoUISourceGeneratorDebuggerBreak>
</PropertyGroup>
```

Setting this property will popup a Debugger window allowing the selection of a visual studio instance, giving the ability to set breakpoints and trace the generator.

## Dumping the XAML Source Generator state

In the context of hot reload or otherwise, troubleshooting the generator's state may be useful.

Using this feature, the generator will dump the following for **each** run:

- CommandLine arguments
- MSBuild properties
- MSBuild items
- Generated source files

To enable this feature, add the following property:

```xml
<PropertyGroup>
  <XamlSourceGeneratorTracingFolder>path_to_folder</XamlSourceGeneratorTracingFolder>
</PropertyGroup>
```

> [!WARNING]
> A lot of data may be generated in some cases, make sure to disable this feature once it is no longer needed and don't forget to cleanup.

## Troubleshooting Uno.SourceGeneration based generation

When building, if you're having build error messages that looks like one of those:

- `the targets [Microsoft.Build.Execution.TargetResult] failed to execute.`
- `error : Project has no references.`

There may be issues with the analysis of the project's source or configuration.

**Security notice: That `binlog` files produced below should never be published in a public location, as they may contain private information, such as source files. Make sure to provide those in private channels after review.**

The Source Generation tooling diagnostics can be enabled as follows:

- In the project file that fails to build, in the first `PropertyGroup` node, add the following content:

    ```xml
    <UnoSourceGeneratorUnsecureBinLogEnabled>true</UnoSourceGeneratorUnsecureBinLogEnabled>
    ```

- Make to update or add the `Uno.SourceGenerationTasks` to the latest version
- When building, in the inner `obj` folders, a set of `.binlog` files are generated that can be opened with the [msbuild log viewer](http://msbuildlog.com/) and help the troubleshooting of the generation errors.
- Once you've reviewed the files, you may provide those as a reference for troubleshooting to the Uno maintainers.
- The best way to provide those file for troubleshooting is to make a zip archive of the whole solution folder without cleaning it, so it contains the proper diagnostics `.binlog` files.

**Make sure to remove the `UnoSourceGeneratorUnsecureBinLogEnabled` property once done.**

If ever the need arises to view the generated source code of a *failing* CI build, you can perform the following steps:

1. In your local branch, locate the one of build yaml files (located in the root Uno folder):
     - `.azure-devops-android-tests.yml`
     - `.azure-devops-wasm-uitests.yml`

2. At the bottom of the yaml files, you'll find *Publish...* tasks, right above these tasks, copy/paste the following code to create a task which will copy all generated source files and put them in an artifact for you to download:

    ```yml
    - bash: cp -r $(build.sourcesdirectory)<YourProjectDirectory>/obj/Release/g/XamlCodeGenerator/ $(build.artifactstagingdirectory)
        condition: failed()
        displayName: "Copy generated XAML code"
    ```

    Therefore, in the case of Uno, an example of <YourProjectDirectory> would be */src/SamplesApp/SamplesApp.Droid*.

3. Once the build fails and completes, you can download the corresponding build artifact from the Artifacts menu to view your generated source files.

**Remember that you should never submit this change, this is temporary and only for viewing generated code.**

## Xaml fuzzy matching

The XAML source generator used to do fuzzy matching for types. This doesn't match Windows behavior and can cause performance issues. The MSBuild property `UnoEnableXamlFuzzyMatching` controls whether fuzzy matching is enabled or not. The property was introduced in Uno 4.8 and defaulted to `true`. Starting with Uno 5.0, this property defaults to `false`. It is planned that fuzzy matching will be removed completely Uno 6.

Note that for XAML-included namespaces (for example `android`, `ios`, etc.), The default namespaces are used (it's considered as if it is `http://schemas.microsoft.com/winfx/2006/xaml/presentation`).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/tutorials-intro.md

---
uid: Uno.Tutorials.Intro
---

# How-tos and tutorials

This section gathers how-tos and longer tutorials that will show you how to use Uno Platform and solve specific problems.

[!include[Inline table of contents](includes/how-tos-and-tutorials-inline-toc.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/unhandled-exceptions.md

---
uid: Uno.Development.UnhandledExceptions
---

# Generic Unhandled Exceptions handler

Starting Uno Platform 5.4, we are generating a generic handler for `Application.UnhandledException`, in line with WinUI approach. When debugger is attached, unhandled framework exceptions will be logged in the debugger output by default. If you also want the debugger to break on unhandled exceptions, set the `BreakOnUnhandledExceptions` property to `true` in the `.csproj`:

```xml
<PropertyGroup>
  <BreakOnUnhandledExceptions>true</BreakOnUnhandledExceptions>
</PropertyGroup>
```

If you want to disable the generated `Application.UnhandledException` handler altogether, define the `DISABLE_GENERATED_UNHANDLED_EXCEPTION_HANDLER` constant in `.csproj` instead:

```xml
<PropertyGroup>
  <DefineConstants>$(DefineConstants);DISABLE_GENERATED_UNHANDLED_EXCEPTION_HANDLER</DefineConstants>
</PropertyGroup>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-app-solution-structure.md

---
uid: Uno.Development.AppStructure
---

# Solution Structure

This guide briefly explains the structure of an app created with either the [`dotnet new unoapp` template](xref:Uno.GetStarted.dotnet-new) or the [Uno Platform Template Wizard](xref:Uno.GettingStarted.UsingWizard). It is particularly aimed at developers who have not worked with cross-platform codebases before.

## The project files in an Uno Platform app

After creating a new blank solution called `MyApp`, it will contain the following project:

![Uno Platform solution structure](Assets/solution-structure.png)

The `MyApp.csproj` project supports Mobile (iOS/Android), WebAssembly, Desktop (macOS, Linux X11/Framebuffer, Windows 7+), and Windows App SDK targets.

You'll find below details about the contents of the solution.

### Platforms

The Platforms folder contains platform specific files for targets supported by Uno Platform:

- `Desktop` uses the [Uno Platform Skia Desktop](xref:Uno.Features.Uno.Sdk) support for Windows 7+, Linux, and macOS
- `Android` contains files and assets specific to Android Phones, Tablets, TVs, and watches
- `iOS` targets Apple's iOS devices, Phones, and Tablets
- `WebAssembly` targets the browser using WebAssembly
- `Windows` targets the [Windows App SDK](https://developer.microsoft.com/en-us/windows/downloads/windows-sdk/) to run on Windows

### Properties

This folder contains the debug profile configuration. This is used to choose where to debug your Skia Desktop app (Local Windows or WSL), the Web Server for your WebAssembly app, or Package and Unpackaged modes for Windows App SDK.

### Assets

This folder contains [all the assets](xref:Uno.Features.Assets) (images, splash screens, data, ...) that are published as part of the app.

## Other project files

- `App.xaml` and `App.xaml.cs` are the common entry point for the app. The generic app setup runtime code generally goes here.
- `MainPage.xaml` and `MainPage.xaml.cs` contain the main UI of the app.
- `GlobalUsings.cs` contains the [global usings](https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/keywords/using-directive#global-modifier) define for the project.
- `app.manifest` contains [Windows specific configuration](https://learn.microsoft.com/en-us/windows/win32/sbscs/application-manifests) for `net9.0-desktop` and `net9.0-windows` targets.
- `Package.appxmanifest` contains metadata about the application such as the app name and description.

### Solution items

This solution folder contains the configuration for the whole solution:

- `global.json` contains the [.NET SDK configuration](https://learn.microsoft.com/en-us/dotnet/core/tools/global-json) as well as the Uno.Sdk version to use. See [our documentation](xref:Uno.Features.Uno.Sdk) on how to update it.
- `Directory.Build.props` and `Directory.Build.targets` contain common solution configurations applied to all projects.
- `Directory.Packages.props` contains the [NuGet Central Package Management](https://learn.microsoft.com/en-us/nuget/consume-packages/Central-Package-Management) package versions.

## Further information

See additional guides on handling platform-specific [C# code](xref:Uno.Development.PlatformSpecificCSharp) and [XAML markup](xref:Uno.Development.PlatformSpecificXaml) in an Uno Platform project.

## Next Steps

Learn more about:

- [Uno Platform features and architecture](xref:Uno.GetStarted.Explore)
- [Hot Reload feature](xref:Uno.Features.HotReload)
- [Troubleshooting](xref:Uno.UI.CommonIssues)
- [List of views implemented in Uno](implemented-views.md) for the set of available controls and their properties.
- You can head to [How-tos and tutorials](xref:Uno.Tutorials.Intro) on how to work on your Uno Platform app.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-build-error-codes.md

---
uid: Build.Solution.error-codes
---
# Uno error codes

## MSBuild Errors

### UNOB0001: Cannot build with both Uno.WinUI and Uno.UI NuGet packages referenced

This error code means that a project has determined what both `Uno.WinUI` and `Uno.UI` packages are referenced.

To fix this issue, you may be explicitly referencing `Uno.UI` and `Uno.WinUI` in your `csproj`, or you may be referencing a NuGet package that is incompatible with your current project's configuration.

For instance, if your project references `Uno.WinUI`, and you try to reference `SkiaSharp.View.Uno`, you will get this error. To fix it, you'll need to reference `SkiaSharp.View.Uno.WinUI` instead.

### UNOB0002: Project XX contains a reference to Uno Platform but does not contain a WinAppSDK compatible target framework

This error code means that a WinAppSDK project is referencing a project in your solution which is not providing a `net7.0-windows10.xx` TargetFramework.

This can happen if a project contains only a `net7.0` TargetFramework and has a NuGet reference to `Uno.WinUI`.

To fix this, it is best to start from a `Cross Platform Library` project template provided by the Uno Platform [visual studio extension](xref:Guide.HowTo.Create-Control-Library), or using [`dotnet new`](xref:Uno.GetStarted.dotnet-new).

### UNOB0003: Ignoring resource XX, could not determine the language

This error may occur during resources (`.resw`) analysis if the framework does not recognize the specified language code.

For instance, the language code `zh-CN` is not recognized and `zh-Hans` should be used instead.

### UNOB0004: The $(UnoVersion) property must match the version of the Uno.Sdk defined in global.json

The build process has determined that an MSBuild property was defined to override `UnoVersion`. This property is defined by the Uno.Sdk and cannot be changed and must be updated through the `global.json` file

Follow this guide in order to [update the Uno Platform packages](xref:Uno.Development.UpgradeUnoNuget).

### UNOB0005: The Version of Uno.WinUI must match the version of the Uno.Sdk found in global.json

The build process has determined that the version of the Uno.WinUI NuGet package does not match the Uno.Sdk version. In general, restarting your IDE and compiling again will fix this issue.

Follow this guide in order to [update the Uno Platform packages](xref:Uno.Development.UpgradeUnoNuget).

### UNOB0006: The UnoFeature 'XX' was selected, but the property XXXVersion was not set

The build process has determined that you have specified an UnoFeature that requires a version to be set for a Package group such as Uno.Extensions, Uno.Toolkit.WinUI, Uno Themes, or C# Markup. Update your `csproj` file or `Directory.Build.props` with the property specified in the error along with the version that you would like to pin your build to.

### UNOB0007: AOT compilation is only supported in Release mode. Please set the 'Optimize' property to 'true' in the project file

The build process has detected that you have set the value `UnoGenerateAotProfile` to true for a build configuration that has not optimized the assembly (i.e. Debug build Configuration). You should only generate an AOT profile from a build Configuration that will optimize the assembly such as the Release build Configuration.

### UNOB0008: Building a WinUI class library with dotnet build is not supported

Building a `net8.0-windows10.x.x` class library using `dotnet build` is not supported at this time because of a [Windows App SDK issue](https://github.com/microsoft/WindowsAppSDK/issues/3548), when the library contains XAML files.

To work around this, use `msbuild /r` on Windows. You can build using `msbuild` with a **Developer Command Prompt for VS 2022** (or 2026), or by using `vswhere` or using [GitHub actions scripts](https://learn.microsoft.com/en-us/windows/apps/package-and-deploy/ci-for-winui3?pivots=winui3-packaged-csharp) in a CI environment.

This particular check can be disabled by setting the msbuild property `UnoDisableValidateWinAppSDK3548` to `true`.

### UNOB0009: Uno Platform Implicit Package references are enabled

When Uno Implicit Package References are enabled you do not need to provide an explicit PackageReference for the Packages listed in the build message. You should open the csproj file, find and remove the `<PackageReference Include="{Package name}" />` as listed in the build message.

Alternatively you may disable the Implicit Package References

```xml
<PropertyGroup>
  <DisableImplicitUnoPackages>true</DisableImplicitUnoPackages>
</PropertyGroup>
```

### UNOB0010: The browserwasm TargetFramework must not be placed first in the TargetFrameworks property

In Visual Studio 2022/2026, [an issue](https://aka.platform.uno/singleproject-vs-reload) prevents debugging and Hot Reload from working properly for all targets when the `net8.0-browserwasm` TargetFramework is placed first in the `TargetFrameworks` property.

Make sure to place `net8.0-browserwasm` last in your `<TargetFrameworks>` property.

This warning can be disabled by adding the following to your `.csproj`:

```xml
<PropertyGroup>
  <UnoDisableVSWarnBrowserNotFirst>true</UnoDisableVSWarnBrowserNotFirst>
</PropertyGroup>
```

### UNOB0011: The desktop TargetFramework must be placed first in the TargetFrameworks property

In Visual Studio 2022/2026, [an issue](https://aka.platform.uno/singleproject-vs-reload) prevents other platforms debugging from working properly when the `net8.0-desktop` TargetFramework is placed first in the `TargetFrameworks` property.

Make sure to place `net8.0-desktop` first in your `<TargetFrameworks>` property.

This warning can be disabled by adding the following to your `.csproj`:

```xml
<PropertyGroup>
  <UnoDisableVSWarnDesktopNotFirst>true</UnoDisableVSWarnDesktopNotFirst>
</PropertyGroup>
```

### UNOB0012: The windows TargetFramework must not be placed first in the TargetFrameworks property

In Visual Studio 2022/2026, [an issue](https://aka.platform.uno/singleproject-vs-reload) prevents other platforms debugging from working properly when the `net8.0-windows10.xxx` TargetFramework is placed first in the `TargetFrameworks` property.

Make sure that `net8.0-windows10.xxx` is not first in your `<TargetFrameworks>` property.

This warning can be disabled by adding the following to your `.csproj`:

```xml
<PropertyGroup>
  <UnoDisableVSWarnWindowsIsFirst>true</UnoDisableVSWarnWindowsIsFirst>
</PropertyGroup>
```

### UNOB0013: The net8.0 TargetFramework must not be placed first in the TargetFrameworks property

In Visual Studio 2022/2026, [an issue](https://aka.platform.uno/singleproject-vs-reload) prevents other platforms debugging from working properly when the `net8.0` TargetFramework is placed first in the `TargetFrameworks` property.

Make sure that `net8.0` is not first in your `<TargetFrameworks>` property.

This warning can be disabled by adding the following to your `.csproj`:

```xml
<PropertyGroup>
  <UnoDisableVSWarnNetIsFirst>true</UnoDisableVSWarnNetIsFirst>
</PropertyGroup>
```

### UNOB0014: The target framework is not supported on macOS or Linux

When building with Rider on Linux or macOS, unsupported target frameworks are [not filtered automatically like other IDEs](https://youtrack.jetbrains.com/issue/RIDER-114790/Unsupported-target-framework-filtering).

See how to [make platforms conditional](xref:Uno.GettingStarted.CreateAnApp.Rider#considerations-for-macos-and-linux) for Rider.

### UNOB0015: The desktop TargetFramework must be placed first

In Visual Studio 17.13 or earlier, when both mobile (`-ios`, `-android`) and `desktop` target frameworks are used, the `-desktop` target framework must be placed first in order for WSL debugging to work.

If `-desktop` is not first, the following message will appear:

```text
The project doesn't know how to run the profile with name 'MyApp (Desktop WSL2)' and command 'WSL2'.
```

To fix the issue, reorder the items in your `.csproj` so that `TargetFrameworks` contains `netX.0-desktop` as the first target framework, or upgrade to Visual Studio 17.13 (when a stable release will be available).

The Uno Platform team is following this [Visual Studio issue](https://developercommunity.visualstudio.com/t/WSL-launch-profile-cannot-be-found-when/10776961).

### UNOB0016: The Publish Profile file must not contain the "PublishDir"

When publishing an app using ClickOnce on Windows, the `PublishProfile` file may not contain a `PublishDir` entry if the command line parameter `UnoClickOncePublishDir` has been set.

This situation is due to an MSBuild property overriding bug found in the .NET SDK. For more information, see our [publishing with ClickOnce](xref:uno.publishing.desktop#windows-clickonce) documentation.

### UNOB0017: A reference to either Uno.WinUI.Runtime.WebAssembly or Uno.WinUI.WebAssembly has been detected

When the `SkiaRenderer` feature is enabled, the `Uno.WinUI.Runtime.WebAssembly` and `Uno.WinUI.WebAssembly` packages must not be referenced directly.

This is generally a package authoring error, make sure to open an issue in the Uno Platform repository to report the problem.

### UNOB0018: Code signing cannot be applied on files with extended attributes (e.g. iCloud)

On macOS code signing will fail if the project's output is located inside a directory that is backed up using [iCloud](https://www.icloud.com). This is because iCloud adds some extended attributes to files and directories while `codesign` will refuse to sign such files.

ref: https://developer.apple.com/library/archive/qa/qa1940/_index.html

Solution: Move your Uno solution/project(s) to a different location, one that is not backed up by iCloud.

## Compiler Errors

### UNO0001

A member is not implemented, see [this page](xref:Uno.Development.NotImplemented) for more details.

### UNO0002

**Do not call Dispose() on XXX**

On iOS, calling `Dispose()` or `Dispose(bool)` on a type inheriting directly from `UIKit.UIView` can lead to unstable results. It is not needed to call `Dispose` as the runtime will do so automatically during garbage collection.

Invocations to `Dispose` can cause the application to crash in `__NSObject_Disposer drain`, causing `ObjectDisposedException` exception to be thrown. More information can be found in [xamarin/xamarin-macios#19493](https://github.com/xamarin/xamarin-macios/issues/19493).

### UNO0006

**Call 'InitializeComponent()' from code-behind**

The method `InitializeComponent` should always be called in class constructor. A missing call will lead to hard-to-diagnose bugs. This analyzer reports when it's missing to make issues more apparent.

### UNO0007

**An assembly required for a component is missing**

Some components like `ProgressRing` and `MediaPlayerElement` requires you to reference a specific NuGet package for them to work correctly.

- For `ProgressRing`, it requires Lottie dependency. For more information about adding Lottie to your project, see [Lottie for Uno](xref:Uno.Features.Lottie).
- For `MediaPlayerElement` on WebAssembly or Gtk, it requires `Uno.WinUI.MediaPlayer.WebAssembly` or `Uno.WinUI.MediaPlayer.Skia.Gtk` NuGet package. For more information, see [MediaPlayerElement](xref:Uno.Controls.MediaPlayerElement).

### UNO0008

In Uno Platform 5.5, the `EnableHotReload` method has been deprecated and replaced by `UseStudio()`.

Note that this change only applies to projects using the Uno.Sdk. If you're not using the Uno.Sdk, you can disable this warning using the following code:

```xml
#pragma warning disable UNO0008 // Replace with UseStudio() when migrating to the Uno.Sdk.
window.EnableHotReload();
#pragma warning restore UNO0008
```

## XAML Errors

### UNOX0001

The `ProgressRing` control [needs an additional Lottie](xref:Uno.Features.Lottie) dependency to be enabled.

## VS Code Errors

### UVSC0001

Building for the specified target framework is not supported on the current platform or architecture. For example:

- A Mac computer is required to build iOS and macOS applications
- A Windows computer is required to build WinUI applications

### UVSC0002

Building WinUI applications requires the use of `msbuild` and the extension must be able to find it. This is done by using the `vswhere` utility.

Installing the latest stable Visual Studio release should provide both tools.

With version 0.14 (and later) you can override the location of `msbuild.exe` by:

1. Opening the **Settings** using `Ctrl`+`,`
1. Searching for `msbuild`
1. Setting the location where your `msbuild.exe` is located

![settings](Assets/quick-start/vs-code-settings-msbuild.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-builds-troubleshooting.md

---
uid: Uno.Development.Troubleshooting
---

# Troubleshooting build issues

## Diagnose environment problems with `uno-check`

If you're not sure whether your environment is correctly configured for Uno Platform development, running the [`uno-check` command-line tool](https://www.nuget.org/packages/Uno.Check) should be your first step. Find installation instructions and other details in the [using uno-check guide](external/uno.check/doc/using-uno-check.md).

## Multi-targeting considerations

Uno Platform projects use multi-targeting, for which each target framework has to be built individually, for some errors to disappear from the **Error List** window (notice the **Project** column values).
In order to clear the **Error List** window, build the whole solution completely once.
Subsequently, build a specific project and prefer the use of the **Output** tool window (in the menu **View** -> **Output**), taking build messages by order of appearance.

## Troubleshooting build errors using the build Output Window

To troubleshoot build error, you can change the text output log level:

- Go to **Tools**, **Options**, **Projects and Solution**, then **Build and Run**
- Set **MSBuild project build output verbosity** to **Normal** or **Detailed**
- Build your project again and take a look at the additional output

## Generating MSBuild Binary Log files

If you have trouble building your project, you can get additional information using binary log (binlog) files.

**Important: Note that binlog files contain environment variables and csproj files used to build the sources, but not the source files themselves.**
Make sure to review the content of the file for sensitive information before posting it on a public issue, otherwise contact us on Discord for additional information to send us the build logs.**

### From Visual Studio

To use MSBuild binary logs:

- Go to **Tools**, **Options**, **Projects and Solution**, then **Build and Run**
- Set **MSBuild project build log verbosity** to **Detailed** or **Diagnostics**
- Install the [MSBuild log viewer](http://msbuildlog.com/)
- Install the [Project System Tools for VS 2022](https://marketplace.visualstudio.com/items?itemName=VisualStudioProductTeam.ProjectSystemTools2022) or [VS 2019](https://marketplace.visualstudio.com/items?itemName=VisualStudioProductTeam.ProjectSystemTools) add-in
- Open **View** > **Other Windows** > **Build Logging**, then click the green play button
- Build your project again and right click the **Failed** build entry in the **Build Logging** tool window.
- The binlog viewer tool will expand to the detailed build error

### From the command line

You may be asked to generate a binlog from the command line, as it includes more information (the project structure, but not the source files) that can help troubleshoot issues.

To generate a binlog file from the command line:

- Open a :
  - [Visual Studio Developer command prompt](https://learn.microsoft.com/visualstudio/ide/reference/command-prompt-powershell) on Windows
  - A terminal window on Linux or macOS
- Navigate to the folder of the project head
- For WinUI/iOS/Android/macOS projects, type the following:

  ```bash
  msbuild /r /bl MyProject.csproj
  ```

- For other targets (.NET 5+, WebAssembly, Skia, etc...)

  ```dotnetcli
  dotnet build /bl MyProject.csproj
  ```

- Once the build has finished, a file named `msbuild.binlog` is generated next to the `.csproj` file.

## Common Build errors troubleshooting

You can also browse the [common issues list](xref:Uno.UI.CommonIssues.AllIDEs) for build errors and their resolutions.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-community-toolkit-v7.md

---
uid: Uno.Development.CommunityToolkit.v7
---

# How to use Windows Community Toolkit - Version 7.x

This tutorial will walk you through adding and implementing the `DataGrid` control but the same steps can be followed for **other\*** Uno ported Windows Community Toolkit controls versions 7.x.

**\* See the [non-Windows platform compatibility](xref:Uno.Development.CommunityToolkit#non-windows-platform-compatibility) section for more details.**

> [!NOTE]
> The complete source code that goes along with this guide is available in the [unoplatform/Uno.Samples](https://github.com/unoplatform/Uno.Samples) GitHub repository - [`DataGrid` Sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-7.x/UnoWCTDataGridSample).

## Prerequisites

For a step-by-step guide to installing the prerequisites for your preferred IDE and environment, consult the [Get Started guide](xref:Uno.GetStarted).

> [!TIP]
> If you are unsure of the version of the Windows Community Toolkit to use between v7 and v8, make sure to read the details about the [migration guide](xref:Uno.Development.CommunityToolkit).

## NuGet Packages for Uno Platform

Uno Platform has ported the Windows Community Toolkit 7.x for use in Uno Platform applications to allow for use on Windows,
Android, iOS, Linux, and WebAssembly.

The following packages are available:

- [Uno.CommunityToolkit.WinUI](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI)
- [Uno.CommunityToolkit.WinUI.Connectivity](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.Connectivity)
- [Uno.CommunityToolkit.WinUI.DeveloperTools](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.DeveloperTools)
- [Uno.CommunityToolkit.WinUI.UI](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI)
- [Uno.CommunityToolkit.WinUI.UI.Animations](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Animations)
- [Uno.CommunityToolkit.WinUI.UI.Behaviors](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Behaviors)
- [Uno.CommunityToolkit.WinUI.UI.Controls](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Controls)
- [Uno.CommunityToolkit.WinUI.UI.Controls.Core](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Controls.Core)
- [Uno.CommunityToolkit.WinUI.UI.Controls.DataGrid](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Controls.DataGrid)
- [Uno.CommunityToolkit.WinUI.UI.Controls.Input](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Controls.Input)
- [Uno.CommunityToolkit.WinUI.UI.Controls.Layout](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Controls.Layout)
- [Uno.CommunityToolkit.WinUI.UI.Controls.Markdown](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Controls.Markdown)
- [Uno.CommunityToolkit.WinUI.UI.Controls.Media](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Controls.Media)
- [Uno.CommunityToolkit.WinUI.UI.Controls.Primitives](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Controls.Primitives)
- [Uno.CommunityToolkit.WinUI.UI.Media](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI.Media)

These package IDs are for Uno Platform (non-Windows) projects. For WinUI 3 projects, you should use the equivalent packages published by Microsoft (`CommunityToolkit.WinUI`, `CommunityToolkit.WinUI.UI.Controls`, etc).

## Referencing the Windows Community Toolkit

When using the Uno Platform solution templates, add the following to your application:

1. Install the NuGet package(s) reference(s) that you need

    ### [Single Project Template [WinUI / WinAppSDK]](#tab/singleproj)

    1. Edit your project file `PROJECT_NAME.csproj` and add the following conditional references:

        ```xml
        <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
          <PackageReference Include="CommunityToolkit.WinUI.UI.Controls" />
          <!-- Add more community toolkit references here -->
        </ItemGroup>
        <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'windows'">
          <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls" />
          <!-- Add more uno community toolkit references here -->
        </ItemGroup>
        ```

        If you already had a reference to the Community Toolkit, you should remove this line:

        ```xml
        <ItemGroup>
          <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls" />
        </ItemGroup>
        ```

    1. Edit `Directory.Packages.props` and add the following conditional references:

        ```xml
        <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
          <PackageVersion Include="CommunityToolkit.WinUI.UI.Controls" Version="7.1.2" />
          <!-- Add more community toolkit references here -->
        </ItemGroup>
        <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'windows'">
          <PackageVersion Include="Uno.CommunityToolkit.WinUI.UI.Controls" Version="7.1.200" />
          <!-- Add more uno community toolkit references here -->
        </ItemGroup>
        ```

    ### [Multi-Head Project Template (Legacy) [WinUI / WinAppSDK]](#tab/multihead-winui)

    Edit your project file `PROJECT_NAME.csproj` and add the following conditional references:

    ```xml
    <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'windows'">
      <PackageReference Include="CommunityToolkit.WinUI.UI.Controls" Version="7.1.2" />
      <!-- Add more community toolkit references here -->
    </ItemGroup>
    <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) != 'windows'">
      <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls" Version="7.1.200" />
      <!-- Add more uno community toolkit references here -->
    </ItemGroup>
    ```

    If you already had a reference to the Community Toolkit, you should remove this line:

    ```xml
    <ItemGroup>
      <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls" Version="7.1.200" />
    </ItemGroup>
    ```

    ### [Shared Project (.shproj) Template (Legacy) [WinUI / WinAppSDK]](#tab/shproj-winui)

    1. Select the following project `PROJECT_NAME.Windows.csproj` for installation and add the following reference:

        ```xml
        <ItemGroup>
          <PackageReference Include="CommunityToolkit.WinUI.UI.Controls" Version="7.1.2" />
          <!-- Add more community toolkit references here -->
        </ItemGroup>
        ```

    1. Select the following projects for installation and add the following reference to each of them:
        - `PROJECT_NAME.Wasm.csproj`
        - `PROJECT_NAME.Mobile.csproj` (or `PROJECT_NAME.iOS.csproj`, `PROJECT_NAME.Droid.csproj`, and `PROJECT_NAME.macOS.csproj` if you have an existing project)
        - `PROJECT_NAME.Skia.Gtk.csproj`
        - `PROJECT_NAME.Skia.WPF.csproj`

        ```xml
        <ItemGroup>
          <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls" Version="7.1.200" />
          <!-- Add more uno community toolkit references here -->
        </ItemGroup>
        ```

        If you already had a reference to the Community Toolkit, you should remove this line:

        ```xml
        <ItemGroup>
          <PackageReference Include="Uno.CommunityToolkit.WinUI.UI.Controls" Version="7.1.200" />
        </ItemGroup>
        ```

    ---

    If you're getting an error like this one :

    ```console
    Controls\TextBox\Themes\Generic.xaml : Xaml Internal Error error WMC9999: 
    Type universe cannot resolve assembly: Uno.UI, Version=255.255.255.255, 
    Culture=neutral, PublicKeyToken=null.
    ```

    This means that there's an unconditional reference to Uno Platform's packages, and you'll need to make sure to add the conditional references as suggested above.

1. Add the the related needed namespaces

      In XAML:  
        ```xmlns:controls="using:CommunityToolkit.WinUI.UI.Controls"```

      In C#:  
        ```using CommunityToolkit.WinUI.UI.Controls;```

## Example with the DataGrid Control

This control will create an easily organized grid that will allow you to create flexible columns and rows.

1. Begin by adding the control using the syntax below. Change the `x:Name` to the name of your DataGrid.  
```<controls:DataGrid x:Name="dataGrid"></controls:DataGrid>```

2. Similar to how you would configure columns for a XAML `Grid` layout, you can add column definitions within your `DataGrid` control:

    ```xml
    <controls:DataGrid.Columns>
        <controls:DataGridTextColumn Header="Rank"/>
        <controls:DataGridComboBoxColumn Header="Mountain"/>
    </controls:DataGrid.Columns>
    ```

    This will create two columns that can be adjusted by the user.
    ![datagrid-column-gif](Assets/datagrid-basic-columns.gif)

    Alternatively, you can use the `AutoGenerateColumns` attribute on your `DataGrid` control if you do not know how many columns your data will require.  

    ```xml
    <controls:DataGrid x:Name="dataGrid" AutoGenerateColumns="True" />
    ```

3. Format your rows in the same way as your columns or use a `DataTemplate` added as an attribute on the `DataGrid` control:

    ```xml
    <controls:DataGrid x:Name="dataGrid" RowDetailsTemplate="{StaticResource RowDetailsTemplate}">
    ```

4. Data can be added with data binding. First, add your `ItemsSource` as a property of your `DataGrid` control.  

    ```xml
    <controls:DataGrid x:Name="dataGrid" ItemsSource="{x:Bind MyViewModel.Customers}" />  
    ```

    Then, set the binding on each column:

    ```xml
    <controls:DataGrid.Columns>
        <controls:DataGridTextColumn Header="Rank" Binding="{Binding Rank}" Tag="Rank" />
        <controls:DataGridTextColumn Header="Mountain" Binding="{Binding Mountain}" Tag="Mountain" />
    </controls:DataGrid.Columns>
    ```

### See a working example with data

![datagrid-full-sample](Assets/datagrid-full-sample.gif)

A complete working sample with data is available on GitHub: [Uno Windows Community Toolkit DataGrid Sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-7.x/UnoWCTDataGridSample)

---

[!include[getting-help](includes/getting-help.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-community-toolkit-v8.md

---
uid: Uno.Development.CommunityToolkit.v8
---

# How to use Windows Community Toolkit - Version 8.x

This tutorial will walk you through adding and implementing the `SettingsCard` control but the same steps can be followed for **other\*** Windows Community Toolkit controls version 8.x.

**\* See the [non-Windows platform compatibility](xref:Uno.Development.CommunityToolkit#non-windows-platform-compatibility) section for more details.**

> [!NOTE]
> The complete source code that goes along with this guide is available in the [unoplatform/Uno.Samples](https://github.com/unoplatform/Uno.Samples) GitHub repository - [`SettingsCard` Sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-8.x/UnoWCTSettingsCardSample)

## Prerequisites

For a step-by-step guide to installing the prerequisites for your preferred IDE and environment, consult the [Get Started guide](xref:Uno.GetStarted).

> [!TIP]
> If you are unsure of the version of the Windows Community Toolkit to use between v7 and v8, make sure to read the details about the Windows Community Toolkit [migration guide](xref:Uno.Development.CommunityToolkit).

## NuGet Packages

Uno Platform is now supported out of the box by the Windows Community Toolkit and Windows Community Toolkit Labs starting with version 8.x.

> [!IMPORTANT]
> If you are already using Windows Community Toolkit version 7.x in your Uno Platform project and want to update to version 8.x, note that Uno Platform has its [own fork](https://github.com/unoplatform/Uno.WindowsCommunityToolkit) of the Windows Community Toolkit for [version 7.x](xref:Uno.Development.CommunityToolkit.v7).
>
> In your project, these Windows Community Toolkit Uno packages were referenced behind a conditional to allow for use on Windows, Android, iOS, Linux, and WebAssembly.
>
> Conditional references are no longer necessary with version 8.x, you can remove the Uno Windows Community Toolkit references and all `Condition` statements around the packages.

## Referencing the Windows Community Toolkit

When using the Uno Platform solution templates, add the following to your application:

1. Install the NuGet package(s) reference(s) that you need

    ### [Single Project Template [WinUI / WinAppSDK]](#tab/singleproj)

    1. Edit your project file `PROJECT_NAME.csproj` and add the needed reference(s):

        ```xml
        <ItemGroup>
          <PackageReference Include="CommunityToolkit.WinUI.Controls.SettingsControls" />
          <!-- Add more community toolkit references here -->
        </ItemGroup>
        ```

    1. Edit `Directory.Packages.props` and add the needed reference(s):

        ```xml
        <ItemGroup>
          <PackageVersion Include="CommunityToolkit.WinUI.Controls.SettingsControls" Version="8.1.240916" />
          <!-- Add more community toolkit references here -->
        </ItemGroup>
        ```

    > [!NOTE]
    > Windows Community Toolkit version 8.x requires an update to Windows SDK **10.0.22621** and above, along with [Microsoft.WindowsAppSDK](https://www.nuget.org/packages/Microsoft.WindowsAppSDK) updated to the latest matching version.
    >
    > To override these versions within a single project structure, you can set the properties in the `Directory.Build.props` file or directly in your project's `csproj` file. For more detailed information, please see the [implicit packages details](xref:Uno.Features.Uno.Sdk#implicit-packages).
    >
    > For example, in `PROJECT_NAME.csproj`:
    >
    > ```xml
    > <TargetFrameworks>
    >   <!-- Code for other TargetFrameworks omitted for brevity -->
    >   net9.0-windows10.0.22621;
    > </TargetFrameworks>
    > ```
    >
    > ```xml
    > <PropertyGroup>
    >   <WindowsSdkPackageVersion>10.0.22621.38</WindowsSdkPackageVersion>
    >   <WinAppSdkVersion>1.5.240607001</WinAppSdkVersion>
    > </PropertyGroup>
    > ```

    ### [Multi-Head Project Template (Legacy) [WinUI / WinAppSDK]](#tab/multihead-winui)

    Edit your project file `PROJECT_NAME.csproj` and add the needed reference(s):

    ```xml
    <ItemGroup>
      <PackageReference Include="CommunityToolkit.WinUI.Controls.SettingsControls" Version="8.1.240916" />
      <!-- Add more community toolkit references here -->
    </ItemGroup>
    ```

    > [!NOTE]
    > Windows Community Toolkit version 8.x requires an update to Windows SDK **10.0.22621** and above, along with [Microsoft.WindowsAppSDK](https://www.nuget.org/packages/Microsoft.WindowsAppSDK) updated to the latest matching version.

    ### [Shared Project (.shproj) Template (Legacy) [WinUI / WinAppSDK]](#tab/shproj-winui)

    1. Select the following projects for installation and add the needed reference(s) to each of them:
        - `PROJECT_NAME.Windows.csproj`
        - `PROJECT_NAME.Wasm.csproj`
        - `PROJECT_NAME.Mobile.csproj` (or `PROJECT_NAME.iOS.csproj`, `PROJECT_NAME.Droid.csproj`, and `PROJECT_NAME.macOS.csproj` if you have an existing project)
        - `PROJECT_NAME.Skia.Gtk.csproj`
        - `PROJECT_NAME.Skia.WPF.csproj`

        ```xml
        <ItemGroup>
          <PackageReference Include="CommunityToolkit.WinUI.Controls.SettingsControls" Version="8.1.240916" />
          <!-- Add more uno community toolkit references here -->
        </ItemGroup>
        ```

    > [!NOTE]
    > Windows Community Toolkit version 8.x requires an update to Windows SDK **10.0.22621** and above, along with [Microsoft.WindowsAppSDK](https://www.nuget.org/packages/Microsoft.WindowsAppSDK) updated to the latest matching version.

    ---

1. Add the related needed namespace(s)

      In XAML:
        ```xmlns:controls="using:CommunityToolkit.WinUI.Controls"```

      In C#:
        ```using CommunityToolkit.WinUI.Controls;```

## Example with the SettingsCard Control

SettingsCard is a control that can be used to display settings in your experience. It uses the default styling found in Windows 11 and is easy to use, meets all accessibility standards and will make your settings page look great!

You can set the `Header`, `HeaderIcon`, `Description`, and `Content` properties to create an easy to use experience, like so:

```xml
<controls:SettingsCard Description="This is a default card, with the Header, HeaderIcon, Description and Content set."
                       Header="This is the Header">
  <controls:SettingsCard.HeaderIcon>
    <FontIcon Glyph="&#xE799;"
              FontFamily="{ThemeResource SymbolThemeFontFamily}" />
  </controls:SettingsCard.HeaderIcon>
  <ComboBox SelectedIndex="0">
    <ComboBoxItem>Option 1</ComboBoxItem>
    <ComboBoxItem>Option 2</ComboBoxItem>
    <ComboBoxItem>Option 3</ComboBoxItem>
  </ComboBox>
</controls:SettingsCard>
```

### See a working sample with more examples

![settingscard-full-sample](Assets/settingscard-full-sample.gif)

A complete working sample, along with additional examples, is available on GitHub: [Uno Windows Community Toolkit SettingsCard Sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/WindowsCommunityToolkit/Version-8.x/UnoWCTSettingsCardSample)

## Using Non-UI Elements from the CommunityToolkit: Converters

The CommunityToolkit provides a collection of ready-to-use converters for various scenarios (e.g., `x:Bind` in XAML). These converters streamline development by offering implementations for commonly used functionality, eliminating the need to manually create basic converters.
[List of CommunityToolkit Converters | Windows Toolkit Documentation](https://learn.microsoft.com/en-us/dotnet/communitytoolkit/windows/converters/)

The implementation of these is similar to the example of the `SettingsControl` above, with some minor adjustments required to use them:

1. Install the NuGet package reference needed for the converters

    ### Single Project Template [WinUI / WinAppSDK]

    1. Edit your project file `PROJECT_NAME.csproj` and add this additional needed reference:

        ```xml
        <ItemGroup>
          <PackageReference Include="CommunityToolkit.WinUI.Converters" />
          <!-- Add more community toolkit references here -->
        </ItemGroup>
        ```

    1. Edit `Directory.Packages.props` and add this additional needed reference:

        ```xml
        <ItemGroup>
          <PackageVersion Include="CommunityToolkit.WinUI.Converters" Version="8.1.240916" />
          <!-- Add more community toolkit references here -->
        </ItemGroup>
        ```

1. Add the related needed namespace(s)

      In XAML:
        ```xmlns:converters="using:CommunityToolkit.WinUI.Converters"```

      In C#:
        ```using CommunityToolkit.WinUI.Converters;```

     If you are developing an app using [C# Markup](xref:Uno.Extensions.Markup.Overview) and want to use the converters, you can refer to the [C# Markup Converters Documentation](xref:Uno.Extensions.Markup.Converters) for a detailed usage guide. The general import process is covered from this point onward.

1. XAML Definition

    Unlike the previously seen `SettingsCard` control example, it is standard practice to define a converter in the `Page.Resources` section as a `StaticResource` before using it. This approach ensures that converters, like controls, are properly declared with a namespace and can be easily reused throughout the page.

    ### [Example: StringToVisibilityConverter](#tab/string-visible-conv)

    The `StringToVisibilityConverter` is a converter that transforms a string value into a `Visibility` state, returning `Visibility.Visible` for non-empty strings and `Visibility.Collapsed` for null or empty strings.

    #### Define the Converter in Page Resources

    Add the converter to the `Page.Resources` section as a `StaticResource`:

    ```xml
    <Page.Resources>
        <converters:StringToVisibilityConverter x:Key="StringToVisibilityConverter" />
    </Page.Resources>
    ```

    #### Use the Converter in Page Content

    Here is an example of how to use the converter in your XAML content:

    ```xml
    <TextBlock Text="This text is visible only if the condition is met."
              Visibility="{Binding SomeStringProperty, Converter={StaticResource StringToVisibilityConverter}}"/>
    ```

    ### [Example: BoolToObjectConverter](#tab/bool-obj-conv)

    The `BoolToObjectConverter` allows you to convert a boolean value into a specific object by defining `TrueObject` and `FalseObject`. Depending on the boolean value, the converter will return the corresponding object.

    #### Define the Converter in Page Resources

    For example, you can use it to switch colors dynamically.
    Add the converter to the `Page.Resources` section as a `StaticResource`:

    ```xml
    <Page.Resources>
        <converters:BoolToObjectConverter x:Key="BoolToColorConverter"
                                          TrueObject="Green"
                                          FalseObject="Red"/>
    </Page.Resources>
    ```
  
    #### Use the Converter in Page Content

    Here is an example of how to use the converter in your XAML content:

    ```xml
    <TextBlock Text="Status:"
              Foreground="{Binding IsValid, Converter={StaticResource BoolToColorConverter}}"/>
    ```

    In this example, the `TextBlock` background will be green when `IsValid` is `true` and red when `IsValid` is `false`.

---

[!include[getting-help](includes/getting-help.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-community-toolkit.md

---
uid: Uno.Development.CommunityToolkit
---

# How to use Windows Community Toolkit

The [Windows Community Toolkit](https://learn.microsoft.com/windows/communitytoolkit/) is a collection of helper functions, custom controls, and app services. It simplifies and demonstrates common developer patterns when building experiences for Windows.

Depending on the version of the Windows Community Toolkit that you want to use, these tutorials below will walk you through adding and implementing:

- **[For WCT version 8.x](xref:Uno.Development.CommunityToolkit.v8):** The `SettingsCard` control, but the same steps can be followed for **other\*** Windows Community Toolkit components supported out of the box.
- **[For WCT version 7.x](xref:Uno.Development.CommunityToolkit.v7):** The `DataGrid` control, but the same steps can be followed for **other\*** Uno ported Windows Community Toolkit components.

**\* See the [non-Windows platform compatibility](#non-windows-platform-compatibility) section below for more details.**

> [!IMPORTANT]
> **Here is the [Migration Guide from v7 to v8 for Windows Community Toolkit](https://github.com/CommunityToolkit/Windows/wiki/Migration-Guide-from-v7-to-v8) for additional information on what changed lately between these versions.**
>
> For some controls (`DataGrid`, `Carousel`, ect...) you will need to use **version 7.x** for them as they are no longer available in the latest 8.x version of Windows Community Toolkit. The complete list of changes is available in the [migration guide](https://github.com/CommunityToolkit/Windows/wiki/Migration-Guide-from-v7-to-v8).
>
> For additional information, here are the releases notes for Windows Community Toolkit:
>
> - [Release notes for version 7.x](https://github.com/CommunityToolkit/WindowsCommunityToolkit/releases)
> - [Release notes for version 8.x](https://github.com/CommunityToolkit/Windows/releases)

## Non-Windows platform compatibility

### Overview

While all Windows Community Toolkit packages are supported on WinAppSDK, this is not the case for the other platforms Uno Platform supports.

### Unsupported Components

Some components, like [Media](https://github.com/CommunityToolkit/Windows/tree/main/components/Media/src), rely heavily on Composition APIs that are not yet supported by Uno Platform on all platforms. As a result, the Media package does not have the Uno-powered [MultiTargets](https://github.com/CommunityToolkit/Windows/blob/main/components/Media/src/MultiTarget.props) enabled, as the component would be non-functional out of the box.

In such cases, the Windows Community Toolkit prefers to disable the package for Uno Platform rather than enable it and have it not work. To address these functional gaps, we encourage contributing to Uno Platform to bridge the gaps for the missing supported APIs or to the [Windows Community Toolkit](https://github.com/CommunityToolkit/Windows) by seeking or helping to build Uno-compatible alternatives.

### Partial Support

In limited cases, WCT packages may have partial support for Uno Platform where the TargetFramework is enabled, but not all Toolkit code works out of the box. Currently, the only package in this scenario is Animations. It has a special FrameworkLayer abstraction that enables `AnimationBuilder` and `CustomAnimation` on Uno-powered MultiTargets but does not extend to `ImplicitAnimationSet` or Connected Animations.
See [CommunityToolkit/Windows #319](https://github.com/CommunityToolkit/Windows/issues/319) for tracking.

### Majority Support

The majority of controls are supported on all platforms by default.
If you find a package that doesn't work as expected on Uno Platform, please open an [issue](https://github.com/unoplatform/uno/issues/new/choose) or [discussion](https://github.com/unoplatform/uno/discussions) to let us know.

## Troubleshooting

The features and support for Uno Platform and Windows Community Toolkit components are constantly evolving. Therefore, you may encounter some issues while building your application. We encourage you to report these [issues](https://github.com/unoplatform/uno/issues/new/choose) and engage in [discussions](https://github.com/unoplatform/uno/discussions) to help improve the platform.

[!include[getting-help](includes/getting-help.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-fluent-assets.md

---
uid: Uno.Development.FluentAssets
---

# Uno Fluent UI assets

Starting from Uno.UI 4.7, Uno Platform provides a cross-platform fluent symbols font, provided by the [Uno.Fonts.Fluent](https://nuget.info/packages/Uno.Fonts.Fluent) NuGet package.

When included in the Uno Platform heads (excluding WinUI head), the symbols fonts will be used to display any control that makes use of it, such as the "burger" menu icon in a `NavigationView`.

## Usage

The symbol font is automatically used by built-in styles and templates. You can reference it in XAML using the `SymbolThemeFontFamily` resource. For example:

```xml
<FontIcon FontFamily="{ThemeResource SymbolThemeFontFamily}" Glyph="&#xE117;"/>
```

## Upgrading to the Uno.Fonts.Fluent package from previous releases

In your Uno Platform projects:

- Add the [Uno.Fonts.Fluent](https://nuget.info/packages/Uno.Fonts.Fluent) package to all your app heads.
- You will also need to make small modifications to individual platforms.
- For all heads, in respective `.csproj` files, remove all font files named `winjs-symbols.ttf` or `uno-fluentui-assets.ttf`.
- For iOS and macOS, the `info.plist` file should be updated for both platforms to remove the `UIAppFonts` block:

    ```xml
    <key>UIAppFonts</key>
    <array>
        <string>Fonts/uno-fluentui-assets.ttf</string>
    </array>
    ```

- For WebAssembly, remove the contents of `Font.css` related to `@font-face { font-family: "Symbols"; ...}`.

## Known issues

On iOS and macOS, the indeterminate state for a CheckBox is not the right color.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-howto-create-a-repro.md

---
uid: Uno.Development.Create-Repro
---

# How to create a reproduction project (aka "repro")

This documentation describes the steps needed to create a "repro" or reproduction project, which will help the community and maintainers troubleshoot issues that you may find when developing with Uno Platform.

The goal of a repro app is to find the **smallest possible piece of code that demonstrates the problem**, with the least dependencies possible. This is needed to make the resolution as fast as possible, as the Uno Platform team and community members do not have access to your projects sources nor understand your own expertise domain.

Some steps and questions to answer:

1. Make sure to test with the latest Uno Platform pre-release builds, the issue might have already been fixed.
1. Start from a new "blank uno app" from the Uno platform Visual Studio extension, or `dotnet new unoapp --preset=blank` app.
1. Attach a .zip file of that repro to the issue.
   > [!TIP]
   > Watch out for the size of zip created. Check the section below on reducing the sample size.
1. If you can, add a video or screenshots reproducing the issue. Github supports uploading `mp4` files in issues.

## Tips on how to create the simplest repro app

- Find the smallest piece of API used by your app (XAML Control, method, type) and extract that code into the repro app
- If it's impacting a control:
  - Try replicating the interactions as minimally as possible by cutting the ties with the rest of your original app
  - Try altering the properties of the control by either removing the styles, changing the styles, changing modes of the control if there are any.
- If you can't repro in a separate app because there are too many dependencies in your app try, removing as much code as you can around the use of failing API or Control. This may include removing implicit styles, global initializations.
- If the control offers events, try adding logging to Loading/Unloading/PropertyChanged/LayoutUpdated or other available events to determine if the Control or API is interacting with your code in expected ways. Sometimes adding a breakpoint in the handler of those events can show interesting stack traces.
- When debugging data bindings:
  - Show the text version of the binding expression somewhere in the UI, to see the type of the bound data:
    - `<TextBlock Text="{Binding}" />`
    - `<TextBlock Text="{Binding MyProperty}" />`
    - `<TextBlock Text="{Binding Command, ElementName=MyButton}" />`
  - Add an event handler to `DataContextChanged` in the code behind to see if and when the `DataContext` changed.
- Analyze device and app logs for clues about the control's behavior.
  - You may enable [the controls debug logs](https://github.com/unoplatform/uno/blob/master/doc/articles/logging.md), if any.
  - To validate that logs are enabled and in Debug, those starting with `Windows`, `Microsoft`, or `Uno` should be visible in the app's output. If not, make sure to [setup the logging properly](xref:Uno.Development.MigratingFromPreviousReleases).
  - Logs on iOS may need to have the [OSLog logger](https://github.com/unoplatform/uno.extensions.logging) enabled when running on production devices.
- Try on different versions of Visual Studio, iOS, Android, Linux, or browsers
- If available, try the API on Windows (WinUI) and see if it behaves differently than what Uno Platform is doing
- When issues occur, try breaking on all exceptions to check if an exception may be hidden and not reported.
- Update Uno.WinUI or other dependencies to previous or later versions, using a [bisection technique](https://git-scm.com/docs/git-bisect). Knowing which version of a package introduced an issue can help orient the investigations.

## Creating a smaller zip file to upload to github

> Yowza, that’s a big file Try again with a file smaller than 10MB.  
> -- Github

If you get the above message when attempting to upload the zipped sample, thats usually because you have included, beside the source codes, needless build outputs inside `bin` and `obj` folders for each target heads.

You can usually reduce this by performing `Build > Clean Solution` before zipping the entire solution folder. It also helps to manually delete the `bin\` and `obj\` folders under each project heads that you've compiled.

However, sometimes that still may not be enough. In such case, you can leverage the `git` tool and a `.gitignore` file to further reduce the size of the solution.

### [**Windows (Visual Studio)**](#tab/windows-vs)

If you're inside of Visual Studio:

- Open the solution
- At the bottom of the IDE window, click the **Add to Source Control** button, then **git**
- Select **Local only**, then **Create**
- Wait a few seconds for the changes to be committed
- Close visual studio
- Open a command line prompt in your solution folder and type `git clean -fdx`

Once done, you can zip the folder and send it to github in your issue or discussion.

### [**Windows (Console)**](#tab/windows-console)

Using the command prompt:

- Navigate to your sample's root folder
- Type `dotnet new gitignore`
- Type `git init`
- Type `git add .`
- Type `git commit -m "Initial sample commit"`
- Type `git archive HEAD --format zip --output sample.zip`
- Type `explorer /select,sample.zip`

Once done, you can send the `sample.zip` to github in your issue or discussion.

### [**macOS / Linux**](#tab/nix)

Using a terminal:

- Navigate to your sample's root folder
- Type `wget https://raw.githubusercontent.com/github/gitignore/main/VisualStudio.gitignore -O .gitignore`
- Type `git init`
- Type `git add .`
- Type `git commit -m "Initial sample commit"`
- Type `git clean -fdx`

Once done, you can zip the folder and send it to github in your issue or discussion.

---

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/uno-internals-android.md

---
uid: Uno.Contributing.Android
---

# How Uno works on Android

This article explores Android-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](uno-internals-overview.md).

Some particulars of Android:

## Some classes are written in Java

Several base classes and helper classes are written in native Java code. These are located in [Uno.UI.BindingHelper.Android](https://github.com/unoplatform/uno/tree/master/src/Uno.UI.BindingHelper.Android/Uno/UI).

The Xamarin.Android framework gives complete access to the Android API from managed C#, so why write anything in Java? The reason is performance. The interop between Java and C# can be costly, and instrumented profiling identified that certain virtual methods when overridden in C# and called in heavily-used paths (eg measure and arrange) imposed a measurable performance penalty. Over time, these 'hot' methods have been lowered to Java classes, particularly the `UnoViewGroup` class.

The `Uno.UI.BindingHelper.Android` project builds these Java types, and wraps them in a [Xamarin binding library](https://learn.microsoft.com/xamarin/android/platform/binding-java-library/), making them available via C#.

## UIElement inherits from ViewGroup

`UIElement` in Uno is a native view on Android, inheriting from the general `ViewGroup` type. To elaborate, `UIElement`'s base classes are the following:
`Android.Views.View` → `Android.Views.ViewGroup` → `Uno.UI.UnoViewGroup` → `Uno.UI.Controls.BindableView` → `Windows.UI.Xaml.UIElement`

Recall that `UIElement` implements `DependencyObect` [as an interface](uno-internals-overview.md) in Uno.

## Layouting

Uno's measure and arrange logic is triggered from the native Android layout cycle. For a schematic of the control flow, see [Layouting in Android](Uno-UI-Layouting-Android.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/uno-internals-hotreload.md

---
uid: Uno.Contributing.Internals.HotReload
---

# Hot Reload Phases

_This page details the internals of Hot Reload. To use Hot Reload, [head over here](xref:Uno.Features.HotReload)._

When a change is made to XAML or a C# code file, it's immediately picked up by compiler. However the updates aren't immediately sent to the app until the file is saved (assuming "Hot Reload on Save" is enabled) or the Hot Reload button is clicked in Visual Studio.

When Hot Reload is triggered, the changes, along with any associated metadata, is propagated to the running application.

There are two types of updates that can be sent:

- Incremental - these are deltas that are applied to existing types. For example a method can be modified, and the next time the method is invoked it will execute the new code
- Type Replacement - when a type has been attributed with the CreateNewOnMetadataUpdate attribute, instead of changes being sent as deltas, a whole new type is added. So for example if a change is made to MainPage, a new type, MainPage#1, is created and is available within the executing application.

After Hot Reload has propagated changes to the running application, it will look for any types that have been registered using the MetadataUpdateHandler attribute. If a type is found, it will attempt to run the UpdateApplication static method, passing in the types that have been modified. In the case of incremental updates, the types will be original types found within the application but they'll have been updated with the deltas that have been sent. In the case of type replacement updates, the types will contain the newly created types. The meta data on these types can be interrogated to determine the original type that they're replacing.

Uno core already registers a class with the MetadataUpdateHandler and has an UpdateApplication method that gets invoked when Hot Reload is triggered. This application does two things:

- for Type Replacement updates, it adds, or updates, values in mapping dictionaries it manages so that it's possible to translate between an original type and it's (current) replacement, and from a replacement type, back to the original type.
- it triggers an update to the UI (a UI Update) which walks the visual tree looking for elements where the type has been replaced. If an element is of a type that has been replace, a new element is created and used to replace the original element in the tree.

## Intercepting the UI Update

The main extensibility point for developers wanting to integrate with Hot Reload for Uno Platform applications is via the UI Update. The UI Update is the phase of Hot Reload where the visual tree is traversed and elements are updated according to the updated type information.

To intercept the UI Update the first thing to do is to create a static class with static methods that will be invoked at different points in the UI Update. The static class needs to be registered using the ElementMetadataUpdateHandler attribute.

In this example, the FrameUpdateHandler is registered as a handler for the Frame class. As the visual tree is traversed, when a Frame is encountered the appropriate methods on the FrameUpdateHandler will be invoked.

```csharp
[assembly:ElementMetadataUpdateHandler(typeof(Frame), typeof(FrameUpdateHandler))]
```

In this example, the VisualTreeHandler is registered as a handler without specifying a particular element type. Only the methods on the VisualTreeHandler that aren't specific to individual elements will be invoked, for example the BeforeVisualTreeUpdate and AfterVisualTreeUpdate method.

The following methods (at least one) can be implemented by the static class registered using the ElementMetadataUpdateHandler:

```csharp
static void BeforeVisualTreeUpdate(Type[]? updatedTypes);

static void AfterVisualTreeUpdate(Type[]? updatedTypes);

static void ReloadCompleted(Type[]? updatedTypes, bool uiUpdated);

static void ElementUpdate(FrameworkElement, Type[]?);

static void BeforeElementReplaced(FrameworkElement, FrameworkElement, Type[]?);

static void AfterElementReplaced(FrameworkElement, FrameworkElement, Type[]?);
```

## Pausing / Resuming UI Update

Pausing and resuming UI Update is done by calling

`TypeMappings.Pause()` and `TypeMappings.Resume()`

Note that pausing UI Updates doesn't stop the Hot Reload process. It only prevents the UI Update from running until UI Updates are resumed.

<!---
## Waiting for Hot Reload to be applied

// TODO: Give an example of how to await UI Updates (eg https://github.com/unoplatform/uno/blob/0340cc1394994cdbd525d61de611a0531c38bcc7/src/Uno.UI.RuntimeTests/Tests/HotReload/Frame/HRApp/Tests/Given_Frame.cs#L9-L37)
-->

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/uno-internals-ios.md

---
uid: Uno.Contributing.iOS
---

# How Uno works on iOS

This article explores iOS-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](uno-internals-overview.md).

## UIElement inherits from UIView

`UIElement` in Uno is a native view on iOS, inheriting from the general `UIView` type. To elaborate, `UIElement`'s base classes are the following:
`UIKit.UIView` → `Uno.UI.Controls.BindableUIView` → `Windows.UI.Xaml.UIElement`

Recall that `UIElement` implements `DependencyObject` [as an interface](uno-internals-overview.md) in Uno.

## Layouting

Uno's measure and arrange logic is triggered from the native iOS layout cycle. For a schematic of the control flow, see [Layouting in iOS](Uno-UI-Layouting-iOS.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/uno-internals-macos.md

---
uid: Uno.Contributing.macOS
---

# How Uno works on macOS

This article explores macOS-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](uno-internals-overview.md).

## UIElement inherits from NSView

`UIElement` in Uno is a native view on macOS, inheriting from the general `NSView` type. To elaborate, `UIElement`'s base classes are the following:
`AppKit.NSView` → `Uno.UI.Controls.BindableNSView` → `Windows.UI.Xaml.UIElement`

Recall that `UIElement` implements `DependencyObect` [as an interface](uno-internals-overview.md) in Uno.

## Similarities with iOS

Since the iOS and macOS UI frameworks bear substantial resemblances, the same or very similar code can frequently be used to do the same thing on both platforms, which Uno takes advantage of where possible. Partial class definitions that are shared between iOS and macOS can be identified by the `*.iOSmacOS.cs` suffix. Since Uno's iOS support predates its macOS support, in some cases internal methods have been added to make macOS' API appear still closer to that of iOS and make code reuse easier, such as the `SizeThatFits()` method or the `SetNeedsLayout()` extension method.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/uno-internals-overview.md

---
uid: Uno.Contributing.Overview
---

# How Uno Platform works

This article explores how Uno works in detail, with a focus on information that's useful for contributors to Uno.

## What Uno Platform does

Uno Platform is a cross-platform projection of Microsoft's WinUI framework (and its preview iteration, UWP). Uno mirrors WinUI types and supports the WinUI 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 WinUI to be built and run on Android, iOS, Linux, macOS, and in the browser via WebAssembly.

> [!NOTE]
> While WinUI 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.Xaml` namespace, and non-UI APIs such as `Windows.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](https://dotnet.microsoft.com/en-us/).

Uno Platform aims to be a 1:1 match for WinUI, 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/WinUI controls in the visual tree.

## Uno.WinUI as a class library

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](https://learn.microsoft.com/windows/uwp/xaml-platform/dependency-properties-overview), 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`](https://learn.microsoft.com/uwp/api/windows.ui.xaml.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`](https://github.com/unoplatform/uno/tree/master/src/Uno.UI/UI/Xaml/Controls/NavigationView) is a good example. The primitives themselves, such as [`TextBlock`](https://github.com/unoplatform/uno/tree/master/src/Uno.UI/UI/Xaml/Controls/TextBlock), [`Image`](https://github.com/unoplatform/uno/tree/master/src/Uno.UI/UI/Xaml/Controls/Image), or [`Shape`](https://github.com/unoplatform/uno/tree/master/src/Uno.UI/UI/Xaml/Shapes), 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`](../features/windows-system-power.md) or [`Windows.Devices.Sensors`](../features/windows-devices-sensors.md), incorporate a large fraction of platform-specific code to interact with the associated native APIs.

### Generated `NotImplemented` stubs

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 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](https://github.com/unoplatform/uno/tree/master/src/Uno.UWPSyncGenerator) inspects the WinUI framework, compares it to authored code in Uno Platform, and generates stubs for all types and type members that exist in WinUI but are not implemented on Uno. For example:

```csharp
#if __ANDROID__ || __IOS__ || __TVOS__ || IS_UNIT_TESTS || __WASM__
[global::Uno.NotImplemented]
public  bool ExitDisplayModeOnAccessKeyInvoked
{
 get
 {
  return (bool)this.GetValue(ExitDisplayModeOnAccessKeyInvokedProperty);
 }
 set
 {
  this.SetValue(ExitDisplayModeOnAccessKeyInvokedProperty, value);
 }
}
#endif
```

Notice 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.

### Platform-specific details

For more details on how Uno Platform runs on each platform, see platform-specific information for:

* [Android](uno-internals-android.md)
* [iOS](uno-internals-ios.md)
* [WebAssembly](uno-internals-wasm.md)

## Uno.WinUI build-time tooling

### Parsing XAML to C# code

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`](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.SourceGenerators/XamlGenerator/XamlFileGenerator.cs) class.

### DependencyObject implementation generator

On [Android](uno-internals-android.md), [iOS](uno-internals-ios.md), and [macOS](uno-internals-macos.md), `UIElement` (the base view type in 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 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](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.SourceGenerators/DependencyObject/DependencyObjectGenerator.cs) looks for such classes and [generates](https://github.com/unoplatform/Uno.SourceGeneration) a partial implementation for the `DependencyObject` interface, ie, the methods that on UWP would be inherited from the base class.

### Formatting image assets

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](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.Tasks/Assets/RetargetAssets.cs) copies the image assets located in the shared project to the appropriate location and format for the target platform.

### Formatting string resources

As with images, different platforms have different requirements for the location and formatting of localized string resources. The [ResourcesGenerationTask](https://github.com/unoplatform/uno/blob/master/src/SourceGenerators/Uno.UI.Tasks/ResourcesGenerator/ResourcesGenerationTask.cs) reads the strings defined in WinUI's `*.resw` files in the shared project, and generates the appropriate platform-specific file.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/uno-internals-wasm.md

---
uid: Uno.Contributing.Wasm
---

# How Uno works on WebAssembly Native

This article explores WebAssembly-specific details of Uno's internals, with a focus on information that's useful for contributors to Uno. For an overview of how Uno works on all platforms, see [this article](uno-internals-overview.md).

## What is WebAssembly actually?

> [WebAssembly is a new type of code](https://developer.mozilla.org/en-US/docs/WebAssembly) that can be run in modern web browsers — it is a low-level assembly-like language with a compact binary format that runs with near-native performance and provides languages such as C/C++ and Rust with a compilation target so that they can run on the web. It is also designed to run alongside JavaScript, allowing both to work together.

WebAssembly (Wasm) allows .NET code, and hence Uno, to run in the browser. It's supported by all major browsers, including mobile browser versions.

Wasm in the browser runs in the same security sandbox as JavaScript does, and has exactly the same capabilities and constraints. Note that for now there's no means of accessing browser APIs, including the DOM, directly from Wasm. All communication to and from the DOM must be done by interop with JavaScript.

## UIElements map to DOM elements

There is for the most part a 1:1 mapping between managed XAML elements and DOM elements. The element tag associated with a XAML type is set by a `UIElement` constructor overload which takes the tag as a string, with "div" as the default.

## Typescript layer

Part of Uno for WASM is defined in Typescript (which transpiles to JavaScript), since going through JavaScript is currently the only way to manipulate the DOM and access other browser APIs from WebAssembly. The TypeScript layer is located in the Uno.UI.Wasm project. The most important class here is `WindowManager.ts`.

## JavaScript interop in Uno

Calls into JavaScript from C# generally access methods in the `WindowManagerInterop` .NET class, which calls methods on the `WindowManager` TypeScript class using the `WebAssemblyRuntime.InvokeJS()` method.

Callbacks into C# from JavaScript can be defined using the `mono_bind_static_method` wrapper. C# methods that will be called from JavaScript must be added to the [LinkerDefinition](https://github.com/unoplatform/uno/blob/master/src/Uno.UI/LinkerDefinition.Wasm.xml) file.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/uno-islands.md

---
uid: Uno.Tutorials.UnoIslands
---

# Uno Islands

With Uno Islands, you can host Uno Platform XAML controls in an WPF application, next to existing WPF content. This feature enables you to enhance the look, feel, and functionality of your existing WPF application with the latest Windows UI features provided by their implementation within Uno Platform.

## How to use Uno Islands with existing WPF app

The most common scenario is to add Uno Islands into an existing WPF app. First, **add a Shared project** into your WPF app solution by right-clicking the solution node in Solution explorer and choosing **Add -> New Project...** and searching for "Shared Project" in the dialog. This project will be used to host our Uno Platform XAML files.

![Adding a Shared project](../Assets/guides/uno-islands/add-shared.png)

### Shared project contents

In this project, we need to add the Uno Islands Application and a page to be displayed. The easiest way to do this is to copy these files from [UnoIslandsSamplesApp in Uno.Samples GitHub repository](https://github.com/unoplatform/Uno.Samples/tree/master/UI/UnoIslandsSampleApp/UnoIslandsSampleApp.Shared). Copy and include `App.xaml`, `App.xaml.cs`, `MainPage.xaml`, and `MainPage.xaml.cs` files in the shared project, and the `Assets` folder to include the Uno Platform icon font.

### Updating the WPF application project

To light-up the Uno Islands feature, we need to reference several Uno Platform NuGet packages, reference the shared project, and include the Uno Platform icon font. Double-click the WPF project and add the following:

```xml
<ItemGroup>
    <PackageReference Include="Microsoft.Extensions.Logging" Version="9.0.1" />
    <PackageReference Include="Microsoft.Extensions.Logging.Console" Version="9.0.1" />
    <PackageReference Include="Uno.WinUI.Skia.Wpf" Version="5.6.33" />
    <PackageReference Include="Uno.WinUI.DevServer" Version="5.6.33" Condition="'$(Configuration)'=='Debug'" />
    <PackageReference Include="Uno.UI.Adapter.Microsoft.Extensions.Logging" Version="5.6.33" />
    <PackageReference Include="Uno.WinUI.XamlHost" Version="5.6.33" />
    <PackageReference Include="Uno.WinUI.XamlHost.Skia.Wpf" Version="5.6.33" />
</ItemGroup>
<ItemGroup>
    <UpToDateCheckInput Include="..\UnoIslandsSampleApp.Shared\**\*.xaml" />
</ItemGroup>
<ItemGroup>
    <Content Include="Assets\Fonts\uno-fluentui-assets.ttf" />
</ItemGroup>

<Import Project="..\UnoIslandsSampleApp.Shared\UnoIslandsSampleApp.Shared.projitems" Label="Shared" />
```

### Adding an Uno Island

Now we can add an Uno Island into our WPF app content. Open a WPF XAML file and add the following namespace declaration to the root element:

```xml
xmlns:xamlHost="clr-namespace:Uno.UI.XamlHost.Skia.Wpf;
                assembly=Uno.UI.XamlHost.Skia.Wpf"
```

And now use the `UnoXamlHost` control to host the Uno Platform island:

```xml
<Grid Margin="20">
    <Grid.RowDefinitions>
        <RowDefinition Height="Auto" />
        <RowDefinition Height="*" />
    </Grid.RowDefinitions>
    <Button>Hello from WPF!</Button>
    <xamlHost:UnoXamlHost Grid.Row="1" 
        InitialTypeName="UnoIslandsSampleApp.MainPage" />
</Grid>
```

![Hello, world! example](../Assets/guides/uno-islands/hello-world.png)

## Data-binding

The WPF `DataContext` is automatically propagated to the Uno Island-hosted controls, which makes it possible to use an MVVM-based approach. Suppose we update the `MainWindow.xaml.cs` as follows:

```csharp
public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
        DataContext = "friends";
    }
}
```

Now we can use the data in the `MainPage.xaml`:

```xml
<Page
    x:Class="UnoIslandsSampleApp.MainPage"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:local="using:UnoIslandsSampleApp"
    xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
    xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
    mc:Ignorable="d"    
    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

    <Grid>
        <TextBlock Margin="20" FontSize="30">
            <Run Text="Hello, " /><Run Text="{Binding}" /><Run Text="!" />
        </TextBlock>
    </Grid>
</Page>
```

![Data binding example](../Assets/guides/uno-islands/hello-friends.png)

## How to use Uno Islands in blank Uno app

The starting point for creating an Uno Islands-enabled application is to create a blank Uno Platform app.

### Preparing solution

In the new solution, feel free to remove targets that are not needed for your purposes, but make sure to keep at least the Shared project and WPF project.

![XamlHost Solution layout](../Assets/guides/uno-islands/solution-layout.png)

Right-click the solution node in Solution Explorer and select `Manage NuGet Packages for Solution...`. In the NuGet Package Manager window, search for `Uno.WinUI.XamlHost`.

![XamlHost NuGet packages](../Assets/guides/uno-islands/xamlhost-packages.png)

Install the `XamlHost` package in all projects and the `XamlHost.Skia.Wpf` package in the WPF project.

### Set up `XamlApplication`

Uno Islands require a special type of `Application` class to get discovered properly. Open the `App.xaml.cs` file and make your application derive from `Uno.UI.XamlHost.XamlApplication`:

```csharp
public sealed partial class App : Uno.UI.XamlHost.XamlApplication
{
    ...
}
```

In `App.xaml` you also need to adjust the root element accordingly:

```xml
<xamlHost:XamlApplication
    x:Class="UnoIslandsSampleApp.App"
    xmlns:xamlHost="using:Uno.UI.XamlHost"
    ...>
...
</xamlHost:XamlApplication>
```

> Note that you can create a separate `XamlApplication`-derived class for Islands purposes and keep the existing `Application` class for "full" Uno Application purposes, if you want to develop a self-standing and island-hosted application simultaneously.

### Hosting Uno Platform content in WPF app

You can now host any Uno Platform content next to classic WPF content using the `Uno.UI.XamlHost.Skia.Wpf.UnoXamlHost` control. The `InitialTypeName` attribute allows you to specify the type that should be loaded in it. For example, we can host the `MainPage` in `MainWindow.xaml` as follows:

```xml
<Window x:Class="UnoIslandsSampleApp.WPF.Host.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:local="clr-namespace:UnoIslandsSampleApp.WPF.Host"
        xmlns:xamlHost="clr-namespace:Uno.UI.XamlHost.Skia.Wpf;assembly=Uno.UI.XamlHost.Skia.Wpf"
        mc:Ignorable="d"
        Title="MainWindow" Height="450" Width="800">
    <Grid Margin="20">
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto" />
            <RowDefinition Height="*" />
        </Grid.RowDefinitions>
        <Button>Hello from WPF!</Button>
        <xamlHost:UnoXamlHost Grid.Row="1" InitialTypeName="UnoIslandsSampleApp.MainPage" />
    </Grid>
</Window>
```

Make sure to update the `MainWindow.xaml.cs` as follows to remove the initialization used by full-window Uno apps:

```csharp
public partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();
    }
}
```

![Hello, world! example](../Assets/guides/uno-islands/hello-world.png)

## Limitations

This feature is in early preview and some functionality is not enabled yet, including:

- Focus management
- Drag and drop
- Keyboard event handling

## See Uno Islands in action

Full working sample application is available in the [Uno Samples repository](https://github.com/unoplatform/Uno.Samples/tree/master/UI).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-notimplemented-types.md

---
uid: Uno.Development.NotImplemented
---

# The member/type is not implemented

If you're visiting this page after having clicked on a link in your application's debug log or exception view, this means you're using directly or indirectly an API that is not implemented.

Uno Platform is built around providing the full APIs provided by WinRT and WinUI, by replicating the available surface to be used in Uno Platform apps.

This WinUI and WinRT surface is very large. We covered a great portion of it since 2013, to the level of even publicly-listed enterprises deploying apps with it. To prioritize the remainder of unimplemented WinUI & WinRT API surface, we need the help of the community to add support for APIs that are marked as "Not Implemented".

Multiple directions are available:

- Make sure that you are using the latest available stable packages for Uno Platform (Uno.WinUI or Uno.UI)
- Find the API (Type, method or property) in the [Issues list](https://github.com/unoplatform/uno/issues) or [Pull Requests](https://github.com/unoplatform/uno/pulls) to vote on it with GitHub reactions, and if it's not already present, create one so the team knows you're trying to use it. Make sure to let us know your use case as it may drive priorities.
- If you're up for it, you can contribute an implementation for this API

The Uno Platform team [offers professional support](https://platform.uno/support/) to get issues sorted out faster.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-platform-status-troubleshooting.md

---
uid: Uno.Development.UnoPlatformStatus
---

[!INCLUDE [uno-platform-status](includes/uno-platform-status-inline.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-platform-status.md

---
uid: Uno.UnoPlatformStatus
---

[!INCLUDE [uno-platform-status](includes/uno-platform-status-inline.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-android.md

---
uid: uno.publishing.android
---

# Publishing Your App for Android

## Preparing For Publish

- [Performance Profiling](xref:Uno.Tutorials.ProfilingApplications)

## Building your app

### Packaging your app using the CLI

To build your app from the CLI, on Windows, Linux, or macOS:

- Open a terminal, command line, or powershell
- Navigate to your `csproj` folder
- Publish the app using:

  ```shell
  dotnet publish -f net9.0-android -c Release -o ./publish
  ```

- Once the build is done, the output `.apk` and `.aab` files are located in the `./publish` folder.

## Publishing your Android App

Publishing an Uno Platform app uses the same steps as .NET for Android-based technologies.

Your app can be published:

- Through a market – There are multiple Android marketplaces that exist for distribution, with the most well-known being [Google Play](https://developer.android.com/distribute/googleplay/publish/index.html), or [Amazon](https://www.developer.amazon.com/docs/app-submission/submitting-apps-to-amazon-appstore.html).
- Via a website – An Uno Platform app can be made available for download on a website, from which users may then install the app by clicking on a link.
- Using [`adb`](https://learn.microsoft.com/en-us/dual-screen/android/emulator/adb) on the command line, with `adb install your.apk`. In Visual Studio 2022/2026, you can open a shell with `adb` available in the `PATH` with the **Tools**, **Android**, **Android Adb Command Prompt** menu.

Publishing an Uno Platform also uses the same steps as a MAUI app, which is based on .NET for Android. You can follow these [steps and links](https://learn.microsoft.com/dotnet/maui/android/deployment/?view=net-maui-8.0) to publish your app.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-desktop-macos-advanced.md

---
uid: uno.publishing.desktop.macos.advanced
---

# Publishing Your App for macOS - Advanced Topics

## App Bundle (.app) Customization

### Custom `Info.plist`

If your application requires extraneous permissions from macOS to execute some operations, e.g. using the camera, then you need to customize the `Info.plist` file of your app bundle.

You can create a basic `Info.plist` file yourself, using any text editor. The content should be like:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <!-- If a `LanguageId` is not provided it will default to `en-US` -->
  <key>CFBundleDevelopmentRegion</key>
  <string></string>

  <!-- If not specified the value of `ApplicationTitle` will be used -->
  <key>CFBundleDisplayName</key>
  <string></string>

  <!-- If not specified the value of `AssemblyName` will be used -->
  <key>CFBundleExecutable</key>
  <string></string>

  <!-- If not specified an `icon.icns` file will be created from the app icons and referenced here -->
  <key>CFBundleIconFile</key>
  <string></string>

  <!-- If not specified the value of `ApplicationId` will be used -->
  <key>CFBundleIdentifier</key>
  <string></string>

  <!-- If not specified the first 16 characters of `ApplicationTitle` will be used -->
  <key>CFBundleName</key>
  <string></string>

  <!-- If not specified the value of `ApplicationDisplayVersion` will be used -->
  <key>CFBundleShortVersionString</key>
  <string></string>

  <!-- If not specified the value of `ApplicationVersion` will be used -->
  <key>CFBundleVersion</key>
  <string></string>

  <!--
	The entries for CFBundleInfoDictionaryVersion, CFBundlePackageType and
	NSPrincipalClass will be added automatically and should not be changed.

	The comments will be removed from this file when saved inside the bundle.

	You can add other entries, like permissions, as needed.
	-->
</dict>
</plist>
```

You can edit the `Info.plist` file, add any required entries (for permissions), and leave other fields empty. The basic, empty fields will be filled automatically by the `msbuild` task based on your project.

Then from the CLI run:

```bash
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:UnoMacOSCustomInfoPlist=path/to/Info.plist
```

### Hardened Runtime

[Hardened Runtime](https://developer.apple.com/documentation/security/hardened-runtime) is `true` by default as it is **required** for [notarization](https://developer.apple.com/documentation/security/notarizing-macos-software-before-distribution).

If needed you can turn it off by providing `-p:UnoMacOSHardenedRuntime=false` on the CLI.

```bash
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:UnoMacOSHardenedRuntime=false
```

### Custom Entitlements

[Entitlements](https://developer.apple.com/documentation/bundleresources/entitlements) grants permission to your executable. If nothing is specified the default entitlements required for a notarization-compatible dotnet-based application will be included automatically.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>com.apple.security.cs.allow-jit</key>
    <true/>
  </dict>
</plist>
```

You can provide your own entitlement file if needed using `-p:UnoMacOSEntitlements=/path/to/entitlements.plist` on the CLI.

```bash
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:UnoMacOSEntitlements=/path/to/entitlements.plist
```

### Trimming

App bundles that are distributed should be self-contained applications that depend only on the OS to execute. However bundling the dotnet runtime, base class libraries, and Uno Platform libraries produce a rather large application size.

To reduce the size of the app bundle you can enable dotnet's [trimming](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/trimming-options#enable-trimming) when publishing the app, using `-p:PublishTrimmed=true`. The full command from the CLI would be:

```bash
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:PublishTrimmed=true
```

> [!IMPORTANT]
> Your code and dependencies need to be [trimmer-aware](https://learn.microsoft.com/en-us/dotnet/core/deploying/trimming/prepare-libraries-for-trimming) and the trimmed app bundle should be carefully tested to ensure the code removed by the trimmer does not affect its functionality.

### Optional files

`dotnet publish` includes several files that are not strictly required to execute your application. To reduce the app bundle size most of those files are **not** included, by default, inside the app bundles.

#### Including dotnet `createdump` tool

Although useful for debugging, the `createdump` executable is rarely used by the application's consumers and, by default, is not included in the app bundle.

If you wish to include `createdump` inside your app bundle add the `-p:UnoMacOSIncludeCreateDump=true` on the CLI.

```bash
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:UnoMacOSIncludeCreateDump=true
```

#### Including `libclrgc.dylib` extraneous GC

An alternate garbage collection (GC) library is included by `dotnet publish`. It is, by default, removed from the app bundle since it would not be used at runtime.

If you wish to include this extra GC library inside your app bundle add the `-p:UnoMacOSIncludeExtraClrGC=true` on the CLI.

```bash
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:UnoMacOSIncludeExtraClrGC=true
```

#### Including `libmscordaccore.dylib` and `libmscordbi.dylib` debugging support

Extraneous debugging support libraries are included by `dotnet publish`. They are, by default, removed from the app bundle since it's unlikely to be used for debugging.

If you wish to include the extra debugging libraries inside your app bundle add the `-p:UnoMacOSIncludeNativeDebugging=true` on the CLI.

```bash
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:UnoMacOSIncludeNativeDebugging=true
```

#### Including assemblies debugging symbols (.pdb) files

dotnet debugging symbols (`.pdb`) are generally included in released applications since they help to provide better stack traces and help developers resolve issues. As such, they are, by default, included inside the app bundle.

If you wish to remove them anyway, you can do so by adding the `-p:UnoMacOSIncludeDebugSymbols=false` on the CLI.

```bash
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=app -p:UnoMacOSIncludeDebugSymbols=false
```

## Disk Image (.dmg) Customization

### Symlink to /Applications

By default, the produced disk image will contain a symlink to `/Applications` so users can drag-and-drop the app bundle inside it. If you do not want the symlink to be present inside the disk image you can add `-p:UnoMacOSIncludeSymlinkToApplications=false` on the command line.

```bash
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=dmg -p:UnoMacOSIncludeSymlinkToApplications=false -p:CodesignKey={{identity}} -p:DiskImageSigningKey={{identity}}
```

### Additional Customization

Further disk image customization is possible but can be tricky since it requires modification to the `.DS_Store` binary file inside the disk image (many trials and errors). If more control is required (e.g. icon positioning, background image...) we recommend using 3rd party tools created specifically for this purpose. Some free/open-source examples are:

- [create-dmg](https://github.com/sindresorhus/create-dmg)
- [dmgbuild](https://dmgbuild.readthedocs.io/en/latest/)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-desktop-macos.md

---
uid: uno.publishing.desktop.macos
---

# Publishing Your App for macOS

There are several options to publish your macOS application to your customers. They all start with creating an [app bundle](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/AboutBundles/AboutBundles.html) (.app).

> [!IMPORTANT]
> Publishing for macOS is only supported on macOS

## Create an app bundle (.app)

The most basic app bundle can be created with:

```bash
dotnet publish -f net9.0-desktop -r {{RID}} -p:PackageFormat=app
```

Where `{{RID}}` is either `osx-x64` or `osx-arm64`.

The resulting app bundle, which is a directory, will be located at `bin/Release/net9.0-desktop/{{RID}}/publish/{{APPNAME}}.app`.

> [!NOTE]
> The [structure of the app bundle](https://developer.apple.com/library/archive/documentation/CoreFoundation/Conceptual/CFBundles/BundleTypes/BundleTypes.html) requires a [custom native host](https://learn.microsoft.com/en-us/dotnet/core/tutorials/netcore-hosting) to run the app. As such, starting with Uno 6.1, the app bundles are **always** built as a self-contained executable, even if the `SelfContained` property is not set to `true` inside the project.

### Code Signing

> [!IMPORTANT]
> The code signing process requires access to the Internet to retrieve a secure timestamp.

To ensure the integrity of the app bundle Apple requires you to digitally sign your code. The key difference to producing a signed app bundle is to add `-p:CodesignKey={{identity}}` to specify which identity should be used to produce the signature.

```bash
dotnet publish -f net9.0-desktop -r {{RID}} -p:PackageFormat=app -p:CodesignKey={{identity}}
```

You can use the special identity `-` to produce an ad-hoc signature. This basically tells macOS's [Gatekeeper](https://support.apple.com/en-us/102445) that the file is safe to use **locally**, however, it does not help distribute the app bundle.

> [!NOTE]
> Besides needed access to the Internet the code signing process slows down the builds. For local testing of your app, you do not need to sign the app bundle.

#### How to find your identity

If you have not already, you need to create your [developer certificates](https://developer.apple.com/help/account/create-certificates/create-developer-id-certificates/). Once you have created them, on your Mac computer, you can find your identities from the CLI, by running:

```bash
security find-identity -v
```

This will show you every **valid** identity available on your Mac.

```text
  1) 8C8D47A2A6F7428971A8AA5C6D8F7A30D344E93C "Apple Development: John Appleby (XXXXXXXXXX)"
  2) F84D25AAF30BAFA988D8B4CE8A0BA3BE891199D8 "Developer ID Installer: John Appleby (XXXXXXXXXX)"
  3) 0357503C3CF78B093A764EA382BF10E7D3AEDA9A "Apple Distribution: John Appleby (XXXXXXXXXX)"
  4) A148697E815F6090DE9698F8E2602773296E2689 "Developer ID Application: John Appleby (XXXXXXXXXX)"
     4 valid identities found
```

To properly sign an app bundle for publishing you need to use the `"Developer ID Application: *"` or its thumbprint (long hex number) entry as the identity.
Both

```bash
dotnet publish -f net9.0-desktop -r {{RID}} -p:PackageFormat=app -p:CodesignKey="Developer ID Application: John Appleby (XXXXXXXXXX)"
```

and

```bash
dotnet publish -f net9.0-desktop -r {{RID}} -p:PackageFormat=app -p:CodesignKey=A148697E815F6090DE9698F8E2602773296E2689
```

are functionally identical and will produce a signed app bundle.

## Distributing the app bundle

An app bundle is a directory and, as such, is not easy to distribute. Most macOS applications are distributed using one of the following methods.

### Installer (.pkg)

You can easily create an installer package for your app bundle. This will produce a single, compressed executable file that can be shared (if signed and notarized) with anyone using a Mac computer.

From the CLI run:

```bash
dotnet publish -f net9.0-desktop -r {{RID}} -p:PackageFormat=pkg -p:CodesignKey={{identity}} -p:PackageSigningKey={{installer_identity}}
```

Where the following changes to the previous command are:

- modifying `PackageFormat` to `pkg` to produce the package. This package will include the app bundle inside it, so the `CodesignKey` argument is still required;
- adding `-p:PackageSigningKey={{installer_identity}}` to specify which identity should be used to sign the package. Unlike app bundles, signing requires a `Developer ID Installer: *` identity.

The resulting installer will be located at `bin/Release/net9.0-desktop/{{RID}}/publish/{{APPNAME}}.pkg`.

> [!IMPORTANT]
> The installer can behave weirdly locally (or on CI) since the app bundle name is known to macOS and it will try to update the application, where it was built or copied, instead of installing a copy of it under the `/Applications/` directory. Ensure you are testing your package installer on a different Mac or inside a clean virtual machine (VM).

#### Notarize the package

Having both the app bundle (.app) and installer (.pkg) signed is insufficient. As the package is binary and you'll share it with customers, Apple must also notarize it.

The first step is to store your Apple Account credentials inside the key store. This makes all the further commands (and notarization) much simpler. From the CLI run:

```bash
xcrun notarytool store-credentials {{notarytool-credentials}} --apple-id john.appleby@platform.uno --team-id XXXXXXXXXX --password aaaa-bbbb-cccc-dddd
```

where

- `{{notarytool-credentials}}` is the name of your credentials inside the key store.
- `--apple-id` provides the email address used for your [Apple Account](https://developer.apple.com/account).
- `--team-id` provides your team ID, a 10-character code. [How to find it](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id).
- `--password` is an [app specific password](https://support.apple.com/en-us/102654) created specifically for `notarytool`

> [!NOTE]
> Since Apple Accounts requires two factors authentication (2FA) you will need to [create an app-specific password](https://support.apple.com/en-us/102654) for `notarytool`.

```text
This process stores your credentials securely in the Keychain. You reference these credentials later using a profile name.

Validating your credentials...
Success. Credentials validated.
Credentials saved to Keychain.
To use them, specify `--keychain-profile "notarytool-credentials"`
```

Once this (one-time) setup is done, you can notarize the disk image while building the app. From the CLI run:

```bash
dotnet publish -f net9.0-desktop -r {{RID}} -p:SelfContained=true -p:PackageFormat=dmg -p:CodesignKey={{identity}} -p:PackageSigningKey={{installer_identity}} -p:UnoMacOSNotarizeKeychainProfile={{notarytool-credentials}} -bl
```

where

- `{{notarytool-credentials}}` is the name of your credentials inside the key store
- `-bl` will create a binary log of your build. This will include information about the notarization process.

> [!NOTE]
> Running this command might [take a while](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow) as it will wait for the notarization process to complete on Apple servers.

Once completed you can distribute the package installer.

### Disk Image (.dmg)

Another common way to distribute your macOS software is to create a disk image (.dmg). This will produce a single, compressed disk image that can be shared (if signed and notarized) with anyone using a Mac computer.

To create a disk image from the CLI run:

```bash
dotnet publish -f net9.0-desktop -r {{RID}} -p:SelfContained=true -p:PackageFormat=dmg -p:CodesignKey={{identity}} -p:DiskImageSigningKey={{identity}}
```

Where the following changes to the original command are

- modifying `PackageFormat` to `dmg` to produce the disk image. This image will include the app bundle inside it, so the `CodesignKey` argument is still required;
- adding `-p:DiskImageSigningKey={{identity}}` to specify which identity should be used to sign the package. Like app bundles, the signing step requires using a `Developer ID Application: *` identity.

The resulting disk image will be located at `bin/Release/net9.0-desktop/{{RID}}/publish/{{APPNAME}}.dmg`.

#### Notarize the disk image

Like an installer (.pkg) a disk image is the outermost container that you'll share with customers and, as such, needs to be notarized by Apple.

The first step is to store your Apple Account credentials inside the key store. This makes all the further commands (and notarization) much simpler. From the CLI run:

```bash
xcrun notarytool store-credentials {{notarytool-credentials}} --apple-id john.appleby@platform.uno --team-id XXXXXXXXXX --password aaaa-bbbb-cccc-dddd
```

where

- `{{notarytool-credentials}}` is the name of your credentials inside the key store.
- `--apple-id` provides the email address used for your [Apple Account](https://developer.apple.com/account).
- `--team-id` provides your team ID, a 10-character code. [How to find it](https://developer.apple.com/help/account/manage-your-team/locate-your-team-id).
- `--password` is an [app specific password](https://support.apple.com/en-us/102654) created specifically for `notarytool`

> [!NOTE]
> Since Apple Accounts requires two factors authentication (2FA) you will need to [create an app-specific password](https://support.apple.com/en-us/102654) for `notarytool`.

```text
This process stores your credentials securely in the Keychain. You reference these credentials later using a profile name.

Validating your credentials...
Success. Credentials validated.
Credentials saved to Keychain.
To use them, specify `--keychain-profile "notarytool-credentials"`
```

Once this (one-time) setup is done, you can notarize the disk image while building the app. From the CLI run:

```bash
dotnet publish -f net9.0-desktop -r {{RID}} -p:SelfContained=true -p:PackageFormat=dmg -p:CodesignKey={{identity}} -p:DiskImageSigningKey={{identity}} -p:UnoMacOSNotarizeKeychainProfile={{notarytool-credentials}} -bl
```

where

- `{{notarytool-credentials}}` is the name of your credentials inside the key store
- `-bl` will create a binary log of your build. This will include information about the notarization process.

> [!NOTE]
> Running this command might [take a while](https://developer.apple.com/documentation/security/customizing-the-notarization-workflow) as it will wait for the notarization process to complete on Apple servers.

Once completed you can distribute the notarized disk image.

### Mac App Store

> [!IMPORTANT]
> Applications distributed on the Mac App Store are required to execute under a [sandbox](https://developer.apple.com/documentation/security/app-sandbox?language=objc), which imposes additional limits on how applications can interact with the computer.

An app bundle (.app) can be submitted to Apple's [App Store](https://www.apple.com/app-store/) using the [transporter app](https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds) from a computer running macOS.

> [!NOTE]
> Notarization of the app bundle is **not** required as the Apple App Store will be taking care of your app binary distribution.

## Troubleshooting

### Apple Developer Account

An active Apple Developer Account is **required** for code signing and notarization.

An error, such as the one below, means that the Apple Developer Account is not active or the necessary agreements have not been signed.

```text
Uno.Sdk.Extras.Publish.MacOS.targets(75,3): error : Failed to submit tmpcZQgA4.zip to Apple's notarization service. Exit code: 1: Error: HTTP status code: 403. A required agreement is missing or has expired. This request requires an in-effect agreement that has not been signed or has expired. Ensure your team has signed the necessary legal agreements and that they are not expired.
```

Try logging into your [Apple Developer Account](https://developer.apple.com/account) to see if any action is required to activate your account.
Once re-enabled, it might take a few minutes (for the update to propagate) before you can sign or notarize your app bundle.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-desktop.linux.md

---
uid: uno.publishing.desktop.linux
---

# Publishing Your App for Linux

## Snap Packages

We support creating .snap packages on **Ubuntu 20.04** or later.

### Requirements

The following must be installed and configured:

```bash
sudo apt-get install -y snapd
sudo snap install core22
sudo snap install multipass
sudo snap install lxd
sudo snap install snapcraft
lxd init --minimal
sudo usermod --append --groups lxd $USER # In order for the current user to use LXD
```

> [!NOTE]
> In the above script, replace `core22` with `core20` if building on Ubuntu 20.04, or `core24` if building on Ubuntu 24.04.
> [!NOTE]
> Docker may interfere with Lxd causing network connectivity issues, for solutions see:
> https://documentation.ubuntu.com/lxd/en/stable-5.0/howto/network_bridge_firewalld/#prevent-connectivity-issues-with-lxd-and-docker

### Generate a Snap file

To generate a snap file, run the following:

```shell
dotnet publish -f net9.0-desktop -p:SelfContained=true -p:PackageFormat=snap
```

The generated snap file is located in the `bin/Release/netX.0-desktop/linux-[x64|arm64]/publish` folder.

Uno Platform generates snap manifests in classic confinement mode and a `.desktop` file by default.

If you wish to customize your snap manifest, you will need to pass the following MSBuild properties:

- `SnapManifest`
- `DesktopFile`

You may use absolute or relative (to the `.csproj`) paths.

The `.desktop` filename MUST conform to the [Desktop File](https://specifications.freedesktop.org/desktop-entry-spec/latest) spec.

If you wish, you can generate a default snap manifest and desktop file by running the command above, then tweak them.

> [!NOTE]
> .NET 9 publishing and cross-publishing are not supported as of Uno 5.5, we will support .NET 9 publishing soon.

#### CI Restrictions

When building in a CI environment, security restrictions may prevent LXD and Multipass from running properly.

In such cases, and if your environment is built using single-use environments like Azure DevOps Hosted Agents, you can enable the Snap [destructive mode](https://snapcraft.io/docs/explanation-architectures#destructive-mode) with the following parameter to the `dotnet publish` command:

```bash
-p:UnoSnapcraftAdditionalParameters=--destructive-mode
```

> [!IMPORTANT]
> Using this mode will make destructive changes to your environment, make sure that you will use this mode on a single-use virtual environment (e.g. Docker or Azure DevOps Hosted Agents).

### Publish your Snap Package

You can install your app on your machine using the following:

```bash
sudo snap install MyApp_1.0_amd64.snap --dangerous --classic
```

You can also publish your app to the [Snap store](https://snapcraft.io/store).

## Limitations

- NativeAOT is not yet supported
- R2R is not yet supported
- Single file publishing is not yet supported

> [!NOTE]
> Publishing is a [work in progress](https://github.com/unoplatform/uno/issues/16440)

## Links

- [Snapcraft.yaml schema](https://snapcraft.io/docs/snapcraft-yaml-schema)
- [Desktop Entry Specification](https://specifications.freedesktop.org/desktop-entry-spec/latest)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-desktop.md

---
uid: uno.publishing.desktop
---

<!-- markdownlint-disable MD001 MD051 -->

# Publishing Your App For Desktop

## Preparing For Publish

- [Profile your app with Visual Studio](https://learn.microsoft.com/en-us/visualstudio/profiling)
- [Profile using dotnet-trace and SpeedScope](https://learn.microsoft.com/en-us/dotnet/core/diagnostics/dotnet-trace)

## Publish Using Visual Studio

- In the debugger toolbar drop-down, select the `net9.0-desktop` or `net10.0-desktop` target framework
- Once the project has reloaded, right-click on the project and select **Publish**
- Select the **Folder** target for your publication then click **Next**
- Select the **Folder** target again then **Next**
- Choose an output folder then click **Finish**
- The profile is created, you can now **Close** the dialog
- In the opened editor, click `Show all settings`
- Set **Configuration** to `Release`
- Set **Target framework** to `net9.0-desktop` or `net10.0-desktop`
- You can set **Deployment mode** to either `Framework-dependent` or `Self-contained`
  - If `Self-contained` is chosen and you're targeting Windows, **Target runtime** must match the installed .NET SDK runtime identifier
    as cross-publishing self-contained WPF apps (e.g. win-x64 to win-arm64) is not supported for now.
- You can set **Target runtime**, make sure it honors the above limitation, if it applies.
- Click **Save**
- Click **Publish**

## Publish Using The CLI

On Windows/macOS/Linux, open a terminal in your `csproj` folder and run:

```shell
dotnet publish -f net10.0-desktop
```

If you wish to do a self-contained publish, run the following instead:

```shell
dotnet publish -f net10.0-desktop -r {{RID}} -p:SelfContained=true -p:TargetFrameworks=net10.0-desktop
```

Where `{{RID}}` specifies [the chosen OS and Architecture](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog) (e.g. win-x64). When targeting Windows, cross-publishing to architectures other than the currently running one is not supported.

> [!IMPORTANT]
> Due to changes in the .NET SDK, when providing an `{{RID}}` you will also need to add the following parameter `-p:TargetFrameworks=net10.0-desktop` for the publish command to succeed.

### Single-file publish

[Single file](https://learn.microsoft.com/en-us/dotnet/core/deploying/single-file/overview?tabs=cli) publishing is supported with the following parameters:

```shell
dotnet publish -f net10.0-desktop -r {{RID}} -p:SelfContained=true -p:PublishSingleFile=true -p:IncludeNativeLibrariesForSelfExtract=true -p:IncludeAllContentForSelfExtract=true
```

Same as above, make sure to replace the `{{RID}}` with [a valid value](https://learn.microsoft.com/en-us/dotnet/core/rid-catalog).

The `IncludeNativeLibrariesForSelfExtract` and `IncludeAllContentForSelfExtract` properties can also be set in a `PropertyGroup` in the `.csproj`.

### Windows ClickOnce

Uno Platform supports publishing desktop apps using **ClickOnce** to Windows environments.

To publish your app that targets `net10.0-desktop` in your `.csproj`, you'll need to create a `.pubxml` file using Visual Studio, or use the file below:

# [**Using a Sample Profile**](#tab/windows)

Create a file named `Properties\PublishProfiles\ClickOnceProfile.pubxml` in your project with the following contents:

```xml
<?xml version="1.0" encoding="utf-8"?>
<!-- https://go.microsoft.com/fwlink/?LinkID=208121. -->
<Project>
  <PropertyGroup>
    <ApplicationRevision>0</ApplicationRevision>
    <ApplicationVersion>1.0.0.*</ApplicationVersion>
    <BootstrapperEnabled>True</BootstrapperEnabled>
    <Configuration>Release</Configuration>
    <CreateWebPageOnPublish>False</CreateWebPageOnPublish>
    <GenerateManifests>true</GenerateManifests>
    <Install>True</Install>
    <InstallFrom>Disk</InstallFrom>
    <IsRevisionIncremented>True</IsRevisionIncremented>
    <IsWebBootstrapper>False</IsWebBootstrapper>
    <MapFileExtensions>True</MapFileExtensions>
    <OpenBrowserOnPublish>False</OpenBrowserOnPublish>
    <Platform>x64</Platform>
    <PublishProtocol>ClickOnce</PublishProtocol>
    <PublishReadyToRun>False</PublishReadyToRun>
    <PublishSingleFile>False</PublishSingleFile>
    <RuntimeIdentifier>win-x64</RuntimeIdentifier>
    <SelfContained>True</SelfContained>
    <SignatureAlgorithm>(none)</SignatureAlgorithm>
    <SignManifests>False</SignManifests>
    <SkipPublishVerification>false</SkipPublishVerification>
    <TargetFramework>net10.0-desktop</TargetFramework>
    <UpdateEnabled>False</UpdateEnabled>
    <UpdateMode>Foreground</UpdateMode>
    <UpdateRequired>False</UpdateRequired>
    <WebPageFileName>Publish.html</WebPageFileName>

    <!-- Those two lines below need to be removed when building using "UnoClickOncePublishDir" -->
    <PublishDir>bin\Release\net10.0-desktop\win-x64\app.publish\</PublishDir>
    <PublishUrl>bin\publish\</PublishUrl>
  </PropertyGroup>
  <ItemGroup>
    <!-- This section needs to be adjusted based on the target framework -->
    <BootstrapperPackage Include="Microsoft.NetCore.DesktopRuntime.10.0.x64">
      <Install>true</Install>
      <ProductName>.NET Desktop Runtime 10.0.1 (x64)</ProductName>
    </BootstrapperPackage>
  </ItemGroup>
</Project>
```

# [**Using the Wizard**](#tab/vs-wizard)

> [!NOTE]
> An existing Visual Studio issue prevents the **Publish** context menu from being active
> if iOS/Android are present in the TargetFrameworks list. In order to create
> the file, you can temporarily remove those target frameworks from `TargetFrameworks` in
> order to create the `.pubxml` file generated.

To use the Visual Studio publishing wizard:

- Select the `netX.0-desktop` target framework in the debugger drop-down
- In the Solution Explorer, right click on your project then select **Publish**
- Click the **+ New profile** button
- Select **ClickOnce**, then **Next**
- Configure your app publishing in all the following wizard pages
- In the **Configuration** section, make sure to select **Portable** for the **Target runtime**
- Click **Finish**.

The `Properties\PublishProfiles\ClickOnceProfile.pubxml` file will be created.

***

Once done, you can use the following command in your CI environment, or using a **Developer Command Prompt for Visual Studio**:

```shell
msbuild /m /r /target:Publish /p:Configuration=Release /p:PublishProfile="Properties\PublishProfiles\ClickOnceProfile.pubxml" /p:TargetFramework=net9.0-desktop
```

The resulting package will be located in the `bin\publish` folder. You can change the output folder using `/p:UnoClickOncePublishDir=your\output\directory`.

Depending on your deployment settings, you can run the `Setup.exe` file to install the application on a machine.

> [!IMPORTANT]
> At this time, publishing with the [Visual Studio Publishing Wizard](https://learn.microsoft.com/visualstudio/deployment/quickstart-deploy-using-clickonce-folder?view=visualstudio)
> is not supported for multi-targeted projects. Using the command line above is required.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-ios.md

---
uid: uno.publishing.ios
---

# Publishing Your App for iOS

## Preparing For Publish

- [Performance Profiling](xref:Uno.Tutorials.ProfilingApplications)

## Building your app

### Packaging your app using the CLI

> [!IMPORTANT]
> Publishing for iOS is only supported on macOS

First, you'll need to setup to be able to build iOS apps. You can follow [these steps for publishing .NET iOS apps](https://learn.microsoft.com/dotnet/maui/ios/deployment/?view=net-maui-8.0).

Then, you'll need to setup your `csproj` to include the signing information:

```xml
<Choose>
    <When Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">
       <PropertyGroup Condition="'$(Configuration)'=='Release'">
         <CodesignKey>iPhone Distribution</CodesignKey>
         <RuntimeIdentifier>ios-arm64</RuntimeIdentifier>
       </PropertyGroup>
    </When>
</Choose>
```

To build your app from the CLI on macOS:

- Open a terminal, command line, or powershell
- Navigate to your `csproj` folder
- Publish the app using:

  ```shell
  dotnet publish -f net9.0-ios -c Release -o ./publish
  ```

The output `.ipa` file will be in the `publish` folder.

## Publishing your app on the App Store

Publishing your app is done through [the transporter app](https://developer.apple.com/help/app-store-connect/manage-builds/upload-builds) on macOS.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-overview.md

---
uid: uno.publishing.overview
---

# Publishing Your App (App Packaging)

Uno Platform provides **integrated, automated packaging** for every supported platform, covering desktop, mobile, web, and embedded, with no third-party tools or extra setup required.
Packaging is part of the standard `.NET publish` workflow, so you can go from code to distributable packages in a single command.

## Why It Matters

App packaging is the bridge between a working build and an installable application.
Each OS has unique signing, metadata, and distribution requirements, which can make deployment complex for cross-platform projects.

Typical tasks include:

- Building and publishing binaries
- Generating assets and manifests
- Applying code signing and notarization
- Assembling installable formats (MSIX, .app, APK, IPA, etc.)
- Preparing for distribution or app store submission

Traditionally, .NET developers rely on custom scripts or third-party tools to manage this complexity.
Uno Platform automates it out of the box.

## The Broader Platform Packaging Ecosystem

| Platform | Formats | Signing | Distribution | Complexity |
|-----------|----------|----------|---------------|-------------|
| **Windows** | MSIX, MSI, ClickOnce | Certificates | Microsoft Store, Direct | Multiple formats; Store validation |
| **macOS** | .app, .pkg, .dmg | Apple certs + notarization | App Store, Direct | Mandatory notarization; complex signing |
| **Linux** | Snap, AppImage, DEB, RPM | Optional | Snap Store, Direct | Multiple package managers |
| **Android** | APK, AAB | Keystore | Google Play, Direct | AAB for Play; Keystore management |
| **iOS** | IPA | Provisioning profiles | App Store, TestFlight | Strict signing; Profile management |
| **WebAssembly** | Static files, PWA | HTTPS / CSP | Web hosting | Service workers; PWA manifest |

## What Uno Platform Provides Out of the Box

Uno Platform simplifies all of this with a unified, automated approach:

| Platform | Package Formats | Code Signing | Store Ready | Status |
|-----------|----------------|---------------|-------------|---------|
| **Windows** | MSIX, ClickOnce | ✅ | ✅ Microsoft Store | ✅ Available |
| **macOS** | .app, .pkg, .dmg | ✅ | ✅ App Store | ✅ Available |
| **Linux** | Snap | ✅ | ✅ Snap Store | ✅ Available |
| **Android** | APK, AAB | ✅ | ✅ Google Play | ✅ Available |
| **iOS** | IPA | ✅ | ✅ App Store | ✅ Available |
| **WebAssembly** | Static files, PWA | ✅ | ✅ Web hosting | ✅ Available |

## Key Features

- **Native `dotnet publish` Integration** – No separate tools required. Works with your CI/CD pipelines.
- **Cross-Platform Build Support** – Build Windows packages from Linux or macOS, and vice versa.
- **Advanced Publishing Options** – Self-contained deployments, single-file packaging, Native AOT (where supported).
- **Automated Everything** – Manifest generation, asset resizing, signing, and platform-specific optimization.

Example command for Android AAB:

```bash
dotnet publish -f net9.0-android -p:AndroidPackageFormat=aab
```

The same command pattern applies to Windows, macOS, Linux, iOS, and WebAssembly.

## Preparing

Before publishing, make sure your app is optimized:

- [Configure the IL Linker](xref:uno.articles.features.illinker)
- [Enable XAML and Resource Trimming](xref:Uno.Features.ResourcesTrimming)
- [Improve Performance](xref:Uno.Development.Performance)

## Platform-Specific Guides

- [Packaging for Desktop](xref:uno.publishing.desktop) (`netX.0-desktop`)
- [Packaging for WebAssembly](xref:uno.publishing.webassembly) (`netX.0-browserwasm`)
- [Packaging for iOS](xref:uno.publishing.ios) (`netX.0-ios`)
- [Packaging for Android](xref:uno.publishing.android) (`netX.0-android`)
- [Packaging for Windows App SDK](xref:uno.publishing.windows) (`netX.0-windows10.yyy`)

## Continuous Integration

Uno Platform provides built-in [CI integrations](xref:Uno.GettingStarted.UsingWizard#11-ci-pipeline) for Azure DevOps and GitHub Actions, included as part of the Uno Platform project templates.
These pipelines include ready-to-use packaging steps for all supported platforms.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-webassembly.md

---
uid: uno.publishing.webassembly
---

# Publishing Your App for WebAssembly

## Preparing For Publish

- [Configure deep linking](xref:UnoWasmBootstrap.Features.DeepLinking)
- [Configure WebAssembly AOT modes](xref:Uno.Wasm.Bootstrap.Runtime.Execution)
- [Profile the memory of your app](xref:Uno.Wasm.Bootstrap.Profiling.Memory)

You can view more on the [WebAssembly Bootstrapper](xref:UnoWasmBootstrap.Overview) options.

## Packaging

### Packaging your app using Visual Studio 2022/2026

To build your app for WebAssembly:

- In the debugger toolbar drop-down, select the `net9.0-browserwasm` target framework
- Once the project has reloaded, right-click on the project and select **Publish**
- Select the appropriate target for your publication, this example will use the **Folder**, then click **Next**
- Choose an output folder for the published output, then click **Close**.
- In the opened editor, on the top right, click the **Publish** button
- Once the build is done, the output is located in the `wwwroot` folder

Once done, you can head over to [publishing section](xref:uno.publishing.webassembly#publishing).

### Packaging your app using the CLI

To build your app from the CLI, on Windows, Linux, or macOS:

- Open a terminal, command line, or powershell
- Navigate to your `csproj` folder
- Publish the app using:

  ```shell
  dotnet publish -f net9.0-browserwasm -c Release -o ./publish
  ```

- Once the build is done, the output is located in the `./publish/wwwroot` folder

Once done, you can head over to [publishing section](xref:uno.publishing.webassembly#publishing).

## Publishing your WebAssembly App

Publishing your app can be done to different servers and cloud providers.

- [How to host a WebAssembly App](xref:Uno.Development.HostWebAssemblyApp)
- [Publishing to Azure Static Apps](xref:Uno.Tutorials.AzureStaticWebApps)
- [Server locally using dotnet-serve](https://github.com/natemcmaster/dotnet-serve)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-windows-packaged-signed.md

---
uid: uno.publishing.windows.sideload.packaged.signed
---

# Build a signed packaged app

This guide will show how to create a signed packaged app using Windows App SDK.

> [!IMPORTANT]
> Building your app requires using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5).

## Package signed the app

This guide uses a self-signed certificate.

To package your app:

- Create a self-signed certificate:
  - Open the solution in Visual Studio
  - Ensure that the active debugging target framework is `net10.0-windows10.0.xxxxx`
  - Double-click on the `Package.appxmanifest` file
  - Navigate to the `Packaging` tab
  - Click the **Choose certificate** button
  - Click the **Create** button, then set a **publisher common name**, then OK. Do not set a password.
  - Close the **Choose a Certificate** window by clicking OK.
  - Click the **Save file** button in the Visual Studio toolbar
- Navigate to the folder of the app's `.csproj` (Building at the solution level is not supported)
- Build the app on the command line with the following command:

  ```shell
  # For .NET 9:
  msbuild /r /p:TargetFramework=net9.0-windows10.0.26100 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true
  
  # For .NET 10:
  msbuild /r /p:TargetFramework=net10.0-windows10.0.26100 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=true
  ```

To package your app for the Microsoft App Store, the process is similar to creating a self-signed app package with just a minor difference:

- Instead of linking to a self-signed certificate, associate your project with a Microsoft Store Application by right-clicking on your project in the solution explorer, then the **Publish**, **Associate App with Store...** menu item.
- Build the app on the command line with the following command:

  ```shell
  msbuild /r /p:TargetFramework=net9.0-windows10.0.26100 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=StoreUpload /p:AppxPackageDir="C:/temp/output/"
  ```

In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files.

> [!IMPORTANT]
> Single package msix bundling is [not yet supported from msbuild the command line](https://learn.microsoft.com/windows/apps/windows-app-sdk/single-project-msix?tabs=csharp#automate-building-and-packaging-your-single-project-msix-app). The individual msix packages can be assembled after creation using Microsoft's `makeappx.exe` tool installed with the Windows SDK in 'Windows Kits' folder, for example `C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\makeappx.exe`.

To bundle the individual msix packages, move them all to a common folder, for example, "C:\Temp\Output\MyApp", and run the following command:

```shell
  "C:\Program Files (x86)\Windows Kits\10\bin\10.0.19041.0\x64\makeappx.exe" bundle /d "C:\Temp\Output\MyApp" /p "C:\Temp\Output\MyApp.msixbundle"
```

> [!TIP]
> The `makeappx.exe` tool is also available from the environment when opening a [**Developer Command Prompt for VS 2022**](https://learn.microsoft.com/en-us/visualstudio/ide/reference/command-prompt-powershell?view=vs-2022)

## Considerations for solutions with class library projects

If your app references multiple library projects, you will need to split the above build command into two parts, one to restore NuGet packages, and the other one to create the package.

To build your solution:

- Add the following to your app's csproj:

  ```xml
  <PropertyGroup Condition=" '$(PublishSignedPackage)' == 'true' ">
    <GenerateAppxPackageOnBuild>true</GenerateAppxPackageOnBuild>
    <AppxBundle>Never</AppxBundle>
    <UapAppxPackageBuildMode>Sideloading</UapAppxPackageBuildMode>
    <AppxPackageSigningEnabled>true</AppxPackageSigningEnabled>  
  </PropertyGroup>
  ```

- Run this command to restore the NuGet packages:

  ```shell
  msbuild /r /t:Restore /p:Configuration=Release
  ```

- Then run this command:

  ```shell
  msbuild /p:TargetFramework=net9.0-windows10.0.26100 /p:Configuration=Release /p:Platform=x64 /p:PublishSignedPackage=true /p:AppxPackageDir="C:/temp/output/"
  ```

  Notice that this command does not contain the `/r`.

## Install the signed Windows app

To install the app:

- Install the certificate on the machine:
  - In the file explorer, right-click on the `.msix` file, then **Show More Options** on Windows 11, then **Properties**
  - Open the **Digital signatures** tab
  - Click on your certificate then **Details**
  - Click the **View Certificate** button
  - Click the **Install Certificate** button
  - Select **Local Machine** then **Next**
  - Click **Place all certificates in the following store** then **Browse**
  - Select **Trusted People** then **OK**
  - Click **Next**, then **Finish**
  - Close all the opened properties windows.
- Install the `.msix` by double-clicking on it

The app will start automatically once installed.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-windows-packaged-unsigned.md

---
uid: uno.publishing.windows.sideload.packaged.unsigned
---

# Build an unsigned packaged app

This guide will show how to create an unsigned packaged app using Windows App SDK.

> [!IMPORTANT]
> Building your app requires using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5).

## Package the unsigned app

Packaging the app without a code signature allows for installing the app on a machine without having to install the signer's certificate. This portion of the guide is derived from the [official Windows App SDK documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package).

To package your app:

- Update the `Package.appxmanifest` file with the following `Identity` node to include the following `OID`:

  ```xml
  <Identity Name="MyApp"
            Publisher="CN=AppModelSamples, OID.2.25.311729368913984317654407730594956997722=1"
            Version="1.0.0.0" />
  ```

- Navigate to the folder of the app's `.csproj` (Building at the solution level is not supported)
- Build your app using the following command:

    ```pwsh
    msbuild /r /p:TargetFramework=net9.0-windows10.0.26100 /p:Configuration=Release /p:Platform=x64 /p:GenerateAppxPackageOnBuild=true /p:AppxBundle=Never /p:UapAppxPackageBuildMode=Sideloading /p:AppxPackageDir="C:/temp/output/" /p:AppxPackageSigningEnabled=false
    ```

In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files.

## Considerations for solutions with class library projects

If your app references multiple library projects, you will need to split the above build command into two parts, one to restore NuGet packages, and the other one to create the package.

To build your solution:

- Add the following to your app's csproj:

  ```xml
  <PropertyGroup Condition=" '$(PublishUnsignedPackage)' == 'true' ">
    <GenerateAppxPackageOnBuild>true</GenerateAppxPackageOnBuild>
    <AppxBundle>Never</AppxBundle>
    <UapAppxPackageBuildMode>Sideloading</UapAppxPackageBuildMode>
    <AppxPackageSigningEnabled>false</AppxPackageSigningEnabled>  
  </PropertyGroup>
  ```

- Run this command to restore the NuGet packages:

  ```pwsh
  msbuild /r /t:Restore /p:Configuration=Release
  ```

- Then run this command:

  ```pwsh
  msbuild /p:TargetFramework=net9.0-windows10.0.26100 /p:Configuration=Release /p:Platform=x64 /p:PublishUnsignedPackage=true /p:AppxPackageDir="C:/temp/output/"
  ```

  Notice that this command does not contain the `/r`.

## Install the unsigned Windows app

To install the app:

- Start an elevated PowerShell command prompt (Search for PowerShell in the start menu, right-click on it then Run as administrator):
- In the folder containing the `.msix` file, execute the following command :

    ```pwsh
    Add-AppPackage -AllowUnsigned ".\MyApp.appx"
    ```

For more information, see the [official documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package#install-an-unsigned-package).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-windows-unpackaged.md

---
uid: uno.publishing.windows.sideload.unpackaged.unsigned
---

# Publish an unpackaged app

This guide will show you how to create an unpackaged app using Windows App SDK.

> [!IMPORTANT]
> Building your app requires using the msbuild command (`dotnet build` is not compatible as of WinAppSDK 1.5).
> [!NOTE]
> Uno Platform also supports building apps for using the `net9.0-desktop` target framework, using Uno Platform's own Skia Desktop implementation.

## Build the app for publishing

Packaging the app without a code signature allows the app to be installed on a machine without installing the signer's certificate. This guide portion is derived from the [official Windows App SDK documentation](https://learn.microsoft.com/en-us/windows/msix/package/unsigned-package).

To publish your app:

1. Navigate to the folder of the app's `.csproj` (Building at the solution level is not supported)
2. Build your app using the following command:

    ```pwsh
    msbuild /r /t:publish /p:TargetFramework=net9.0-windows10.0.26100 /p:Configuration=Release /p:Platform=x64 /p:PublishDir=c:\temp\myoutput
    ```

In order to build for additional platforms, change the `Platform` parameter to `x86` or `arm64` to create additional MSIX files.

## Publish the Windows app

Publishing your app can be done through different means:

- [ClickOnce](https://learn.microsoft.com/visualstudio/deployment/quickstart-deploy-using-clickonce-folder?view=vs-2022)
- Using a Zip file, then running the app using `[yourapp].exe`

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-publishing-windows.md

---
uid: uno.publishing.windows
---

# Publishing Your App for Windows App SDK

## Preparing For Publish

## Building your app

Using the Windows App SDK, it's possible to side-load an app using the following:

- [Build an unsigned packaged app](xref:uno.publishing.windows.sideload.packaged.unsigned)
- [Build a signed packaged app](xref:uno.publishing.windows.sideload.packaged.signed)
- [Build an unpackaged app](xref:uno.publishing.windows.sideload.unpackaged.unsigned)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-toolchain-telemetry.md

---
uid: Uno.Development.ToolchainTelemetry
---

# Uno Platform Build tools telemetry

The [Uno Platform SDK](https://github.com/unoplatform/uno) includes a [telemetry feature](https://github.com/unoplatform/uno.devtools.telemetry)
that collects usage information. It is important that the Uno Platform Team understands how the build tools are used so they can be improved.

The collected data is anonymous.

The telemetry behavior is based on the [.NET Core telemetry feature](https://learn.microsoft.com/dotnet/core/tools/telemetry).

## Scope

The build tooling is used to generate XAML from code during the compilation of an
Uno Platform project. This step collects telemetry.

The application resulting of that build **does not collect telemetry**.

## How to opt out

The Uno Platform SDK telemetry feature is enabled by default. Opt out of the telemetry feature by
setting a global environment variable `UNO_PLATFORM_TELEMETRY_OPTOUT` set to `1` or `true`, or with
an msbuild property named `UnoPlatformTelemetryOptOut` set to `1` or `true`.

## Data points

The feature collects the following data:

* Timestamp of invocation
* The step invoked
* The duration of the step
* The exception type if the generation fails
* If the build is running under a CI (Travis, Azure Devops, AppVeyor, Jenkins, GitHub Actions, BitBucket, Build kite, Codebuild, Drone, MyGet, Space, TeamCity)
* Operating system name, version, kernel version, and architecture
* The current culture
* The current Uno Platform nuget package version
* Target frameworks
* Hashed (SHA256) current working directory
* Hashed (SHA256) MAC address: a cryptographically anonymous and unique ID for a machine.

The feature doesn't collect personal data, such as usernames or email addresses. It doesn't scan your code and doesn't extract
sensitive project-level data, such as name, repo, or author. The data is sent securely to Microsoft servers using Microsoft Azure
Application Insights technology, held under restricted access, and published under strict security controls from secure Azure Storage systems.

The Uno Platform team wants to know how the build tools are used and if they're working well, not what you're
building with the Uno Platform. If you suspect that the telemetry is collecting sensitive data or that the
data is being insecurely or inappropriately handled, file an issue in the [unoplatform/uno](https://github.com/unoplatform/uno/issues)
repository for investigation.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/contributing/guidelines/updating-dependencies.md

---
uid: Uno.Contributing.UpdatingDependencies
---

# Guidelines for updating dependencies

We use Dependabot to notify the team of any updates to dependencies. Once a week, the robot will scan our dependencies and raise a pull-request if a new version is found. If an existing open pull-request is found for a dependency, it will be closed and replaced with a new pull-request..

## Internal dependencies

The following dependencies don't change the public API surface and are typically safe to merge and we could potentially [configure mergify to automatically merge them if CI passes](https://docs.mergify.com/workflow/automerge/):

- BenchmarkDotNet
- [FluentAssertions](https://github.com/unoplatform/uno/pull/1196)
- [NUnit3TestAdapter](https://github.com/unoplatform/uno/pull/1455)
- [NUnit.Runners](https://github.com/unoplatform/uno/pull/1122)
- [Microsoft.AppCenter](https://github.com/unoplatform/uno/pull/1175)
- [Microsoft.SourceLink.GitHub](https://github.com/unoplatform/uno/pull/1204)
- [Microsoft.NET.Test.Sdk](https://github.com/unoplatform/uno/pull/1203)
- [MSTest.TestAdapter](https://github.com/unoplatform/uno/pull/1126)
- [MSTest.TestFramework](https://github.com/unoplatform/uno/pull/1128)
- Moq

The following dependencies require manual adjustments before merging:

- [docfx.console](https://github.com/unoplatform/Uno/pull/1082/commits/c222caf8c23b35e19f6b33cd624cbfa714250bfe)
- `Microsoft.CodeAnalysis.*`. Those dependencies need to be aligned with the source generation task package, for which the dependency cannot be be explicitly provided.
- `Xamarin.GooglePlayServices.*`. Those dependencies are added per TargetFramework (Android SDK version), not updated.

## Public dependencies

Updating public dependencies will require consumers to upgrade their dependencies and as such need consideration on a case by case basis is required before merging.

## additional care required

The following dependencies require care and human testing:

- [Microsoft.CodeAnalysis.*](https://github.com/unoplatform/uno/pull/1169) children packages needs to be aligned with the other `Microsoft.CodeAnalysis` packages.
- [Microsoft.Build.*](https://github.com/unoplatform/uno/pull/1169) children packages needs to be aligned with the other `Microsoft.Build` packages.
- [Microsoft.Extensions.Logging.*](https://github.com/unoplatform/uno/pull/1108/files#r300432589) child packages needs to be aligned with the other `Microsoft.Extensions.Logging` packages. Currently can't be upgraded because most recent versions are using thread, which are not supported on Wasm.
- [Microsoft.UI.Xaml](https://github.com/unoplatform/uno/pull/1503): This dependency is needs to be aligned with the currently supported API set found in Uno.
- [Microsoft.Extensions.Logging.Console](https://github.com/unoplatform/Uno/pull/894#issuecomment-495046929): Compatibility of this dependency should be confirmed against WebAssembly.

## chatops

You can trigger Dependabot actions by commenting on the pull-request:

```text
@dependabot recreate will recreate this PR, overwriting any edits that have been made to it
@dependabot ignore this [patch|minor|major] version will close this PR and stop Dependabot creating any more for this minor/major version (unless you reopen the PR or upgrade to it yourself)
@dependabot ignore this dependency will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself)
```

Please do not use any of the `rebase|merge|squash and merge` chatops commands as they bypass our merging pull-request guidelines and `ready-to-merge` workflow.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/updating-to-winui3.md

---
uid: Uno.Development.UpdatingToWinUI3
---

# Updating an Uno application to WinUI 3.0

Uno Platform supports authoring apps using [WinUI 3's API](uwp-vs-winui3.md). This article details the changes required when migrating an application from the UWP API set to the WinUI 3 API set.

[Read more about WinUI 3 and Uno Platform.](uwp-vs-winui3.md)

## Migrating an app to WinUI 3.0

- **NuGet updates:**
  - `Uno.UI` becomes `Uno.WinUI`
  - `Uno.UI.DevServer` becomes `Uno.WinUI.DevServer`
  - `Uno.UI.Lottie` becomes `Uno.WinUI.Lottie`
  - `Uno.UI.Foldable` becomes `Uno.WinUI.Foldable`
- **String replacements:**
  - `Windows.UI.Xaml` becomes `Microsoft.UI.Xaml`
  - `Windows.UI.Composition` becomes `Microsoft.UI.Composition`
- **Update `App.xaml.cs`:**
  - If your solution was created with an older version of the Uno app template, you'll need to update `App.xaml.cs` for compatibility with WinUI 3/Project Reunion.

        Fixes to apply:
    - Ensure `Window` doesn't fall out of scope ([diff](https://github.com/unoplatform/uno/commit/0d5418dada17561f857cf13750762468b77dfbf0))
    - Fix invalid defines ([diff](https://github.com/unoplatform/uno/commit/a4c3d3f5ec65071041a7b93f64d7175fbde189ac))

## API Changes

### Changed or removed controls

- `MapControl` is missing
- `MediaPlayerElement` is missing
- `WebView` is now `WebView2`

For a full list of unavailable controls and visual features, as well as timelines for restoration in some cases, consult the [WinUI 3 Feature Roadmap](https://github.com/microsoft/microsoft-ui-xaml/blob/master/docs/roadmap.md#winui-30-feature-roadmap).

### WinRT API changes for Desktop apps

Some WinRT APIs are unsupported in WinUI 3 Desktop apps, notably `CoreDispatcher`, `CoreWindow`, and `ApplicationView`. Consult [this guide](https://github.com/microsoft/microsoft-ui-xaml/blob/master/docs/winrt-apis-for-desktop.md) for supported alternatives to those APIs. `DispatcherQueue`, the replacement for `CoreDispatcher` in WinUI 3, is supported by Uno Platform.

## Creating an application from the templates

Instructions are available in [Getting started with WinUI 3](get-started-winui3.md) for creating a new Uno Platform application targeting WinUI 3.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/upgrading-nuget-packages.md

---
uid: Uno.Development.UpgradeUnoNuget
---
# How to upgrade Uno Platform NuGet Packages

Upgrading packages in your applications is done differently, depending on how your solution has been created.

- If your Uno Platform `.csproj` files start with `<Project Sdk="Uno.Sdk"`, you are using the [Uno.Sdk](xref:Uno.Features.Uno.Sdk) structure introduced in Uno Platform 5.1.
- If not, you are using the original project structure provided before Uno Platform 5.1.

Choose one of the sections below depending on your situation.

## Projects using the Uno.Sdk

The latest version of the Uno.Sdk is [![NuGet](https://img.shields.io/nuget/v/uno.sdk.svg)](https://www.nuget.org/packages/uno.sdk/).

To upgrade the Uno.Sdk, you'll need to open the `global.json` file located at the root of the solution, which typically looks like this:

```json
{
  "msbuild-sdks": {
    "Uno.Sdk": "xx.yy.zz",
  }
}
```

Update the `xx.yy.zz` property to the latest Uno.Sdk version, then save the file.

> [!IMPORTANT]
> In Visual Studio 2022/2026, once the Uno Version is updated, a banner will ask to restart the IDE. Once the solution is reopened the changes will take effect.
>
> At this time, the NuGet package Manager does not parse or manage Sdks provided by NuGet. If you would like to see this feature added, please be sure to provide your [feedback or upvote this issue](https://github.com/NuGet/Home/issues/13127).

You can also browse the available versions of the Uno.Sdk using [Nuget Package Explorer](https://nuget.info).

## Projects without the Uno.Sdk

To upgrade NuGet packages without the Uno.Sdk, you can use the [Nuget Package Manager](https://learn.microsoft.com/en-us/nuget/consume-packages/install-use-packages-visual-studio) coming from Visual Studio. Choose the latest stable versions of Uno Platform's NuGet packages.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/upri-trimming.md

---
uid: Uno.Features.StringResourceTrimming
---

# String Resource Trimming

Uno Platform provides a set of controls that are localized in many cultures, which may not be required for your app.

String resource trimming is an optional feature used to reduce the final payload size of an Uno Platform application by removing unused localization languages throughout the app.

## Using String Resource Trimming

To enable resources trimming, you need to declare which culture(s) your application uses. For example, in your csproj add:

```xml
<ItemGroup>
    <UnoSupportedLanguage Include="en-US" />
    <UnoSupportedLanguage Include="fr-CA" />
</ItemGroup>
```

You do not need to include parent cultures (`en` and `fr` in the previous example), they are automatically kept because they may be used as a fallback.

Make sure to update [Uno.Wasm.Bootstrap](https://www.nuget.org/packages/Uno.Wasm.Bootstrap) to the latest 7.0.x or 8.0.x version.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-il-linker-webassembly.md

---
uid: uno.articles.features.illinker
---

# Using the IL Linker

> [!NOTE]
> This article is about the .NET IL Linker, you can also view information about [XAML and Resources Trimming](xref:Uno.Features.ResourcesTrimming).

## Support for features

In order to improve the size of the application, some platforms are providing the ability to unconditionally disable features if the app is known not to use them.

|Feature|MSBuild property|Description|
|-----|----|---|
|External Drag and Drop|`UnoDragDropExternalSupport`|Enables or disables drag and dropping content from **outside** the app using this property. Drag and Drop **inside** the app is always available when disabled.|

For example, to disable external drag and drop support on WebAssembly, add the following to your csproj:

```xml
<PropertyGroup>
    <UnoDragDropExternalSupport>false</UnoDragDropExternalSupport>
</PropertyGroup>
```

## WebAssembly

The [linker step](https://github.com/dotnet/linker/tree/main/docs) (also known as tree shaking, or IL Trimming) is responsible for the detection and removal of code that may not be used at runtime. This step is particularly important when targeting WebAssembly or native code in general, to reduce significantly the final package size.

The linker is generally efficient at removing code but in some cases it may remove too much code, making some assemblies fail to work properly. In particular, assemblies or features that rely on reflection don't work by default with the linker enabled. `JSON.NET` is a good example of this, as it relies on reflection very heavily.

To handle cases where the default linker behavior removes too much code, the linker can be manually configured using the `LinkerConfig.xml` file in Uno projects.

When parts of an application fail to work, you can:

- Add full assembly names to the `LinkerConfig.xml` file:

```xml
<assembly fullname="MyAssembly" />
```

- Add namespaces for the linker to ignore:

```xml
<assembly fullname="MyAssembly">
  <!-- This is required by Json.NET and any expression.Compile caller -->
  <type fullname="MyNamespace*" />
</assembly>
```

As a troubleshooting step to determine if the linker is causing your code to break, you can also disable the linker completely by adding the following to your `csproj` file:

```xml
<PropertyGroup>
  <WasmShellILLinkerEnabled>false</WasmShellILLinkerEnabled>
</PropertyGroup>
```

Note that disabling the linker is not recommended as it can force the compiler to generate very large WebAssembly modules AOT process, and go over the browser's size limits.

You can find additional information about the linker step in Uno Platform in the [Linker configuration documentation](https://github.com/unoplatform/Uno.Wasm.Bootstrap/blob/main/doc/linker-configuration.md).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-linux-framebuffer.md

---
uid: Uno.Skia.Linux.Framebuffer
---

# Using the Linux FrameBuffer and `libinput`

Uno Platform supports the [Linux FrameBuffer](https://www.kernel.org/doc/html/latest/fb/framebuffer.html) and [libinput](https://wayland.freedesktop.org/libinput/doc/latest/what-is-libinput.html) as a target, in the case where your target device does not provide a Window Manager.

There are some restrictions for the support for the FrameBuffer:

- The mouse is supported through pointer events, but Uno Platform does not show the pointer for your app. You'll need to display one using the pointer events provided by Uno Platform (also in the `CoreWindow` class).
- It is only supported on Linux where `/dev/fbXX` is available.

## Get started with the FrameBuffer

- Follow the [getting started guide](xref:Uno.GetStarted.vscode)

Create a new app using:

```dotnetcli
dotnet new unoapp -o MyApp
```

In the `Platforms/Desktop/Program.cs` file, the `UnoPlatformHostBuilder` can be configured to use the Framebuffer support, in case X11 support is detected first:

```csharp
var host = UnoPlatformHostBuilder.Create()
    .App(() => new App())
    .UseX11()
    .UseLinuxFrameBuffer()
    .UseMacOS()
    .UseWindows()
    .Build();
```

Each platform support is evaluated in order for availability and definition in builder. X11 is chosen when the `DISPLAY` variable is present.

## Running the app

You can build and run this app by navigating to the `MyApp` and type the following:

```dotnetcli
dotnet run -f net9.0-desktop
```

The app will start and display on the first available framebuffer device. To change the active framebuffer, set the device name in the `FRAMEBUFFER` environment variable.

By default, the `Debug` configuration is used, which will show logging information in the current terminal and may overwrite the UI content.

To read the logging information, either:

- Launch the application from a different terminal (through SSH, for instance)
- Launch the app using `dotnet run -f net9.0-desktop > logging.txt 2>&1`, then launch `tail -f logging.txt` in another terminal.

Once the application is running, you can exit the application with:

- `Ctrl+C`
- `F12`, a key configuration found in the `Program.cs` file of your project which invokes `Application.Current.Exit()`

## Creating a standalone app

You can create a standalone publication folder using the following:

```dotnetcli
dotnet publish -c Release -f net9.0-desktop -r linux-x64 --self-contained true
```

> [!NOTE]
> When using the `Release` configuration, logging is disabled for performance considerations. You can restore logging in the `App.xaml.cs` file.

Documentation on other hardware targets is [available here](https://github.com/dotnet/core/blob/main/release-notes/8.0/supported-os.md).

## DPI Scaling support

Whenever possible, the `FrameBufferHost` will try to detect the actual DPI scale to use when rendering the UI, based on the physical information provided by the FrameBuffer driver. If the value cannot be determined, a scale of `1.0` is used.

The automatic scaling can be overridden in two ways:

- Set a value using `FrameBufferHost.DisplayScale`.
- Set a value through the `UNO_DISPLAY_SCALE_OVERRIDE` environment variable. This value has precedence over the value specified in `FrameBufferHost.DisplayScale`.

## Additional dependencies

If your device is significantly trimmed down for installed packages, you'll need to install:

- `libfontconfig`
- `libfreetype`
- `libinput`

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-markup.md

---
uid: uno.development.using.markup
---

# UI Markup

Uno Platform provides two ways for defining your UI: WinUI XAML or [C# Markup](xref:Uno.Extensions.Markup.Overview).

You can choose either one for developing your application, based on your preferences.

> [!NOTE]
> At this time, [Hot Design](xref:Uno.HotDesign.Overview) only supports designing XAML markup files.

## XAML Markup

XAML is an XML based UI definition declarative language, and Uno Platform uses the WinUI 3 flavor.

Elements such as `Grid`, `StackPanel` and `TextBlock` can be used to defined your user interface.

For more information about XAML, see the [Microsoft documentation](https://learn.microsoft.com/en-us/windows/apps/design/layout/) on the topic.

## C# Markup

C# Markup is a declarative, fluent-style syntax for defining the layout of an application in C#.

With C# Markup, you can define both the layout and the logic of your application using the same language. C# Markup leverages the same underlying object model as XAML, meaning that it has all the same capabilities, such as data binding, converters, and access to resources. You can use all the built-in controls, any custom controls you create, and any 3rd party controls, all from C# Markup.

For more information, see our overview of [C# Markup](xref:Uno.Extensions.Markup.Overview).

## Related documentation

- [WinUI Development topics](xref:Uno.Development.WinUIDevelopmentDoc)
- [WinUI Design](xref:Uno.Development.WinUIDesignDoc)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-native-rendering.md

---
uid: uno.features.renderer.native
---

# The Native Renderer

The native renderer is our oldest backend, which uses the native components and APIs to render the UI.

Each supported platform (iOS, Android, and WebAssembly) has its own set of platform interactions, listed below, allowing for deep integration of native components into the visual tree. Each `UIElement` has a corresponding native element (`div` on WebAssembly, `UIView` on iOS, `ViewGroup` on Android).

This renderer uses the native input controls of the platforms, providing the best access to accessibility and IME features.

This renderer supports [integrating native views](xref:Uno.Development.NativeViews).

## Web (WebAssembly)

On WebAssembly, XAML elements are translated into HTML elements:

- Panels and layout containers are materialized as `<div>`
- Leaf controls like `TextBlock`, `Image` are materialized as semantic elements like `<p>`, `<img>`, etc.

This rendering integrates with CSS and DOM APIs, enabling UI behavior consistent with web standards.

## iOS

- All `FrameworkElement` types are backed by native `UIView` instances.
- Controls like `Image` implicitly create native `UIImageView` subviews.
- Native input, layout, and accessibility features are utilized.

## Android

- All `FrameworkElement` types inherit from native `ViewGroup`.
- Controls like `Image` wrap native `ImageView` instances.
- Leverages Android’s native rendering, accessibility, and gesture systems.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-skia-desktop.md

---
uid: Uno.Skia.Desktop
---

# Using the Skia Desktop

Uno Platform supports running applications using a common Skia Desktop shell, which is automatically used based on the running platform, using a single build output using the `net9.0-desktop` target framework from the [Uno.Sdk](xref:Uno.Features.Uno.Sdk).

The currently supported targets and platforms are:

- Linux X11
- [Linux Framebuffer](xref:Uno.Skia.Linux.Framebuffer)
- Windows (Using Win32 shell)
- [macOS (Using an AppKit shell)](xref:Uno.Skia.macOS)

The set of supported platforms can be defined by using the `UnoPlatformHostBuilder`, introduced in Uno Platform 5.2 and the [Single Project support](xref:Uno.Development.MigratingToSingleProject).

## Get started with the Skia Desktop head

Follow the getting started guide for [VS Code](xref:Uno.GetStarted.vscode) or [Visual Studio](xref:Uno.GetStarted.vs2022), making sure to use the latest Uno Platform templates.

Once created, in the `Platforms/Desktop/Program.cs` file, you'll find the following builder:

```csharp
var host = UnoPlatformHostBuilder.Create()
   .App(() => new App())
   .UseX11()
   .UseLinuxFrameBuffer()
   .UseMacOS()
   .UseWin32()
   .Build();

host.Run();
```

This builder allows us to configure the SkiaHost and setup which platforms will be supported at runtime. The builder evaluates the platform's availability one by one, in the order of definition.

### Additional setup

#### [**Linux**](#tab/linux)

[!include[linux-setup](../includes/additional-linux-setup-inline.md)]

---

### Troubleshooting OpenGL integration

Enabling debug logging messages for the Skia Host can help diagnose the render surface type selection.

In your `App.xaml.cs` file, change the minimum log level to:

```csharp
builder.SetMinimumLevel(LogLevel.Debug);
```

Then change the logging level of the Skia Host to `Information` or `Debug`:

```csharp
builder.AddFilter("Uno.UI.Runtime.Skia", LogLevel.Information);
```

You may also need to initialize the logging system earlier than what is found in Uno.UI's default templates by calling this in `Main`:

```csharp
YourAppNamespace.App.ConfigureFilters(); // Enable tracing of the Skia host
```

## Upgrading to a later version of SkiaSharp

By default, Uno Platform comes with a set of **SkiaSharp** dependencies.

If you want to upgrade **SkiaSharp** to a later version, you'll need to specify all packages individually in your project as follows:

```xml
<ItemGroup>
   <PackagReference Include="SkiaSharp" Version="3.119.0" />
   <PackagReference Include="SkiaSharp.NativeAssets.Linux" Version="3.119.0" />
   <PackageReference Update="SkiaSharp.NativeAssets.macOS" Version="3.119.0" />
   <PackagReference Include="HarfBuzzSharp" Version="8.3.1.1" />
</ItemGroup>
```

## Windows Specifics

### RDP Hardware Acceleration

The Uno Platform Skia Desktop runtime on Windows uses a WPF shell internally. By default, Uno Platform enables RDP hardware acceleration in order to get good performance, yet this feature is disabled by default in standard WPF apps with .NET 8.

If you're having issues with the Windows support for Skia Desktop over RDP, add the following to your project:

```xml
<ItemGroup>
    <RuntimeHostConfigurationOption Include="Switch.System.Windows.Media.EnableHardwareAccelerationInRdp" Value="false" />
</ItemGroup>
```

## X11 Specifics

When running using X11 Wayland compatibility (e.g. recent Ubuntu releases), DPI scaling cannot be determined in a reliable way. In order to specify the scaling to be used by Uno Platform, set the `UNO_DISPLAY_SCALE_OVERRIDE` environment variable. The default value is `1.0`.

The X11 support uses DBus for various interactions with the system, such as file selection. Make sure that dbus is installed.

## .NET Native AOT support

Building an Uno Platform Skia Desktop app with .NET (7+) Native AOT requires Uno Platform 4.7 (or later).

To build an app with this feature enabled:

1. Add the following property in your `.csproj`:

   ```xml
   <PropertyGroup>
      <PublishAot>true</PublishAot>
   </PropertyGroup>
   ```

1. Add the following items in your `.csproj`:

   ```xml
   <ItemGroup>
      <TrimmerRootAssembly Include="MyApp" />
   </ItemGroup>
   ```

1. Build your app with:

   ```dotnetcli
   dotnet publish -c Release -f net9.0-desktop
   ```

   > [!NOTE]
   > Cross-compilation support is not supported as of .NET 7. To build a Native AOT app for Linux or Mac, you'll need to build on the corresponding host.
   > [!NOTE]
   > .NET Native AOT on Windows is not yet supported as WPF does not support it at this time.

For more information, see [the runtime documentation](https://github.com/dotnet/runtime/blob/main/src/coreclr/nativeaot/docs/reflection-in-aot-mode.md) and the [.NET Native AOT documentation](https://learn.microsoft.com/dotnet/core/deploying/native-aot/).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-skia-hosting-native-controls.md

---
uid: Uno.Skia.Embedding.Native
---

# Embedding Native Elements in Skia Apps

> [!NOTE]
> This document describes Skia renderer native embedding, for other platforms/renderers see the [native views](xref:Uno.Development.NativeViews) documentation.

In an Uno Platform app with a Skia renderer, i.e. using `net9.0-desktop` or adding `SkiaRenderer` to the `UnoFeatures` MSBuild property, you can embed native controls in your Skia app. This is useful if you want to use a native control for a specific task, for instance, to integrate an existing WPF control.

Each target platform has its own idea of a native element.

| Platform                        | Native element                                                                     | Description                                  |
|---------------------------------|------------------------------------------------------------------------------------|----------------------------------------------|
| Skia Desktop (Win32)            | Uno.UI.NativeElementHosting.Win32NativeWindow                                      | A native Windows window with a unique `Hwnd` |
| Skia Desktop (WPF)              | System.Windows.UIElement                                                           | A WPF control                                |
| Skia Desktop (X11)              | Uno.UI.NativeElementHosting.X11NativeWindow                                        | A native X11 window with a unique `XID`      |
| Skia Desktop (macOS)            | Not yet supported.                                                                 | Not yet supported as of Uno Platform 6.0     |
| WebAssembly with `SkiaRenderer` | [Uno.UI.NativeElementHosting.BrowserHtmlElement](xref:Uno.Interop.WasmJavaScript1) | An HTML element with a unique `id`.          |
| Android with `SkiaRenderer`     | Android.Views.View                                                                 | An Android view.                             |
| Apple UIKit with `SkiaRenderer` | UIKit.UIView                                                                       | An UIKit view.                               |

The app developer is responsible for creating the native element and internal checks make sure that only a supported native element on the running platform is used.

## Using embedded native controls

To embed a native element, you will need to set the native control as `Content` of a `ContentControl`, either via code or XAML. On desktop platforms, it's often more straightforward to create the native element via code since the parameters for creating the native element are not known ahead of time. For example, on Win32, you need to create a native Windows window first, get its `Hwnd` and then create a `Win32NativeWindow` instance with that `Hwnd` value.

Do not set a `ContentTemplate` or a `ContentTemplateSelector` on the `ContentControl`.

## Features

The layouting of native elements behaves mostly like regular `UIElement`s, using the native platform's measuring and arranging functions, e.g. `UIKit.UIView.SizeThatFits` on Apple UIKit, if they are present and defaulting to taking the entire available space on targets that don't have corresponding native measuring and arranging methods. On targets that don't have native measuring methods and expand to fill all available space, make sure that the wrapping `ContentControl` is not given infinite width or height when being measured, for example, by being put in a StackPanel. In those cases, limit the layout bounds by, for example, setting `MaxWidth`/`MaxHeight`/`Width`/`Height`.

> [!NOTE]
> `ContentControl` contains a `ContentPresenter` which hosts the actual native content. In the default `ContentControl` template, the `HorizontalAlignment` and `VerticalAlignment` of the `ContentPresenter` are bound to the `HorizontalContentAlignment` and `VerticalContentAlignment`, respectively, of the wrapping `ContentControl`, which are set by default to `Top` and `Left`, respectively. As a result, if your layout logic relies on the alignment/stretching of the `ContentControl`, you will likely want to set `<Horizontal|Vertical>ContentAlignment` to match `<Horizontal|Vertical>Alignment`.

Furthermore, native elements blend and overlap naturally with Uno controls and respect Z-axis ordering. For example, if you open a popup on top of a native element, the popup will show on top of the element. Native-managed blending is not limited to rectangular boundaries and elements clipped with arbitrary paths work as expected. For example, elements with rounded corners that are placed on a native element will not show up as rectangles but behave as usual with rounded corners.

Setting the `Opacity` of the wrapping `ContentControl` will also set the opacity of the hosted native element. Likewise, setting the `Visibility` of the wrapping `ContentControl` will flow to the native element and hide/show it.

> [!NOTE]
> As of Uno Platform 6.0, setting the opacity of native elements is not supported on X11.

## Limitations

The native control is rendered by the native windowing system and cannot be styled by Uno Platform styles.

While setting the transparency of native elements is supported, native elements don't alpha-blend. In other words, if a partially-transparent Uno control is placed on top of a native element, the native element will not be visible underneath the Uno control. Instead, the transparent area will behave as if the native element is not there and will only show managed Uno controls underneath.

Focus and pointer/keyboard input work as expected most of the time, but, depending on the platform, you might find some quirks with the way inputs are handled.

Placing Uno Controls outside of their layout bounds to be on top of native elements using `RenderTransform` or similar techniques will not clip correctly. The clipping of Uno controls is used to calculate which areas are painted by managed controls and how they overlap with native elements. If the clip bounds of a control are unbounded (i.e. the control isn't clipped at all), the clip bounds for managed-native overlapping purposes will be the layout rectangle of the control.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-skia-macos.md

---
uid: Uno.Skia.macOS
---

# Using the Desktop (Skia) on macOS

## Metal (Hardware Accelerated) Rendering

All recent Mac computers support Metal. It has been required to run macOS 10.14 (Mojave). As such macOS hardware-accelerated [Metal](https://developer.apple.com/metal/) rendering is enabled by default.

However, it's possible that under certain circumstances, like virtualization (including [GitHub CI](https://github.com/actions/runner-images/issues/1779)), Metal might not be available to applications. In this case, the host will **automatically** fall back to a software-based rendering.

> [!NOTE]
> Some Mac models released before 2012 did not support Metal. See Apple's support document [Support for Metal on Mac, iPad, and iPhone](https://support.apple.com/en-us/102894) for the list of devices that support Metal.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-skia-rendering.md

---
uid: uno.features.renderer.skia
---

# The Skia Renderer

Available on iOS, Android, macOS, Windows, Linux and WebAssembly, based on the [Skia](https://skia.org) drawing library, the Skia Renderer is a cross-platform unified rendering component of Uno Platform which provides a single UI experience across all supported platforms.

The whole UI Visual Tree is drawn on an hardware accelerated canvas, using Metal, OpenGL, and WebGL where applicable. Unlike Native rendering, Skia doesn’t rely on platform UI components.

The Skia Rendering backend has a very cheap cost for creating UI elements, which makes it very efficient for large user interfaces.

Starting with Uno.Sdk 6.0, **it is the default rendering engine** when creating a project from the templates. On **WebAssembly (Wasm)**, **Android**, and **iOS**, you can opt in to use the native rendering engine instead.

This renderer supports [integrating native views](xref:Uno.Skia.Embedding.Native).

> [!NOTE]
> The **WinAppSDK** target is not provided by Uno Platform directly, so it only offers the **native rendering mode**.

## How Skia Rendering Works

- The entire UI is drawn on a Skia canvas
- There are **no native views**; all visuals are composed in Skia using vector graphics
- A minimal native shell (like a window or web canvas) hosts the Skia surface

As the Skia Renderer bypasses native UI components, Skia can offer pixel-perfect rendering and visual consistency. The same UI is offered by default, but platform-specific theming is possible using [Uno.Themes](xref:Uno.Themes.Overview).

## Benefits

> [!TIP]
> If you are building a custom drawing application, charts, or games in Uno Platform, Skia can offer more flexibility and uniform visuals across platforms.

- **Consistent visuals**: Skia ensures pixel-perfect rendering across all supported platforms, making it ideal for applications where precise control over appearance is critical.
- **Custom drawing**: Ideal for apps requiring advanced graphics, custom controls, or canvas-based rendering—Skia gives you low-level drawing access, such as with the [SKCanvasElement](xref:Uno.Controls.SKCanvasElement).
- **Unified rendering pipeline**: Unlike native rendering, which varies by platform, Skia uses a single rendering backend, reducing platform-specific variations.
- **Improved rendering performance on desktop**: On platforms like Linux/macOS, Skia is often faster and more efficient than native alternatives.
- **Access to the full Composition API**: The Skia renderer provides access to the full [Composition API access for richer custom rendering](https://learn.microsoft.com/en-us/windows/apps/windows-app-sdk/composition).
- **Better control over visual updates**: You can fine-tune repainting behavior for animations, games, or dynamic content using Skia’s immediate mode rendering.
- **Smaller dependency surface**: By avoiding native UI components, Skia can simplify deployment—especially in environments like Wasm or containerized desktop apps.

## Using Skia rendering for new apps

You can use our [Visual Studio Wizard](xref:Uno.GettingStarted.UsingWizard) to create a new project. By default, the Wizard uses the Skia rendering engine, automatically setting up the necessary MSBuild properties and references for you. If you prefer to use native rendering instead, you can select it in the Wizard’s configuration options. You can find more details on how to use the Wizard here: [Creating a new project](xref:Uno.GettingStarted.UsingWizard).

> [!NOTE]
> If you're upgrading an existing project to Uno Platform 6.0, be sure to also check our migration guidance in [Migrating from previous releases](xref:Uno.Development.MigratingFromPreviousReleases).

## Using Skia rendering for existing apps

To enable Skia rendering in your Uno Platform project, you must opt in using MSBuild properties and features.

### Using Skia Desktop

On **macOS**, **Linux**, and **Windows**, using the `netX.0-desktop` target framework, Skia rendering is always used.

However, when using **WinAppSDK**, the **native rendering engine** is always used, regardless of whether Skia or Native is enabled in `UnoFeatures`.

> [!NOTE]
> Starting with Uno Platform 6.0, **Mac Catalyst** is no longer present in templates, and we encourage users to move to `netX.0-desktop`, which runs on macOS using Skia for rendering.

You can find more details in [Using the Skia Desktop](xref:Uno.Skia.Desktop).

### Upgrading to use Skia for iOS, Android, and WebAssembly

> [!TIP]
> If your project was created before Uno Platform 6.0 and you want to enable Skia rendering, [follow the upgrade guide](xref:Uno.Development.MigratingToUno6).

## Limitations

Using Skia rendering might have some limitations compared to native rendering. Some of the known limitations include:

- **Accessibility support**: Since Skia doesn't rely on native controls, accessibility tools (e.g., screen readers) are a work in progress. We're actively improving accessibility support in future releases.
- **Text rendering differences**: Font rendering may not match platform-specific expectations due to differences in text shaping and anti-aliasing.
- **IME support**: This portion of input support is also a work in progress, expect improvements in upcoming releases.
- **Limited hardware acceleration on some platforms**: Depending on the platform, Skia may fall back to software rendering, affecting the overall performance.
- Skia Rendering on WebAssembly is only supported on .NET 9 and later.
- Removing `SkiaRenderer` from `UnoFeatures` inside the project's `.csproj` file to target native rendering, then setting it back after a new build will raise a runtime Exception. You will need to remove `bin` and `obj` folders, and clear site data of the browser app in order to avoid encountering this exception.

Skia rendering is best suited for cross-platform scenarios where a unified appearance and customized graphics are key. Some native integration scenarios may not yet be supported. If you encounter any of such scenarios, make sure to let it be known by [opening an issue](https://github.com/unoplatform/uno/issues).

## Architecture

In order to accommodate the inclusion of Skia rendering for all platforms, the Uno Platform internal structure uses two layers of "bait-and-switch" of reference assemblies.

### Publish-time switching

When building in the `SkiaRenderer` node, an application compiles against "reference" versions of `Uno.UI`, `Uno.UI.Dispatching`, `Uno.UI.Composition`, `Uno`, and `Uno.Foundation`. When the application is being packaged, `Uno.UI` and `Uno.UI.Composition` are switched to the Skia-compatible versions. The `Uno.UI.Dispatching`, `Uno`, and `Uno.Foundation` are switched to their corresponding target platform versions.

By doing so, any use of the APIs provided by `Uno.UI.Dispatching`, `Uno`, and `Uno.Foundation` is automatically redirected to the proper platform support, for instance, redirecting `GeoLocator` to use the proper APIs provided by the underlying platform.

### Implications for iOS/Android class libraries

At this time, NuGet packages that provide UI features on iOS/Android may not be consumed by both native and Skia renderer projects under certain conditions.

The reason for this limitation is caused by the fact that Native renderers expose a different API set for `Microsoft.UI.Xaml` types, therefore causing incompatibility issues when apps use such a library.

Here are the different scenarios:

- Given a library that uses `net9.0-ios` or `net9.0-android`, which does not have the `SkiaRenderer` set as an `UnoFeature`, but uses platform conditional code with `#if` blocks:

  - This package is only usable by both native and Skia apps if it also provides a `net9.0` TFM. In this case, for a native app, nothing changes.
  - For a `SkiaRenderer` enabled app, the `net9.0` variant of the library will be used and will not offer iOS/Android specific conditional code, but any code that uses Uno Platform provided APIs will work properly.

- Given a library that uses `net9.0-ios` or `net9.0-android`, which does have the `SkiaRenderer` set as an `UnoFeature`, but uses platform conditional code with `#if` blocks:

  - This package is only usable by Skia-enabled apps.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.wasm.bootstrap/refs/heads/main/doc/using-the-bootstrapper.md

---
uid: UnoWasmBootstrap.Overview
---

# Using the bootstrapper

The Uno.Wasm.Bootstrap package provides a runtime bootstrapper of the `Microsoft.NET.Sdk.WebAssembly` SDK from .NET 9.

This package only provides the bootstrapping features to run a .NET assembly and write to the javascript console, through `Console.WriteLine`. To write an app that provides UI functionalities, make sur to check out https://aka.platform.uno/get-started.

This work is based on the excellent work from @praeclarum's [OOui Wasm MSBuild task](https://github.com/praeclarum/Ooui).

## Prepare your machine

On the command line, type the following to install the WebAssembly workload:

```bash
dotnet workload install wasm-tools
```

## How to use the Bootstrapper with .NET 9 and later

- Create a .NET 9 Console Application, and update it with the following basic definition:

  ```xml
  <Project Sdk="Microsoft.NET.Sdk.WebAssembly">

    <PropertyGroup>
      <OutputType>Exe</OutputType>
      <TargetFramework>net10.0</TargetFramework>
    </PropertyGroup>

    <ItemGroup>
      <PackageReference Include="Uno.Wasm.Bootstrap" Version="9.0.*" />
  </ItemGroup>

  </Project>
  ```

- Add a main entry point:

  ```csharp
  class Program
  {
      static void Main(string[] args)
      {
          Console.WriteLine("Hello from C#!");
      }
  }
  ```

- In Visual Studio 2022, press `F5` to start with the debugger
- A browser window will appear with your application
- The output of the Console.WriteLine will appear in the javascript debugging console

## How to use the Visual Studio 2022 Debugger

To enable the debugging, make sure that the following line is present in your `Properties/launchSettings.json` file:

```json
"inspectUri": "{wsProtocol}://{url.hostname}:{url.port}/_framework/debug/ws-proxy?browser={browserInspectUri}"
```

in every profile section of the file, below each `"launchBrowser": true,` line.

Press `F5` to start debugging.

## Alternate deployment methods

Install the [`dotnet serve`](https://github.com/natemcmaster/dotnet-serve) tool:

```dotnetcli
dotnet tool install -g dotnet-serve
```

Once installed, launch the server by using the following command:

```bash
cd MyApp.Wasm
dotnet publish -c Debug
dotnet serve -d bin\Debug\net10.0\publish\wwwroot -p 8000
```

You application will be available `http://localhost:8000`.

## Upgrading from previous versions of the Uno.Wasm.Bootstrap package

Moving from version 8.x to 9.x may require changing the used MSBuild SDK for your project.

- If your project contains `Sdk="Uno.Sdk"`, you will need to update the Uno.Sdk to 5.5 or later.
- If your project contains `Sdk="Microsoft.NET.Sdk.Web"`, you'll need to change it to `Sdk="Microsoft.NET.Sdk.WebAssembly"`.

Once done, make sure to install the WebAssembly tools from .NET:

```bash
dotnet workload install wasm-tools
```

By default, the .NET runtime does not load all resource assemblies, but if you want to load all resources regardless of the user's culture, you can add the following to your project file:

```xml
<PropertyGroup>
    <WasmShellLoadAllSatelliteResources>true</WasmShellLoadAllSatelliteResources>
</PropertyGroup>
```

If you're not using the Uno.SDK and that you are using AOT with `WasmShellMonoRuntimeExecutionMode` set to `InterpreterAndAOT`, you'll also need to keep `WasmShellMonoRuntimeExecutionMode` and add the following:

```xml
<PropertyGroup>
   <RunAOTCompilation>true</RunAOTCompilation>
</PropertyGroup>
```

If not set, you may get the error `error MSB4036: The "MonoAOTCompiler" task was not found"`.

### Threading

Microsoft’s runtime team [has made major changes](https://github.com/dotnet/runtime/issues/85592#issuecomment-2031876112) in .NET 9 to how threads interact with the DOM and JavaScript, aiming to improve stability.

Since threading was, and continues to be an experimental feature, these changes now prevent managed code from running on the main JavaScript thread — something Uno Platform depends on.

As a result, WebAssembly threading is currently not supported in Uno Platform apps. However, as Microsoft’s runtime team is working on it, we hope that the support for threading may return in future .NET 10 preview builds.

### IDBFS

In version 8.x and earlier of the bootstrapper, IDBFS support was enabled by default.

Moving the .NET 9, the default interpreter runtime does not enable it by default. Read this documentation in order to [restore IDBFS support](xref:UnoWasmBootstrap.Features.idbfs).

### Interop

- `Module.mono_bind_static_method` is not available anymore, you'll need to use `Module.getAssemblyExports` instead.
- .NET 9 upgrades to emscripten 3.1.56 for which `.bc` native files are not supported properly. Use `.a` or `.o` extensions instead for native dependencies.

### Build Errors

#### UNOWA0001

This error happens when the .NET for WebAssembly workload has not been detected:

```text
Native WebAssembly assets were detected, but the wasm-tools workload could not be located. Install it by running uno.check (https://aka.platform.uno/uno-check) or 'dotnet workload install wasm-tools'.
```

To fix this issue:

- If you're building with net10.0, either use [uno.check](https://aka.platform.uno/uno-check), or use `dotnet workload install wasm-tools` in the folder of your app's `csproj`.
- If you're building with net9.0 with the .NET SDK 10.0 installed, run [uno.check](https://aka.platform.uno/uno-check) then run `dotnet workload install wasm-tools-net9` in the folder of your app's `csproj`.

You can also validate manually that this workload is installed by running `dotnet workload list` in the folder of your app's `csproj.

### Deprecated APIs

- The `Uno.Wasm.Boostrap.DevServer` package is not needed anymore and can be removed
- `WasmShellOutputPackagePath` has been removed. Use `$(PublishDir)`
- `WasmShellOutputDistPath` has been removed. Use `$(PublishDir)`
- `WasmShellBrotliCompressionQuality`, `WasmShellCompressedExtension` and `WasmShellGenerateCompressedFiles` have been removed, the compression is done by the .NET SDK
- `WasmShellEnableAotGSharedVT` has been removed.
- `WasmShellEnableEmscriptenWindows` has been removed, the .NET SDK manages emscripten
- `WasmShellEnableLongPathSupport` has been removed, the .NET SDK manages the build
- `WasmShellEnableNetCoreICU`has been removed, the .NET SDK manages localization
- `WasmShellForceDisableWSL` and `WasmShellForceUseWSL` have been removed, Windows and Linux are supported natively by the .NET SDK.
- `WashShellGeneratePrefetchHeaders` has been removed.
- `WasmShellNinjaAdditionalParameters` has been removed, the .NET SDK manages the build
- `WasmShellObfuscateAssemblies`, `WasmShellAssembliesExtension` and `AssembliesFileNameObfuscationMode` have been removed, the .NET SDK uses WebCIL to achieve the same result.
- `WasmShellPrintAOTSkippedMethods` has been removed
- `WasmShellPThreadsPoolSize` has been removed in favor of the official .NET SDK parameters
- `MonoRuntimeDebuggerEnabled` has been removed, the .NET SDK manages the debugger
- `WashShellUseFileIntegrity` has been removed, the .NET SDK manages the assets integrity

## Bootstrapper versions and .NET runtimes

Each major version of the bootstrapper targets a different version of the .NET Runtime.

- 2.x: Mono runtime (https://github.com/mono/mono)
- 3.x: .NET 6 (https://github.com/dotnet/runtime/commits/release/6.0)
- 7.x: .NET 7 (https://github.com/dotnet/runtime/commits/release/7.0)
- 8.0: .NET 8 (https://github.com/dotnet/runtime/commits/release/8.0)
- 9.0: .NET 9 (https://github.com/dotnet/runtime/commits/release/9.0)
- 10.0: .NET 10 (https://github.com/dotnet/runtime/commits/release/10.0)

> [!NOTE]
> Between version 3.x and 8.x, the bootstrapper is using custom builds of the runtime, maintained here: https://github.com/unoplatform/Uno.DotnetRuntime.WebAssembly
>
> [!NOTE]
> Bootstrapper builds version 4.x-dev were based on developments builds of .NET 7 and were later versioned 7.x-dev to match the appropriate runtime.

## Previous releases documentation

- [8.0.x](https://github.com/unoplatform/Uno.Wasm.Bootstrap/tree/release/stable/8.0/doc)
- [7.0.x](https://github.com/unoplatform/Uno.Wasm.Bootstrap/tree/release/stable/7.0/doc)
- [3.x](https://github.com/unoplatform/Uno.Wasm.Bootstrap/tree/release/stable/3.3/doc)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/guides/using-the-server-project.md

---
uid: Uno.Guides.UsingTheServerProject
---

# The ASP.NET Core Server Project

As part of the uno platform templates, the server option is provided to allow the hosting of both an API server as well as a WebAssembly app. This allows you 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.

You will find [more information](xref:Uno.GettingStarted.UsingWizard#server) on how to use it from the solution wizard or `dotnet new` templates.

When creating an app with the server option enabled, you'll get:

- An app project, which contains a target framework with `net9.0-browserwasm`
- A server project, which references the app project and will by default host it at its root

## Using the server project

See below the specifics about the server project per IDE.

### Visual Studio

To run the project, set the server project as "startup project", then press F5 to enable the debugging.

> [!IMPORTANT]
> See the section below on HTTPS to ensure that debugging works properly

You can start debugging the app in the same way you would when starting the app project directly.

### VS Code

In order to launch the server project in VS Code:

- In a terminal, navigate to your `ReplaceMe.Server` folder
- Type `dotnet run -f net9.0 --launch-profile ReplaceMe.Server`

> [!IMPORTANT]
> See the section below on HTTPS to ensure that debugging works properly

Launching with the debugger is pending on [this issue](https://github.com/unoplatform/uno.templates/issues/1618).

### Rider

- Select the "ReplaceMe.Server" project in the top right debugger selector
- Start the app

> ![IMPORTANT]
> WebAssembly Debugging is [not yet supported](https://github.com/unoplatform/uno/issues/15226) in Rider.
> [!IMPORTANT]
> See the section below on HTTPS to ensure that debugging works properly

## Adjusting for HTTPS

As the app will run with https by default, you will get an error about "Mixed Content" not being supported.

To fix this when using Chrome or Edge:

- When the browser window opens for the first time, click on the padlock or section at the left of the address bar
  ![The security popup window with security options](../Assets/uno-guide-server-mixed-content-enable.png)
- Click the **Permissions for this site** option
- In the window that opened, search for **Insecure content** then select **Allow**. This will enable Hot Reload and Hot Design for this specific url/port.
  ![Allow mixed content option](../Assets/uno-guide-server-mixed-content-allowed.png)
- Close the browser window, ensure that the debugger has stopped in your IDE

You may also need to [trust the developer certificates](https://learn.microsoft.com/en-us/aspnet/core/security/enforcing-ssl?view=aspnetcore-9.0&tabs=visual-studio%2Clinux-sles#trust-the-aspnet-core-https-development-certificate):

```text
dotnet dev-certs https --trust
```

## Enabling HTTPS for the app project

If you want to enable for the app project, independently from the server project, you can modify your `Properties/launchSettings.json` file this way to use https first:

```json
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-the-uno-mcps.md

---
uid: Uno.Features.Uno.MCPs
---

# The Uno Platform MCPs

Uno Platform provides two [MCPs](https://modelcontextprotocol.io/docs/getting-started/intro):

- The Uno Platform Remote MCP, providing prompts and up-to-date documentation
- The Uno Platform Local App MCP, providing interactive access to your running application

This document explains how to interact with both those MCPs. You can find further below descriptions of the provided tools and prompts.

## MCP (Remote)

This is a remotely hosted publicly and provides:

- A set of tools to search and fetch Uno Platform documentation
- A set of prompts to create and develop Uno Platform applications.

### Predefined Prompts

The prompts provided by the MCP are automatically registered in your environment when supported by your AI agent (e.g., Claude, Codex, Copilot, etc.).

Here are the currently supported prompts:

- `/new`, used to create a new Uno Platform app with the best practices in mind.
- `/init`, used to "prime" your current chat with Uno's best practices. It's generally used in an existing app when adding new features.

### Sample Prompts for Uno MCP Servers

You can find common prompts to use with agents in our [getting started](xref:Uno.BuildYourApp.AI.Agents) section.

### Uno MCP Tools

The Uno MCP tools are the following:

- `uno_platform_docs_search` used by Agents to search for specific topics. It returns snippets of relevant information.
- `uno_platform_docs_fetch` used by Agents to get a specific document, grabbed through `uno_platform_docs_search`.
- `uno_platform_agent_rules_init` used by Agents to "prime" the environment on how to interact with Uno Platform apps during development.
- `uno_platform_usage_rules_init` used by Agents to "prime" the environment on how to Uno Platform's APIs in the best way possible

Those tools are suggested to the agent on how to be used best. In general, asking the agent "Make sure to search the Uno Platform docs to answer" will hint it to use those tools.

> [!NOTE]
> You can unselect `uno_platform_agent_rules_init` and `uno_platform_usage_rules_init` in your agent to avoid implicit priming, and you can use the `/init` prompt to achieve a similar result.

## App MCP (Local)

This MCP is running locally and provides agents with the ability to interact with a running app, in order to click, type, analyze or screenshot its content.

These tools give "eyes" and "hands" to Agents in order to validate their assumptions regarding the actions they take, and the code they generate.

> [!NOTE]
> If using Visual Studio 2022/2026, sometimes the Uno App MCP does not appear in the Visual Studio tools list. See [how to make the App MCP appear in Visual Studio](xref:Uno.UI.CommonIssues.AIAgents#the-app-mcp-does-not-appear-in-visual-studio).

### App MCP Tools

The Community license MCP app tools are:

- `uno_app_get_runtime_info`, used to get general information about the running app, such as its PID, OS, Platform, etc...
- `uno_app_get_screenshot`, used to get a screenshot of the running app
- `uno_app_pointer_click`, used to click at an X,Y coordinates in the app
- `uno_app_key_press`, used to type individual keys (possibly with modifiers)
- `uno_app_type_text`, used to type long strings of text in controls
- `uno_app_visualtree_snapshot`, used to get a textual representation of the visual tree of the app
- `uno_app_element_peer_default_action`, used to execute the default automation peer action on a UI element
- `uno_app_close`, used to close the running app

The Pro license App MCP app tools are:

- `uno_app_element_peer_action`, used to invoke a specific element automation peer action
- `uno_app_get_element_datacontext`, used to get a textual representation of the DataContext on a FrameworkElement

## Troubleshooting MCP Servers

You can find additional information about [troubleshooting AI Agents](xref:Uno.UI.CommonIssues.AIAgents) in our docs.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-the-uno-sdk.md

---
uid: Uno.Features.Uno.Sdk
---

# 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](https://marketplace.visualstudio.com/items?itemName=mhutch.msbuildeditor) to provide intellisense.

## Managing the Uno.Sdk version

Updating the Uno.Sdk is [done through the global.json file](xref:Uno.Development.UpgradeUnoNuget).

## 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:

```xml
<UnoFeatures>
    Material;
    Hosting;
    Toolkit;
    Logging;
    Serilog;
    MVUX;
    Configuration;
    Http;
    HttpRefit;
    HttpKiota;
    Serialization;
    Localization;
    Navigation;
    SkiaRenderer;
</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                                                                                                                                                                                                                                |
|----------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `Authentication`     | Adds the [Uno.Extensions](xref:Uno.Extensions.Overview) packages for Custom [Authentication](xref:Uno.Extensions.Authentication.Overview).                                                                                                 |
| `AuthenticationMsal` | Adds the [Uno.Extensions](xref:Uno.Extensions.Overview) packages for [Authentication](xref:Uno.Extensions.Authentication.Overview) using [Microsoft.Identity.Client](xref:Uno.Extensions.Authentication.HowToMsalAuthentication).          |
| `AuthenticationOidc` | Adds the [Uno.Extensions](xref:Uno.Extensions.Overview) packages for [Authentication](xref:Uno.Extensions.Authentication.Overview) using a custom [Oidc](xref:Uno.Extensions.Authentication.HowToOidcAuthentication) client.               |
| `Configuration`      | Adds the [Uno.Extensions](xref:Uno.Extensions.Overview) packages for [Configuration](xref:Uno.Extensions.Configuration.Overview).                                                                                                          |
| `CSharpMarkup`       | Adds support for [C# Markup](xref:Uno.Extensions.Markup.Overview).                                                                                                                                                                         |
| `Cupertino`          | Adds support for the [Cupertino Design Theme](xref:Uno.Themes.Cupertino.GetStarted) library. If the `Toolkit` feature is also used, it will add support for the [Cupertino Design Toolkit](xref:Toolkit.GettingStarted.Cupertino) library. |
| `Dsp`                | Adds support for the [Uno.Dsp.Tasks packages](https://www.nuget.org/packages?q=uno.dsp.tasks).                                                                                                                                             |
| `Extensions`         | Adds the most commonly used Extensions Packages for Hosting, Configuration, and Logging.                                                                                                                                                   |
| `Foldable`           | Adds a reference to [Uno.WinUI.Foldable](https://www.nuget.org/packages/Uno.WinUI.Foldable).                                                                                                                                               |
| `GLCanvas`           | Adds support for the [OpenGL Canvas](xref:Uno.Controls.GLCanvasElement).                                                                                                                                                                   |
| `GooglePlay`         | Adds support for [In App Reviews](xref:Uno.Features.StoreContext). For more information, see the [Store Context documentation](xref:Uno.Features.StoreContext).                                                                            |
| `Hosting`            | Adds support for [Dependency Injection](xref:Uno.Extensions.DependencyInjection.Overview) using [Uno.Extensions.Hosting packages](https://www.nuget.org/packages?q=Uno.Extensions.Hosting).                                                |
| `Http`               | Adds support for custom [Http Clients](xref:Uno.Extensions.Http.Overview) with [Uno.Extensions](xref:Uno.Extensions.Overview).                                                                                |
| `HttpRefit`          | Adds support for strongly-typed REST API clients via [Refit](xref:Uno.Extensions.Http.Overview#refit)                                                                           |
| `HttpKiota`          | Adds support for OpenAPI-generated clients via [Kiota](xref:Uno.Extensions.Http.Overview#kiota)                                                                           |
| `Localization`       | Adds support for [Localization](xref:Uno.Extensions.Localization.Overview) using [Uno.Extensions](xref:Uno.Extensions.Overview).                                                                                                           |
| `Logging`            | Adds support for [Logging](xref:Uno.Extensions.Logging.Overview) using [Uno.Extensions](xref:Uno.Extensions.Overview).                                                                                                                     |
| `LoggingSerilog`     | Adds support for [Serilog](https://github.com/serilog/serilog) using [Uno.Extensions](xref:Uno.Extensions.Overview).                                                                                                                       |
| `Lottie`             | Adds support for [Lottie animations](xref:Uno.Features.Lottie).                                                                                                                                                                            |
| `Material`           | Adds support for the [Material Design Theme](xref:Uno.Themes.Material.GetStarted) library. If the `Toolkit` feature is also used, it will add support for the [Material Design Toolkit](xref:Toolkit.GettingStarted.Material) library.     |
| `MauiEmbedding`      | Adds support for [embedding Maui controls in Uno Platform applications](xref:Uno.Extensions.Maui.Overview).                                                                                                                                |
| `MediaPlayerElement`       | Adds native references where needed to use [MediaPlayerElement](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mediaplayerelement).                                                                                                |
| `Mvvm`               | Adds support for the [CommunityToolkit.Mvvm](https://www.nuget.org/packages/CommunityToolkit.Mvvm) package.                                                                                                                                |
| `MVUX`               | Adds support for [MVUX](xref:Uno.Extensions.Mvux.Overview).                                                                                                                                                                                |
| `Navigation`         | Adds support for [Navigation](xref:Uno.Extensions.Navigation.Overview) using [Uno.Extensions](xref:Uno.Extensions.Overview).                                                                                                               |
| `Prism`              | Adds [Prism](https://github.com/PrismLibrary/Prism) support for Uno Platform applications WinUI.                                                                                                                                           |
| `Serialization`      | Adds support for [Serialization](xref:Uno.Extensions.Serialization.Overview) using [Uno.Extensions](xref:Uno.Extensions.Overview).                                                                                                         |
| `Skia`               | Adds support for [SkiaSharp](https://github.com/mono/SkiaSharp).                                                                                                                                                                           |
| `SkiaRenderer`       | Adds support for using Skia as the graphics rendering engine. For more details, see [Skia Rendering documentation](xref:uno.features.renderer.skia).                                                                                               |
| `Storage`            | Adds support for [Storage](xref:Uno.Extensions.Storage.Overview) using [Uno.Extensions](xref:Uno.Extensions.Overview).                                                                                                                     |
| `Svg`                | [SVG](xref:Uno.Features.SVG) support for iOS, and Android. This option is not needed when only targeting WebAssembly and WinAppSDK.                                                                                          |
| `ThemeService`       | Adds the [Uno.Extensions.Core.WinUI package](https://www.nuget.org/packages/Uno.Extensions.Core.WinUI).                                                                                                                                    |
| `Toolkit`            | Adds support for the [Uno.Toolkit](xref:Toolkit.GettingStarted).                                                                                                                                                                           |
| `WebView`            | Adds support for the [WebView2 control](xref:Uno.Controls.WebView2).

## 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**](#tab/uno-packages)

| Property                         | NuGet Package(s)                                                                                                 | Description                                                                                                                         |
|----------------------------------|------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
| `UnoCoreLoggingSingletonVersion` | [Uno.Core.Extensions.Logging.Singleton](https://www.nuget.org/packages/Uno.Core.Extensions.Logging.Singleton)    | Provides a logging singleton pattern with helpers and extension methods for simplified logging.                                     |
| `UnoCSharpMarkupVersion`         | [Uno.WinUI.Markup](https://www.nuget.org/packages/Uno.WinUI.Markup) and similar packages                         | Enables [C# Markup](xref:Uno.Extensions.Markup.Overview), the use of C# for building UI markup, similar to XAML but with C# syntax. |
| `UnoDspTasksVersion`             | [Uno.Dsp.Tasks](https://www.nuget.org/packages/Uno.Dsp.Tasks) and similar packages                               | Includes tasks for Uno DSP (Theme colors import) within Uno Platform projects.                                                      |
| `UnoExtensionsVersion`           | [Uno.Extensions.Storage.WinUI](https://www.nuget.org/packages/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](https://www.nuget.org/packages/Uno.Extensions.Logging.OSLog) and similar packages | Implements logging mechanisms to help with monitoring and debugging Uno Platform applications.                                      |
| `UnoResizetizerVersion`          | [Uno.Resizetizer](https://www.nuget.org/packages/Uno.Resizetizer)                                                | Provides tools for automatically resizing and managing image assets in Uno Platform projects.                                       |
| `UnoThemesVersion`               | [Uno.Material.WinUI](https://www.nuget.org/packages/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](https://www.nuget.org/packages/Uno.Toolkit.WinUI) and similar packages                       | Offers a collection of controls, helpers, and tools to complement the standard WinUI components.                                    |
| `UnoUniversalImageLoaderVersion` | [Uno.UniversalImageLoader](https://www.nuget.org/packages/Uno.UniversalImageLoader)                              | Facilitates the loading and displaying of images across different platforms supported by Uno.                                       |
| `UnoWasmBootstrapVersion`        | [Uno.Wasm.Bootstrap](https://www.nuget.org/packages/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.

## [**Third Party Packages**](#tab/3rd-party-packages)

| Property                            | NuGet Package(s)                                                                                                     | Description                                                                                                    |
|-------------------------------------|----------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| `AndroidMaterialVersion`            | [Xamarin.Google.Android.Material](https://www.nuget.org/packages/Xamarin.Google.Android.Material)                    | Implements Material Design components for Android using Xamarin bindings.                                      |
| `AndroidXActivityVersion`           | [Xamarin.AndroidX.Activity](https://www.nuget.org/packages/Xamarin.AndroidX.Activity)                                | Provides classes to build Android activities with AndroidX libraries.                                          |
| `AndroidXAppCompatVersion`          | [Xamarin.AndroidX.AppCompat](https://www.nuget.org/packages/Xamarin.AndroidX.AppCompat)                              | Offers backward-compatible versions of Android components with AndroidX.                                       |
| `AndroidXBrowserVersion`            | [Xamarin.AndroidX.Browser](https://www.nuget.org/packages/Xamarin.AndroidX.Browser)                                  | Contains components to implement browser features with AndroidX.                                               |
| `AndroidXCollectionVersion`         | [Xamarin.AndroidX.Collection](https://www.nuget.org/packages/Xamarin.AndroidX.Collection) and similar packages       | Provides AndroidX extensions for collections like sparse arrays and bundles.                                   |
| `AndroidXLegacySupportV4Version`    | [Xamarin.AndroidX.Legacy.Support.V4](https://www.nuget.org/packages/Xamarin.AndroidX.Legacy.Support.V4)              | Supports older Android versions with AndroidX compatibility libraries.                                         |
| `AndroidXSplashScreenVersion`    | [Xamarin.AndroidX.Core.SplashScreen](https://www.nuget.org/packages/Xamarin.AndroidX.Core.SplashScreen)              | Support for Android splash screen customization.                                         |
| `AndroidXNavigationVersion`         | [Xamarin.AndroidX.Navigation.UI](https://www.nuget.org/packages/Xamarin.AndroidX.Navigation.UI) and similar packages | Facilitates navigation within an Android app using AndroidX.                                                   |
| `AndroidXRecyclerViewVersion`       | [Xamarin.AndroidX.RecyclerView](https://www.nuget.org/packages/Xamarin.AndroidX.RecyclerView)                        | Implements a flexible view for providing a limited window into large datasets with AndroidX.                   |
| `AndroidXSwipeRefreshLayoutVersion` | [Xamarin.AndroidX.SwipeRefreshLayout](https://www.nuget.org/packages/Xamarin.AndroidX.SwipeRefreshLayout)            | Provides a swipe-to-refresh UI pattern with AndroidX.                                                          |
| `CommunityToolkitMvvmVersion`       | [CommunityToolkit.Mvvm](https://www.nuget.org/packages/CommunityToolkit.Mvvm)                                        | Delivers a set of MVVM (Model-View-ViewModel) components for .NET applications.                                |
| `MicrosoftIdentityClientVersion`    | [Microsoft.Identity.Client](https://www.nuget.org/packages/Microsoft.Identity.Client)                                | Provides an authentication library for Microsoft Identity Platform.                                            |
| `MicrosoftLoggingVersion`           | [Microsoft.Extensions.Logging.Console](https://www.nuget.org/packages/Microsoft.Extensions.Logging.Console)          | Enables logging to the console with Microsoft's extensions.                                                    |
| `PrismVersion`                      | [Prism.Uno.WinUI](https://www.nuget.org/packages/Prism.Uno.WinUI) and similar packages                               | Integrates the Prism library, which aids in building loosely coupled, maintainable, and testable applications. |
| `SkiaSharpVersion`                  | [SkiaSharp.Skottie](https://www.nuget.org/packages/SkiaSharp.Skottie) and similar packages                           | Provides a cross-platform 2D graphics API for .NET platforms based on Google's Skia Graphics Library.          |
| `SvgSkiaVersion`                    | [Svg.Skia](https://www.nuget.org/packages/Svg.Skia)                                                                  | Renders SVG files using the SkiaSharp graphics engine.                                                         |
| `WinAppSdkBuildToolsVersion`        | [Microsoft.Windows.SDK.BuildTools](https://www.nuget.org/packages/Microsoft.Windows.SDK.BuildTools)                  | Contains the tools required to build applications for the Microsoft Windows App SDK.                           |
| `WinAppSdkVersion`                  | [Microsoft.WindowsAppSDK](https://www.nuget.org/packages/Microsoft.WindowsAppSDK)                                    | Provides project templates and tools for building Windows applications.                                        |
| `WindowsCompatibilityVersion`       | [Microsoft.Windows.Compatibility](https://www.nuget.org/packages/Microsoft.Windows.Compatibility)                    | Enables Windows desktop apps to use .NET Core by providing access to additional Windows APIs.                  |

---

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

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

      ...

      <UnoFeatures>
        Material;
        Dsp;
        Hosting;
        Toolkit;
        Logging;
        MVUX;
        Configuration;
        Http;
        Serialization;
        Localization;
        Navigation;
        ThemeService;
        Mvvm;
        SkiaRenderer;
      </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.

## Disabling Implicit Uno Packages

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

```xml
<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 |
| tvOS  | 14.2 |
| 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`.

```xml
 <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)')) == 'tvOS'">
      <PropertyGroup>
        <SupportedOSPlatformVersion>14.2</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 First-TargetFramework Workarounds

Using a Single Project in Visual Studio 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:

```xml
<PropertyGroup>
  <UnoDisableVSTargetFrameworksRewrite>true</UnoDisableVSTargetFrameworksRewrite>
</PropertyGroup>
```

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

- `net8.0-browserwasm` must be first for WebAssembly debugging to work ([Link](https://developercommunity.visualstudio.com/t/net80-must-be-first-for-WebAssembly-pub/10643720))
- [WinAppSDK Unpackaged profile cannot be selected properly when a net8.0 mobile target is active](https://developercommunity.visualstudio.com/t/WinAppSDK-Unpackaged-profile-cannot-be-s/10643735)

## 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:

```xml
<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](https://github.com/microsoft/microsoft-ui-xaml/issues/8857) 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:

```xml
<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:

- `*.wasm.cs` (WebAssembly)
- `*.desktop.cs` (Desktop)
- `*.iOS.cs` (iOS)
- `*.tvOS.cs`(tvOS)
- `*.UIKit.cs`, `*.Apple.cs` (iOS & tvOS)
- `*.Android.cs` (Android)
- `*.WinAppSDK.cs` (Windows App SDK)

For class libraries we also provide:

- `*.reference.cs` (Reference only)
- `*.crossruntime.cs` (WebAssembly, Desktop, or Reference)

> [!NOTE]
> For backwards compatibility, using `.skia.cs` is currently equivalent to `.desktop.cs`. This might change in the future, so we recommend using the suffixes above instead.

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:
>
> ```xml
> <Target Name="AdjustAppItemGroups" BeforeTargets="ResolveAssemblyReferences">
>     <ItemGroup Condition="'$(TargetFramework)' == 'net9.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.

## Apple Privacy Manifest Support

Starting May 1st, 2024, Apple requires the inclusion of a new file, the [Privacy Manifest file](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files) (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](https://aka.platform.uno/apple-privacy-manifest-sample) repository.

For more information on how to include privacy entries in this file, see the [Microsoft .NET documentation](https://learn.microsoft.com/dotnet/maui/ios/privacy-manifest) on the subject, as well as [Apple's documentation](https://developer.apple.com/documentation/bundleresources/privacy_manifest_files).

> [!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:
>
> ```xml
>  <ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">
>    <BundleResource Include="iOS\PrivacyInfo.xcprivacy" LogicalName="PrivacyInfo.xcprivacy" />
>  </ItemGroup>
> ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.check/refs/heads/main/doc/using-uno-check.md

---
uid: UnoCheck.UsingUnoCheck
---

# Setup your environment with uno-check

[`uno-check`](https://github.com/unoplatform/uno.check) is a dotnet command-line tool that runs a suite of automated check-ups on your dev environment, making sure you have all the prerequisites installed to successfully develop an Uno Platform application. The tool is available on Windows, Linux, and macOS.

If it finds something missing, out of date, or misconfigured, it will either offer to automatically fix it, or else direct you to instructions to manually fix the problem.

![uno-check running](https://github.com/unoplatform/uno/raw/master/doc/articles/Assets/uno-check-running.gif)

## Install and run uno-check

# [**Windows**](#tab/windows)

1. Make sure you have the [.NET SDK installed](https://dotnet.microsoft.com/download).
1. Open a command-line prompt, Windows Terminal if you have it installed, or else Command Prompt or Windows Powershell from the Start menu.
1. Setup uno.check by:
    - Installing the tool:

        ```dotnetcli
        dotnet tool install -g uno.check
        ```

    - Updating the tool, if you previously installed it:

        ```dotnetcli
        dotnet tool update -g uno.check
        ```

1. Run the tool from the command prompt with the following command:

    ```bash
    uno-check
    ```

1. Follow the instructions indicated by the tool.
1. If you get any errors or warnings, run the provided fix or follow the provided instructions. Run `uno-check` again to verify that the fixes worked.
1. Once `uno-check` gives you the green light, you can [get started](https://platform.uno/docs/articles/get-started.html)!

# [**Linux**](#tab/linux)

1. Open a Terminal
1. If `dotnet --version` returns `command not found`:
    - Follow the [official directions](https://learn.microsoft.com/dotnet/core/install/linux?WT.mc_id=dotnet-35129-website#packages) for installing .NET.
      > [!IMPORTANT]
      > If your distribution is Ubuntu and you want to develop for Android, make sure to use the directions to install the Microsoft feed and not the Ubuntu official feed. The latter does not contain Android workloads.
1. Then, setup uno.check by:
    - Installing the tool:

        ```dotnetcli
        dotnet tool install -g uno.check
        ```

    - Updating the tool, if you previously installed it:

        ```dotnetcli
        dotnet tool update -g uno.check
        ```

1. Run the tool from the command prompt with the following command:

    ```bash
    uno-check
    ```

    If the above command fails, use the following:

    ```bash
    ~/.dotnet/tools/uno-check
    ```

1. Follow the instructions indicated by the tool
1. If you get any errors or warnings, run the provided fix or follow the provided instructions. Run `uno-check` again to verify that the fixes worked.
1. Once `uno-check` gives you the green light, you can [get started](https://platform.uno/docs/articles/get-started.html)!

# [**macOS**](#tab/macos)

1. Make sure you have the [.NET SDK installed](https://dotnet.microsoft.com/download).
1. Open a Terminal.
1. Setup uno.check by:
    - Installing the tool:

        ```dotnetcli
        dotnet tool install -g uno.check
        ```

    - Updating the tool, if you previously installed it:

        ```dotnetcli
        dotnet tool update -g uno.check
        ```

1. Run the tool from the command prompt with the following command:

    ```bash
    uno-check
    ```

    If the above command fails, use the following:

    ```bash
    ~/.dotnet/tools/uno-check
    ```

1. Follow the instructions indicated by the tool
1. If you get any errors or warnings, run the provided fix or follow the provided instructions. Run `uno-check` again to verify that the fixes worked.
1. Once `uno-check` gives you the green light, you can [get started](https://platform.uno/docs/articles/get-started.html)!

***

## Common uno-check command lines

### Run uno-check in verbose mode

```bash
uno-check -v
```

This command shows additional logs for each running check.

### Run uno-check for a specific platforms

```bash
uno-check --target desktop --target web # or ios, android, windows
```

This command avoids installing tooling that is not needed.

See [Command line arguments](xref:UnoCheck.Configuration#command-line-arguments) for more details

### Run uno-check in readonly mode on Windows

```bash
cmd /c "set __COMPAT_LAYER=RUNASINVOKER && uno-check --ci --non-interactive"
```

This command only checks for missing tooling and report the results.

### Run uno-check in readonly mode on macOS or Linux

```bash
uno-check -v --ci --non-interactive
```

This command only checks for missing tooling and report the results.

### Run uno-check to list available checks

```bash
uno-check list
```

This command lists checks that can be skipped using `--skip`

### Run uno-check with specific checks skipped

```bash
uno-check --skip androidsdk
```

This command skips specified checks and runs the rest.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.resizetizer/refs/heads/main/doc/using-uno-resizetizer.md

---
uid: Uno.Resizetizer.GettingStarted
---

# How-To: Get Started with Uno.Resizetizer

Uno.Resizetizer is a set of MSBuild tasks designed to manage an application's assets. With this package, there's no need to worry about creating and maintaining various image sizes or setting up a splash screen. Simply, provide an SVG file, and the tool will handle everything else.

> [!TIP]
> To create an app, make sure to visit [our getting started tutorials](xref:Uno.GetStarted).

## How it works

Resizetizer uses an `svg` or `png` file as input. If an `svg` file is used, it will be re-scaled for different resolutions. The `UnoImage`, on iOS, for example, will use the x2 and x3 corresponding sizes and add them to your project for you. If a `png` file is used, it will not be resized, but it will be added to your project and used as one size image. If you want to know all the scales that are used, you can check this [Table of scales](https://platform.uno/docs/articles/features/working-with-assets.html#table-of-scales).

For `UnoIcon` and `UnoSplashScreen`, the generated sizes will be the same as the ones used by the platform.

As `svg` has the ability to scale without losing quality, we strongly encourage the usage of `svg` files, to take most of the benefits of the tool. In the rest of the docs, you can assume that we are using `svg` files.

> [!TIP]
> You can use the `Resize` property on `UnoImage` to force the resize of a `png` file. But be aware that the quality can be affected.

## Manual Installation

Uno.Resizeter is delivered [through NuGet](https://www.nuget.org/packages/Uno.Resizetizer). In order to install it, you can either install it in your project using your IDE (this will be shown in the next steps) or added directly on your `.csproj` as shown in the [NuGet page](https://www.nuget.org/packages/Uno.Resizetizer/).

> [!NOTE]
> If you're using the new template, you can skip this step because it is already included by default with Uno Platform 4.8 and later.
  
### 1. Installing Uno.Resizetizer

* Open your favorite IDE, in this case, it will be Visual Studio, after that open the Manage NuGet packages window.
* Search for `Uno.Resizetizer` and install it over your projects.

> [!NOTE]
> Uno.Resizetizer is compatible with projects running .NET 6 and later.

## Usage

Uno.Resizetizer can handle:

* Images used in the application
* The App icon
* The splash screen

The next sections will show how to use it for each use case.

> [!WARNING]
> All the assets used by Uno.Resizetizer should be lower case and don't have special characters. You can use `_` to separate words.
> This is because the assets are used on different platforms and some of them have limitations on the characters that can be used.

### UnoImage

`UnoImage` is the build action used for images that will be part of the app.

### 2. Configure the project to use generated Images

* In the App Class library, create a folder called `Assets` (if doesn't exist) and then create a folder called `Images`. We now need to add assets to this folder.

> [!TIP]
> Those folder names are examples. It is possible to create folders with any name and how many levels are needed.

Make sure that the build assets are configured to be `UnoImage`. In the `csproj`, to make all files inside the `Assets\Images` folder to be automatically configured to be `UnoImage`, add the following:

```xml
<ItemGroup>
    <UnoImage Include="Assets\Images\*" />
</ItemGroup>
```

You can also make specific files to be `UnoImage` using Visual Studio, by right-clicking on the file, selecting `Properties`, then `Build Action`, and selecting `UnoImage`. The image below shows what it looks like:

![UnoImage Build Action](Assets/UnoImage_BuildAction.png)

### 3. Using the assets on the project

* `UnoImage` assets can now be used just like any regular image. For example:

```xml
<Image Width="300"
       Height="300"
       Source="Assets/Images/my_image.png" />
```

> [!TIP]
> Make sure to add the `.png` at the end of the file name

## UnoIcon

`UnoIcon` is the build action for the app icon. There should only be one per application. The `UnoIcon` accepts two assets, one that represents the `Foreground` and another that represents the `Background`. During the generation phase, those files will be merged into one `.png` image.

During the creation of your `svg` file, please remember to make the `ViewBox` bigger than the `Foreground` and `Background` images, not adding an extra space could cause the app icon to not look good on some platforms. We recommend to add a 30% extra space on each side. This will be enough for Resizetizer to work with padding and margins.

### 4. Configuring the project to use generated app icon

# [**Single Project Based Solution**](#tab/singleproject)

* When you create a new Uno Platform application, an `Icons` folder is automatically generated under the `Assets` directory. This folder contains `icon.svg` and `icon_foreground.svg` files.
* You can simply replace these files with your custom icons while retaining the file names, or you can customize the icon configuration using SDK properties if different names or additional configurations are needed.
* This configuration automatically applies across all target platforms included in the single project structure.

## Utilizing SDK Properties

The Uno Platform SDK exposes several properties that simplify the customization of your app icon. These properties allow you to easily adjust key aspects like the base size, color, and icon files without detailed XML changes, making your development process more streamlined.

* `UnoIconBackgroundFile`: Sets the background image file for the icon.
* `UnoIconForegroundFile`: Sets the foreground image file for the icon.
* `UnoIconForegroundScale`: Adjusts the scaling of the icon's foreground.
* `UnoIconBackgroundColor`: Sets the background color of the icon.

For basic adjustments, such as changing the icon's foreground color or applying a common modification across platforms, you can use SDK properties:

```xml
<PropertyGroup>
    <UnoIconForegroundFile>Assets\Icons\customicon.svg</UnoIconForegroundFile>
    <UnoIconColor>#FF0000</UnoIconColor>
</PropertyGroup>
```
This setup ensures that the icon settings are centralized, simplifying the maintenance and updating process.

# [**Class Library Based Solution**](#tab/classlib)

* Create an `Icons` folder inside the Base project, and add the files related to the app icon there.
* Now open the `base.props` file, inside the `MyApp.Base` folder project and add the following block:

```xml
<ItemGroup>
    <UnoIcon Include="$(MSBuildThisFileDirectory)Icons\iconapp.svg"
             ForegroundFile="$(MSBuildThisFileDirectory)Icons\appconfig.svg"
             Color="#FF0000"/>
</ItemGroup>
```

We recommend adding the `UnoIcon` on `base.props` because this file is imported by all head projects, that way, you don't need to add the same configuration in each head project.

If you want, you can see our sample project in [Uno.Resizetizer GitHub repository](https://github.com/unoplatform/uno.resizetizer/blob/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate/Resizetizer.Extensions.Sample.Base/base.props#L13-L16) where this step is configured.

> [!TIP]
> If the icon doesn't look good, you can use the `ForegroundScale` property which will re-scale the `Foreground` image for all platforms. If you want to re-scale for a specific platform, you can use the specific property for that platform. For more information, see [Resizetizer Properties](xref:Overview.Uno.Resizetizer.Properties).

# [**Shared Project Based Solution**](#tab/sharedproject)

* Create an `Icons` folder inside the Shared project, and add the files related to the app icon there.
* In each of your project heads (iOS, Android, WebAssembly, ...), add the following block to the `csproj` file:

```xml
<ItemGroup>
    <UnoIcon Include="..\MyApp.Shared\Icons\iconapp.svg"
             ForegroundFile="..\MyApp.Shared\Icons\appconfig.svg"
             Color="#FF0000"/>
</ItemGroup>
```

You can also make specific files to be `UnoIcon` using Visual Studio, by right-clicking on the file, selecting `Properties`, then `Build Action`, and selecting `UnoIcon`. The image below shows what it looks like:

![UnoIcon Build Action](Assets/UnoIcon_BuildAction.png)

-----

Next, some adjustments are needed on `Android`, `Windows (WinUI)`, `WebAssembly`, `mac-catalyst`, and `iOS`.

# [**Android**](#tab/Android)

* Open the [`Main.Android.cs` file](https://github.com/unoplatform/uno.resizetizer/blob/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate/Resizetizer.Extensions.Sample.Mobile/Android/Main.Android.cs) (or the file that has the `Android.App.ApplicationAttribute`), and change the `Icon` property, in that attribute, to be the name of the file used in the `Include` property of `UnoIcon`, in our case will be:

  ```csharp
  [global::Android.App.ApplicationAttribute(
      Label = "@string/ApplicationName",
      Icon = "@mipmap/iconapp",
      //...
  )]
  ```

> [!TIP]
> You can remove the old assets related to the app icon from the `Android` project.

# [**Windows (WinUI)**](#tab/Windows)

> [!NOTE]
> Uno.Resizetizer is currently only supported on WinUI, UWP is not supported."

* Open the [`Package.appxmanifest` file](https://github.com/unoplatform/uno.resizetizer/blob/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate/Resizetizer.Extensions.Sample.Windows/Package.appxmanifest) and look for the `Application` tag
* Remove everything that's related to the application icon (BackgroundColor, Square and Wide property inside the `uap:DefaultTile` attribute). It should look like this:

    ```xml
    <Applications>
       <Application Id="App"
         Executable="$targetnametoken$.exe"
         EntryPoint="$targetentrypoint$">
         <uap:VisualElements
           DisplayName="Resizetizer.Extensions.Sample"
           Description="Resizetizer.Extensions.Sample">
           <uap:SplashScreen Image="Resizetizer.Extensions.Sample/Assets/SplashScreen.png" />
           <uap:DefaultTile/>
         </uap:VisualElements>
       </Application>
     </Applications>
    ```
* In a multi-window environment, you need to call 'SetWindowIcon' for each new window created to show the app icon on the app bar:
    ```c#
    using System;
    using Uno.Resizetizer;

    newwindow = new Window();
    newwindow.SetWindowIcon();
    newwindow.Activate();
    ```

# [**Web Assembly (Wasm)**](#tab/Wasm)

> [!NOTE]
> You will only need to configure this platform if you want to deploy it as a PWA.

* Open the [`manifest.webmanifest` file](https://github.com/unoplatform/uno.resizetizer/blob/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate/Resizetizer.Extensions.Sample.Wasm/manifest.webmanifest) and look for the `icons` tag and remove all the values inside it. You should be seeing an empty array like this:

    ```json
    {
      "background_color": "#ffffff",
      "description": "UnoResApp1",
      "display": "standalone",
      "icons": [ ],
    }
    ```

> [!NOTE]
> In some projects, the file is named `manifest.json` instead of `manifest.webmanifest`. If so, you can either adjust your project to use `manifest.webmanifest` or keep it as `manifest.json`.
>
> [!NOTE]
> Uno.Resizetizer will support comments on your json file, but they will be ignored on the final generated file.

# [**iOS**](#tab/iOS)

* For `mac-catalyst` and `iOS`, open the [`info.plist` file](https://github.com/unoplatform/uno.resizetizer/blob/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate/Resizetizer.Extensions.Sample.Mobile/iOS/Info.plist), find the `XSAppIconAsset` key, and change its value to `Assets.xcassets/iconapp.appiconset`.

> [!NOTE]
> If your app icon has a another name than `iconapp`, use it instead.
>
> [!TIP]
> You can delete the old assets related to the app icon from the project.

-----

## UnoSplashScreen

`UnoSplashScreen` is the build action for the splash screen. There should only be one per application. The `UnoSplashScreen` has two more properties that you can use to adjust your asset, which are:

* `BaseSize`: It's the size that will be used to perform the scaling of the image. The default value is the size of the asset. So, if you feel that your SplashScreen doesn't look right, you can tweak this value.

* `Color`: It's the background color that will be used to fill the empty space on the final SplashScreen asset. The default value is `#FFFFFF` (white).

### 5. Configuring the project to use generated splash screen
# [**Single Project Based Solution**](#tab/singleproject)
* When you create a new Uno Platform application, a `Splash` folder is automatically generated under the `Assets` directory. This folder contains `splash_screen.svg` file.
* You can simply replace these files with your custom splash screen while retaining the file names, or you can customize the splash screen configuration using SDK properties if different names or additional configurations are needed.
* This configuration automatically applies across all target platforms included in the single project structure.

## Utilizing SDK Properties

The Uno Platform SDK exposes several properties that simplify the customization of your splash screen. These properties allow you to easily adjust key aspects like the base size, color, and icon files without detailed XML changes, making your development process more streamlined.

* `UnoSplashScreenFile`: Specifies the image file for the splash screen.
* `UnoSplashScreenBaseSize`: Sets the base size for the splash screen image.
* `UnoSplashScreenColor`: Determines the background color of the splash screen.

To facilitate easier customization, such as adjusting the base size or color of the splash screen, you can leverage SDK properties:
```xml
<PropertyGroup>
    <UnoSplashScreenFile>Assets\SplashScreen\custom_splash_screen.svg</UnoSplashScreenFile>
    <UnoSplashScreenBaseSize>128,128</UnoSplashScreenBaseSize>
    <UnoSplashScreenColor>#512BD4</UnoSplashScreenColor>
</PropertyGroup>
```

This setup ensures that the splash screen settings are centralized, simplifying the maintenance and updating process.

# [**Class Library Based Solution**](#tab/classlib)

* Create a `SplashScreen` folder inside the Base project, and add the file related to the splash screen there.
* Now, open the `base.props` file inside the `MyApp.Base` folder project and add the following block:

    ```xml
    <UnoSplashScreen
             Include="$(MSBuildThisFileDirectory)SplashScreen\splash_screen.svg"
             BaseSize="128,128"
             Color="#512BD4" />
    ```

We recommend adding the `UnoSplashScreen` on `base.props` because this file is imported by all head projects, that way, you don't need to add the same configuration on each head project.

If you want, you can see our sample project in [Uno.Resizetizer GitHub repository](https://github.com/unoplatform/uno.resizetizer/blob/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate/Resizetizer.Extensions.Sample.Base/base.props#L17-L21).

# [**Shared Project Based Solution**](#tab/sharedproject)

* Create a `SplashScreen` folder inside the Shared project, and add the file related to the splash screen there.
* In each of your project heads (iOS, Android, WebAssembly, ...), add the following block to the `csproj` file:

    ```xml
    <UnoSplashScreen
             Include="..\MyApp.Shared\SplashScreen\splash_screen.svg"
             BaseSize="128,128"
             Color="#512BD4" />
    ```

You can also make specific files to be `UnoSplashScreen` using Visual Studio, by right-clicking on the file, selecting `Properties`, then `Build Action`, and selecting `UnoSplashScreen`. The image below shows what it looks like:

![UnoSplashScreen Build Action](Assets/UnoSplashScreen_BuildAction.png)

***

Next, some adjustments are needed on `Android`, `Windows`, and `iOS`.

# [**Android**](#tab/Android)

* Open the [`style.xml` file](https://github.com/unoplatform/uno.resizetizer/blob/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate/Resizetizer.Extensions.Sample.Mobile/Android/Resources/values/Styles.xml), look for the `Theme` that is been used by the application and add the following line:

    ```xml
    <style name="AppTheme" parent="Theme.AppCompat.Light">
    
        <!-- Other properties -->
    
        <!-- This property is used for the splash screen -->
        <item name="android:windowSplashScreenBackground">@color/uno_splash_color</item>
        <item name="android:windowBackground">@drawable/uno_splash_image</item>
        <item name="android:windowSplashScreenAnimatedIcon">@drawable/uno_splash_image</item>
    
        <!-- Image at the footer -->
        <!-- This is not required in order to make the Splash screen work -->
        <!-- For more info please see: https://developer.android.com/develop/ui/views/launch/splash-screen#set-theme -->
        <item name="android:windowSplashScreenBrandingImage">@drawable/uno_splash_image</item>
    </style>
    ```

> [!NOTE]
> The `uno_splash_image` and `uno_splash_color` are generated by the build process.

# [**Windows (WinUI)**](#tab/Windows)

* Open the [`Package.appxmanifest` file](https://github.com/unoplatform/uno.resizetizer/blob/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate/Resizetizer.Extensions.Sample.Windows/Package.appxmanifest) and look for the `Application` node, inside it, look for the `uap:SplashScreen` node. Delete the `Image` property and its value, the `Application` tag should be like this:

    ```xml
    <Applications>
       <Application Id="App"
         Executable="$targetnametoken$.exe"
         EntryPoint="$targetentrypoint$">
         <uap:VisualElements
           DisplayName="Resizetizer.Extensions.Sample"
           Description="Resizetizer.Extensions.Sample">
           <uap:SplashScreen />
           <uap:DefaultTile />
         </uap:VisualElements>
       </Application>
     </Applications>
    ```

# [**Web Assembly (Wasm)**](#tab/Wasm)

* No additional adjustments are needed on Wasm.

# [**iOS**](#tab/iOS)

* Open the [`info.plist` file](https://github.com/unoplatform/uno.resizetizer/blob/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate/Resizetizer.Extensions.Sample.Mobile/iOS/Info.plist) and look for the `UILaunchStoryboardName` key, delete it and its value.

> [!TIP]
> Feel free to delete the `LaunchScreen.storyboard` file.

> [!NOTE]
> Feel free to delete old assets related to the splash screen.

-----

## Platform-Specific Customization
The Uno Resizetizer SDK allows for detailed control over how assets are rendered on different platforms. This can be particularly useful for properties such as icon and splash screen backgrounds, which may need to vary between platforms due to design or visibility concerns.

### Customizing Background Colors Per Platform

For properties like BackgroundColor, which might need different values per platform (for example, transparent backgrounds on Windows and WASM but a solid color on iOS and Android), you can specify platform-specific properties in your project file:

```xml
<PropertyGroup>
    <!-- Default background color -->
    <UnoIconBackgroundColor>#FFFFFF</UnoIconBackgroundColor>

    <!-- Platform-specific overrides using Uno SDK properties -->
    <UnoIconBackgroundColor Condition="'$(IsAndroid)' == 'true'">#000000</UnoIconBackgroundColor>
    <UnoIconBackgroundColor Condition="'$(IsIOS)' == 'true'">#FF0000</UnoIconBackgroundColor>
    <UnoIconBackgroundColor Condition="'$(IsWinAppSdk)' == 'true'">Transparent</UnoIconBackgroundColor>
    <UnoIconBackgroundColor Condition="'$(IsBrowserWasm)' == 'true'">Transparent</UnoIconBackgroundColor>
</PropertyGroup>
```
This setup demonstrates setting a default background color that is overridden on specific platforms. Adjust the conditions to match your project's target frameworks as defined in your project files or SDK documentation.

#### Applying Platform-Specific Scale
Similarly, if you want to apply different scaling factors for the icon foreground across platforms, use the platform-specific properties:

```xml
<PropertyGroup>
    <!-- Default scale -->
    <UnoIconForegroundScale>0.5</UnoIconForegroundScale>

    <!-- Platform-specific scales using Uno SDK properties -->
    <UnoIconForegroundScale Condition="'$(IsAndroid)' == 'true'">0.6</UnoIconForegroundScale>
    <UnoIconForegroundScale Condition="'$(IsBrowserWasm)' == 'true'">0.4</UnoIconForegroundScale>
    <UnoIconForegroundScale Condition="'$(IsWinAppSdk)' == 'true'">0.3</UnoIconForegroundScale>
    <UnoIconForegroundScale Condition="'$(IsIOS)' == 'true'">0.55</UnoIconForegroundScale>
</PropertyGroup>

```
## Using SVG Images vs PNG Images with SVG underneath
The Uno Platform allows for flexible image handling through direct SVG use or through asset generation via Uno.Resizetizer. Understanding when to use each approach can optimize your app's performance and visual quality.

### Direct SVG Usage

#### When to Use:

* You require vector graphics to be scalable without loss of quality.
* Your app needs to dynamically change aspects of the image, such as color or size, at runtime.
#### How to Implement:

* Add a folder named `Svg` in `Assets` and add your SVG file.
* Set the build action of your SVG file to `Content`.
* Reference the SVG file directly in the Image control's Source property.
```xml
<Image Source="Assets/Svg/my_vector_image.svg" />
```
[Using Svg Images](https://platform.uno/docs/articles/features/svg.html?tabs=singleproject)

### Using Uno.Resizetizer for SVG to PNG Conversion

#### When to Use:

* You need raster graphics to optimize performance on platforms where SVG rendering might be less efficient.
* Your app targets multiple platforms and requires consistent image rendering across all.

#### How to Implement:

* Set the build action of your SVG file to UnoImage.
* Uno.Resizetizer will generate PNG assets at various scales.
* Reference the generated PNG in the Image control's Source property.
```xml
<Image Source="Assets/Images/my_vector_image.png" />
```
[Using Uno Resizetizer ](https://platform.uno/docs/articles/external/uno.resizetizer/doc/using-uno-resizetizer.html?tabs=classlib%2CAndroid#unoimage)

Choosing between direct SVG usage and PNG conversion with Uno.Resizetizer depends on your specific application needs. Consider factors such as platform target, performance requirements, and how you plan to manipulate the images within your app.
## Sample App Example

A sample app is available [here](https://github.com/unoplatform/uno.resizetizer/tree/7ad1199ea1a256e171d88e694486e9a8c341c8a2/samples/NewTemplate) as an example for all the previous steps detailed above.

## Troubleshooting

### Windows (WinUI)

In some cases, the OS caches the app icon and your changes might not be applied. To fix this issue, first uninstall your app and then use one of the following options:

1. In the run dialog (Win + R) execute `ie4uinit.exe -ClearIconCache`
2. Restart `explorer.exe` process (in **Task Manager - Details** select `explorer.exe` in the list and click on **Restart task**).
3. Reboot your PC

Afterward, try to deploy the app again and your icons should be updated correctly.

### Icon Assets

The Icon Extension generation will not succeed if the project cannot find `/Assets/Icons/icon.svg` and `/Assets/Icons/icon_foreground.svg`. You can find the related GitHub issue [here](https://github.com/unoplatform/uno.resizetizer/issues/289).

Without these icon assets, a reference error will occur: _CS0234: The type or namespace name 'Resizetizer' does not exist in the namespace 'Uno' (are you missing an assembly reference?)_.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/using-uno-ui.md

---
uid: Uno.Development.Overview
---

# Developing with Uno Platform

Write applications once in XAML and/or C# and deploy them to [any target platform](getting-started/requirements.md).

## About Uno

* [What is Uno Platform?](xref:Uno.Documentation.Intro)
* [How does Uno Platform work?](xref:Uno.Development.HowItWorks)
* [Supported target platforms](xref:Uno.GettingStarted.Requirements)
* [Supported .NET versions by platform](xref:Uno.Development.NetVersionSupport)

## Mastering the basics

The WinUI application API which Uno Platform uses is extensively documented by Microsoft. We've [selected some articles from Microsoft](winui-doc-links.md) which will jump-start your Uno Platform development.

Here are some articles which cover the basics of cross-platform Uno development:

* [The structure of an Uno Platform codebase](uno-app-solution-structure.md)
* Platform-specific code: [C#](platform-specific-csharp.md) and [XAML](platform-specific-xaml.md)
* [Best practices for developing Uno Platform applications](best-practices-uno.md)

## WinUI features

These articles cover general WinUI features in Uno Platform, discussing what's supported and which platform-specific constraints exist.

* [Accessibility](features/working-with-accessibility.md)
* [Assets in shared code](features/working-with-assets.md)
* [Custom fonts](features/custom-fonts.md)
* [Shapes & Brushes](features/shapes-and-brushes.md)
* [Handling user input](features/pointers-keyboard-and-other-user-inputs.md)
* [Using Fluent styles in legacy apps](features/using-winui2.md)

## WinUI controls

Uno Platform provides support for a large number of WinUI controls, panels, and visual primitives - see [a complete list](implemented-views.md) in the Reference documentation. The 'WinUI controls' section in the Table of Contents on the left covers platform-specific constraints and extensions for selected controls.

## WinRT features (non-visual APIs)

Uno Platform supports a number of non-visual APIs from Windows Runtime namespaces on non-Windows platforms, like [clipboard management](features/windows-applicationmodel-datatransfer.md) and [sensor access](features/windows-devices-sensors.md).

[!include[Inline table of contents](includes/winrt-features-inline-toc.md)]

## Features unique to Uno

* [VisibleBoundsPadding - manage 'safe' area on notched devices](features/VisibleBoundsPadding.md)
* [ElevatedView - apply a shadow effect on all platforms](features/ElevatedView.md)
* [Uno.Material - Material Design on all platforms](external/uno.themes/doc/material-getting-started.md)
* [Uno.Cupertino](external/uno.themes/doc/cupertino-getting-started.md)

## Core functionality

* [Enable and configure logging](logging.md)
* [Configure build telemetry](uno-toolchain-telemetry.md)
* [Add native views to the visual tree](native-views.md)
* [Enable native control styles (Android and iOS)](native-styles.md)

## Common development tasks

* [Migrating single-platform WinUI/UWP code](howto-migrate-existing-code.md)
* [Creating a cross-targeted library](migrating-libraries.md)
* [Upgrading from an older Uno.UI releases](migrating-from-previous-releases.md)

## Debugging Uno Platform applications

* [Hot Reload](xref:Uno.Features.HotReload)
* [Troubleshooting build errors](uno-builds-troubleshooting.md)
* [Debugging C# on WASM](debugging-wasm.md)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno.uitest/refs/heads/master/doc/using-uno-uitest.md

---
uid: Uno.UITest.GetStarted
---

# Using Uno.UITest

Uno.UITest is a framework to enable **unified UI Testing** of [Uno Platform apps](https://github.com/unoplatform/uno), using [NUnit 3.x](https://github.com/nunit/nunit).

This library provides a set of APIs to interact with an app, and assess its behavior using device simulators and browsers. The API set is based on [Xamarin.UITest](https://docs.microsoft.com/en-us/appcenter/test-cloud/uitest/), which makes the migration and patterns very familiar.

The testing is available through :
- Selenium for WebAssembly apps, using Chrome
- [Xamarin.UITest](https://docs.microsoft.com/en-us/appcenter/test-cloud/uitest/) and [AppCenter](https://appcenter.ms/apps) for iOS and Android apps.

The following target platforms are not yet supported:
- SkiaSharp backends (GTK, WPF and Tizen )
- Xamarin.macOS
- Windows

## How to use Uno.UITest with an Uno Platform app

> [!TIP]
> UI Testing setup is already integrate in Uno Platform 4.8 and later, see our [getting started](xref:Uno.GetStarted) to create your Uno Platform app.

- Make sure [Chrome is installed](https://www.google.com/chrome)
- In Visual Studio for Windows, [create an application](https://platform.uno/docs/articles/getting-started-tutorial-1.html) using the Uno Platform templates
- Add the following code to each `.csproj` files (iOS, Android and WebAssembly), at the end before the closing `</project>` tag:
	```xml
	<PropertyGroup Condition="'$(Configuration)'=='Debug' or '$(IsUiAutomationMappingEnabled)'=='True'">
		<IsUiAutomationMappingEnabled>True</IsUiAutomationMappingEnabled>
		<DefineConstants>$(DefineConstants);USE_UITESTS</DefineConstants>
	</PropertyGroup>
	```
- In the iOS project, add a reference to the `Xamarin.TestCloud.Agent` nuget package (0.21.8 or later)
- In the `OnLaunched` method of `App.xaml.cs`, add the following at the beginning:
	```csharp
	#if __IOS__ && USE_UITESTS
		// Launches Xamarin Test Cloud Agent
		Xamarin.Calabash.Start();
	#endif
	```
- Install the Uno Platform `dotnet new` templates:

	```sh
	dotnet new -i Uno.ProjectTemplates.Dotnet
	```
- Navigate to your `.sln` folder using a command line:
    - Create a folder named `YourAppName\YourAppName.UITests`
    - Then run :
	```
    cd YourAppName.UITests
	dotnet new unoapp-uitest
	```
    The new project will be added automatically to your solution. If you get "No templates found matching: 'unoapp-uitest'." error, please see [dotnet new templates for Uno Platform](https://platform.uno/docs/articles/get-started-dotnet-new.html) article.
- In the new UI Tests project, edit the `Constants.cs` file with values that match your project 
- In your application, add the following XAML:

	```XAML
	<StackPanel>
		<CheckBox AutomationProperties.AutomationId="cb1" AutomationProperties.AccessibilityView="Raw" Content="Test 1"/>
	</StackPanel>
	```
   > Note that `AutomationProperties.AccessibilityView="Raw"` is only required for `ContentControl` based controls to allow for `cb1` to be selectable instead of the text `Test 1`. 

- Then following test can be written:

	```csharp
	using NUnit.Framework;
	using Uno.UITest.Helpers.Queries;
	using System.Linq;
	// Alias to simplify the creation of element queries
	using Query = System.Func<Uno.UITest.IAppQuery, Uno.UITest.IAppQuery>;

	public class CheckBox_Tests : TestBase
	{
		[Test]
		public void CheckBox01()
		{
			Query checkBoxSelector = q => q.Marked("cb1");
			App.WaitForElement(checkBoxSelector);

			Query cb1 = q => q.Marked("cb1");
			App.WaitForElement(cb1);

			var value1 = App.Query(q => cb1(q).GetDependencyPropertyValue("IsChecked").Value<bool>()).First();
			Assert.IsFalse(value1);

			App.Tap(cb1);

			var value2 = App.Query(q => cb1(q).GetDependencyPropertyValue("IsChecked").Value<bool>()).First();
			Assert.IsTrue(value2);
		}
	}
	```

This sample is provided through the [`Sample.UITests` project](https://github.com/unoplatform/Uno.UITest/tree/master/src/Sample/Sample.UITests) in this repository.

### Running the tests for WebAssembly
- To test in Chrome, first deploy the WebAssemly app using `Ctrl+F5`, take note of the Url of the app
- Update the `Constants.WebAssemblyDefaultUri` property in `Constants.cs`
- Change the `Constants.CurrentPlatform` to `Platform.Browser`
- [Launch a test](https://docs.microsoft.com/en-us/visualstudio/test/getting-started-with-unit-testing?view=vs-2019) by right clicking on the test in the Test Explorer, or in the test code itself.
- A Chrome browser window will open in automated mode, and the test will execute.


### Running the tests for Android
- Build and deploy the app on a simulator
- Update the `Constants.AndroidAppName` property in `Constants.cs` to the value set in your app manifest
- Change the `Constants.CurrentPlatform` to `Platform.Android`
- [Launch a test](https://docs.microsoft.com/en-us/visualstudio/test/getting-started-with-unit-testing?view=vs-2019) by right clicking on the test in the Test Explorer, or in the test code itself.
- The application will start on the emulator, and the test will execute

### Running the tests for iOS
> testing for iOS is only available through Visual Studio for Mac, where the simulators can run.

- Open your solution in Visual Studio for mac
- Build and deploy the app on an iOS simulator
- Update the `Constants.iOSAppName` property in `Constants.cs` to the value specified in your `info.plist` file
- Change the `Constants.CurrentPlatform` to `Platform.iOS`
- [Launch a test](https://docs.microsoft.com/en-us/visualstudio/mac/testing?view=vsmac-2019)
- The application will start on the emulator, and the test will execute

This sample is provided through the [`Sample.UITests` project](https://github.com/unoplatform/Uno.UITest/tree/master/src/Sample/Sample.UITests) in this repository.

### Validating the currently running environment

```csharp
if(AppInitializer.GetLocalPlatform() == Platform.Android)
{
    Assert.Ignore();
}
```

## UI Testing in a CI environment

One of the design goal of the `Uno.UITest` library is to enable UI Testing in Pull Request builds, so that the UI testing is not an afterthought, and is part of the development flow.

You can find some scripts examples to enable such testing, using [Azure Devops hosted agents](https://docs.microsoft.com/en-us/azure/devops/pipelines/agents/hosted?view=azure-devops):
- [Android UI Testing in a Simulator](https://github.com/unoplatform/Uno.UITest/blob/master/build/android-uitest-run.sh) using Linux
- [WebAssembly UI Testing](https://github.com/unoplatform/Uno.UITest/blob/master/build/wasm-uitest-run.sh) using Linux
- [iOS UI Testing in an simulator](https://github.com/unoplatform/Uno.UITest/blob/master/build/ios-uitest-run.sh) using macOS

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-winrt.md

---
uid: uno.features.uno.winrt
---

# Non-UI Cross-Platform API - Using Uno.WinRT

Uno.WinRT is the non-UI layer of Uno Platform.

It is composed of APIs that have been present since the beginning of Uno Platform to provide cross-platform access to non-UI features such as generic filesystem, sensors, file/image/video picking, networking, and devices like MIDI, flashlight, geolocation, Game Pads, and dozens more.

These APIs can be used in a NuGet package directly, without depending on UI features.

For a list of available APIs, browse the tree on the side of this document.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/using-winui2.md

---
uid: Uno.Features.WinUI2
---

# Using Fluent styles in legacy apps

> This article is only relevant for migration of **legacy UWP-based Uno Platform applications**. Modern template has Fluent styles included by default.

## Enabling Fluent styles

1. In the `UWP` head project of your solution, install the [WinUI 2 NuGet package](https://www.nuget.org/packages/Microsoft.UI.Xaml).
1. There's no extra package to install for non-Windows head projects - the WinUI 2 controls are already included in the `Uno.UI` NuGet package which is installed with the default Uno Platform template.
1. Open the `App.xaml` file inside one of the Head project used by all platform heads. Add the `XamlControlsResources` resource dictionary to your application resources inside `App.xaml`.

    ```xml
        <Application>
            <Application.Resources>
                <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
            </Application.Resources>
        </Application>
    ```

    Or, if you have other existing application-scope resources, add `XamlControlsResources` at the top (before other resources) as a merged dictionary:

    ```xml
        <Application.Resources>
            <ResourceDictionary>
                <ResourceDictionary.MergedDictionaries>
                    <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
                    <!-- Other merged dictionaries here -->
                </ResourceDictionary.MergedDictionaries>
                <!-- Other app resources here -->
            </ResourceDictionary>
        </Application.Resources>
    ```

1. Now you're ready to use WinUI 2 controls in your application. Sample usage for the `NumberBox` control:

    ```xml
    <Page x:Class="UnoLovesWinUI.MainPage"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:local="using:UnoLovesWinUI"
        xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
        xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
        xmlns:winui="using:Microsoft.UI.Xaml.Controls"
        mc:Ignorable="d"
        Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

        <Grid>
            <winui:NumberBox />
        </Grid>
    </Page>
    ```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/getting-started/wizard/using-wizard.md

---
uid: Uno.GettingStarted.UsingWizard
---

# The Uno Platform Solution Template

> [!Video https://www.youtube-nocookie.com/embed/s_QbZbPIeWY]

## Solution Structure

Both the Visual Studio Template Wizard, which comes with the [Uno Platform Visual Studio extension](https://marketplace.visualstudio.com/items?itemName=unoplatform.uno-platform-addin-2022), and the `dotnet new` [unoapp template](xref:Uno.GetStarted.dotnet-new) 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

[!INCLUDE [Startup](includes/startup.md)]

---

### 1. Framework

[!INCLUDE [Framework](includes/framework.md)]

---

### 2. Platforms

[!INCLUDE [Platforms](includes/platforms.md)]

---

### 3. Presentation

[!INCLUDE [Presentation](includes/presentation.md)]

---

### 4. Markup

[!INCLUDE [Markup](includes/markup.md)]

---

### 5. Theme

[!INCLUDE [Theme](includes/themes.md)]

---

### 6. Extensions

[!INCLUDE [Extensions](includes/extensions.md)]

---

### 7. Features

[!INCLUDE [Features](includes/features.md)]

---

### 8. Authentication

[!INCLUDE [Authentication](includes/authentication.md)]

---

### 9. Application

[!INCLUDE [Application](includes/application.md)]

---

### 10. Testing

[!INCLUDE [Testing](includes/testing.md)]

---

### 11. CI Pipeline

[!INCLUDE [CI Pipeline](includes/cipipeline.md)]

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uwp-vs-winui3.md

---
uid: Uno.Development.UwpVsWinUI3
---

# WinUI 3 and Uno Platform

WinUI 3 is the [next generation of Microsoft's Windows UI library](https://learn.microsoft.com/windows/apps/winui/). It succeeds the UWP XAML framework as Microsoft's actively developed native UI platform for Windows. WinUI 3 supports Windows Desktop apps through [Windows AppSDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/).

> [!TIP]
> If you just want to add Fluent styles to legacy Uno Platform projects, [check the guide here](features/using-winui2.md).

## How does WinUI 3 differ from UWP XAML?

WinUI 3 differs in minor ways from UWP XAML in terms of API, and in more substantial ways in its technical comportment.

### API

The main difference between WinUI 3 and UWP XAML is the change of namespace. UWP XAML namespaces begin with 'Windows' - `Windows.UI.Xaml`, `Windows.UI.Composition`, and so on. WinUI 3 namespaces begin with 'Microsoft' - `Microsoft.UI.Xaml`, `Microsoft.UI.Composition`, and so on. Aside from that change, the API surface is very similar. Some of the remaining differences are listed in our [guide to upgrading to WinUI 3](updating-to-winui3.md).

### Technical

Below the surface, the differences are more substantial. The UWP XAML stack is part of the Windows OS. The WinUI 3 stack is decoupled from the Windows OS. This means application developers can use the newest features without worrying that they might not be supported on the end user's system.

WinUI 3 is also decoupled from the application model. The UWP XAML stack is only compatible with the 'UWP model' in which the application runs in a secure sandbox. WinUI 3 is compatible both with the 'UWP model' and with the traditional 'Win32' or 'desktop' application model in which the application has largely-unrestricted access to the rest of the OS.

## How does this affect Uno Platform?

Uno Platform is only affected by the API change - the technical changes don't apply on non-Windows platforms.

When you create a new Uno Platform application, you can choose to create a WinUI 3-compatible application (using the WinUI 3 API, and building with WinUI 3 on the Windows head project) instead of a UWP XAML-compatible application [using the `dotnet new` templates](get-started-dotnet-new.md#uno-platform-blank-application-for-winappsdk---winui-3).

### Do you plan to publish on Windows?

If Windows is one of your target platforms, then the [technical differences](#technical) discussed above apply. Probably the key question is, can your application run in the sandboxed 'UWP model', or is it better served by the unrestricted 'Win32 model'?

### Do you depend on features that haven't yet migrated to WinUI 3?

[Check the WinUI 3 roadmap](https://github.com/microsoft/microsoft-ui-xaml/blob/master/docs/roadmap.md#winui-30-feature-roadmap) for a list of features that won't be available in the initial supported release, like `InkCanvas`.

## Further reading

* [Create a new WinUI 3-flavored Uno Platform app with Project Reunion support](get-started-winui3.md)
* [Migrate an existing Uno Platform app to WinUI 3](updating-to-winui3.md)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/vscode-advanced-mobile-debugging.md

---
uid: uno.vscode.mobile.advanced.debugging
---

# Advanced Topics for VS Code for Mobile Targets

Starting from Uno 4.8.26, the Uno Platform solution templates contains the appropriate support to debug Mobile applications. See below for adjusting projects.

## Supported Features

### SourceLink and Sources embedded inside PDB

Both [Source Link](https://github.com/dotnet/designs/blob/main/accepted/2020/diagnostics/source-link.md) and "Sources embedded inside PDB" features are used by Uno Platform and are supported by the extension.

However, only Android includes the `.pdb` of the referenced assemblies inside debug builds for net6.0. This makes the features unusable for iOS and macOS, see [issue](https://github.com/xamarin/xamarin-macios/issues/11879#issuecomment-1279452073).

This situation [should be](https://github.com/dotnet/sdk/issues/1458#issuecomment-1244736464) fixed with net7.0. A workaround for .NET 6 mobile projects is to install [Cymbal](https://github.com/SimonCropp/Cymbal).

### Remote SSH

VS Code can [connect to a remote computer](https://code.visualstudio.com/docs/remote/ssh) (using `ssh`) to develop and debug projects. Note that all the sources, build and debugging are done on the remote computer, where the Uno Platform extension is being executed.

### Logpoints

[Logpoints](https://code.visualstudio.com/blogs/2018/07/12/introducing-logpoints-and-auto-attach#_introducing-logpoints) are functionally similar to adding `Console.WriteLine` but without modifying the sources.

## Converting existing projects

Existing Uno Platform projects requires a few simple changes to work properly with multiples TargetFrameworks inside VS Code.

### launch.json

You can add a default entry for all mobile targets by adding the following JSON block inside your `launch.json`.

```json
{
  "name": "Uno Platform Mobile",
  "type": "Uno",
  "request": "launch",
  // any Uno* task will do, this is simply to satisfy vscode requirement when a launch.json is present
  "preLaunchTask": "Uno: net7.0-android | Debug | android-x64"
},
```

This will ask the `Uno` debug provider how to build and launch the application. The Target Framework Moniker (TFM) selected in VS Code's status bar, e.g. `net7.0-ios`, and the target platform, e.g. `iossimulator-x64`, will be used automatically.

> [!NOTE]
> Uno Platform's [templates](https://www.nuget.org/packages/uno.templates/) already include this change.

## Debugging with the Windows Subsystem for Android

You first need to [connect](https://learn.microsoft.com/windows/android/wsa/#connect-to-the-windows-subsystem-for-android-for-debugging) to the Windows Subsystem for Android (WSA) in order to use it for debugging. From the command-line type:

```bash
adb connect 127.0.0.1:58526
```

and you should then be able to see the WSA device inside VSCode. You can also confirm it's connected from the command-line:

```bash
$ adb devices -l
List of devices attached
127.0.0.1:58526        device product:windows_arm64 model:Subsystem_for_Android_TM_ device:windows_arm64 transport_id:1
```

## Settings

### Unoplatform › Debugger: Exception Options

You can choose to break execution on specific exceptions, either always or if the exception is unhandled.

Note: Those settings do not apply when debugging Windows (WinUI) or macOS (AppKit) application since it use the CoreCLR debugger.

### Unoplatform › Debugger › Ios › Mlaunch: Extra Arguments

For example you can add `-vvvvv` to get more verbosity from `mlaunch`.

This can be useful if you run into issues deploying your application to an iOS device.

### Unoplatform › Debugger › Ios › Mlaunch: Path

By default the version of `mlaunch` associated with the currently iOS workload will be used to launch application to iOS devices.

You can override the path to the `mlaunch` tool to be used. For example you could set the path to `/Library/Frameworks/Xamarin.iOS.framework/Versions/Current/bin/mlaunch` to use the version from the legacy (pre-net6.0) Xamarin.iOS SDK.

This can be useful when a new Xcode is released, requiring an update to `mlaunch`, while allowing you to use the current stable SDK version for development.

### Unoplatform › Debugger › Ios › Simulator: X64

By default the simulators are listed for both `arm64` and `x64` on Apple Silicon Macs.
`x64` simulators are provided using Rosetta emulation and is required if `arm64` support is missing for some dependencies (e.g. SkiaSharp).

This can be useful if your project has dependencies that are not available yet for the `arm64` architecture.

## Environment Variables

### Xcode override

The Uno extension uses `xcrun` to find the active Xcode version to use. You can override this version of Xcode by setting the `DEVELOPER_DIR` environment variable. More information can be found running `man xcrun` inside the terminal.

## Advanced Debugger Configuration

It is possible to create advanced `launch.json` and `tasks.json` entries if additional customization is needed for a project.

### Editing `launch.json`

The extension provides default launch configurations for supported platforms, without the need to define them inside the `launch.json` file.

If you need to define launches or modify the defaults then you can can create your own.

1. Press the `Shift+Cmd+P` keys to open the **Command Palette**
1. Select the `Debug: Select and Start Debugging` item
1. Select the `Add Configuration...` item
1. Select `.NET Custom Launch Configuration for Uno Platform` item
1. This will insert a JSON block that looks like the following:

    ```json
    {
      "comment1": "// name: unique name for the configuration, can be identical to preLaunchTask",
      "name": "Uno: net6.0-android | Debug | android-x64",
      "comment2": "// type: 'Uno' for mono-based SDK, 'coreclr' for desktop targets",
      "type": "Uno",
      "request": "launch",
      "comment3": "// preLaunchTask format is 'Uno: {tfm} | {config}[ | {rid]}]' where ",
      "comment4": "// * {tfm} is the target framework moniker, e.g. net6.0-ios",
      "comment5": "// * {config} is the build configuration, e.g. 'Debug' or 'Release'",
      "comment6": "// * {rid} is the optional runtime identifier, e.g. 'osx-arm64'",
      "comment7": "// E.g. 'Uno: net6.0-ios | Debug | iossimulator-x64', 'Uno: net6.0 | Debug' for desktop",
      "preLaunchTask": "Uno: net6.0-android | Debug | android-x64"
    },
    ```

1. Follow the comments to construct the launch required by your target platform, for example:

    ```json
    {
      "name": "net7.0-ios | simulator | x64",
      "type": "Uno",
      "request": "launch",
      "preLaunchTask": "Uno: net7.0-ios | Debug | iossimulator-x64"
    },
    ```

If you follow the `Uno: {tfm} | {config}[ | {rid]}]` convention then there is no need to add entries inside the `tasks.json` file, the extension already provides them.

### Customizing tasks.json

The extension provides default build tasks for most platforms without the need to define them inside the `tasks.json` file.
If you need to define tasks or something that the default built-in tasks do not provide, you can create your own.

1. Press the `Shift+Cmd+P` keys to open the **Command Palette**.
1. Select the `Tasks: Configure Tasks` item.
1. Pick the `Uno: *` task that is the closest to your need.
1. Edit the `args` section but avoid changing the other values (besides the `label`) to keep automation working.

See [VS Code documentation](https://code.visualstudio.com/docs/editor/tasks) for more information.

#### Example

```json
{
  "label": "custom-mac-build",
  "command": "dotnet",
  "type": "process",
  "args": [
    "build",
    "${workspaceFolder}/unoapp/unoapp.csproj",
    "/property:GenerateFullPaths=true",
    "/consoleloggerparameters:NoSummary",
    // specify the target platform - since there's more than one inside the mobile.csproj
    "/property:Configuration=Debug",
    // this is to workaround both an OmniSharp limitation and a dotnet issue #21877
    "/property:UnoForceSingleTFM=true"
    // other custom settings that you need
  ],
  "problemMatcher": "$msCompile"
},
```

#### Tips

* Most of the build settings should be done (or changed) inside the `.csproj` file. This way only a simple `dotnet build` is needed to create the applications.

* The easiest way to create a custom task is to look at the build logs and see what is normally provided, by default, to build for a specific target platform.

* You will also need a custom launch target that will use the `label` name for it's `preLaunchTask`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/wasm-appmanifest.md

---
uid: Uno.Development.WasmAppManifest
---

# AppManifest for WebAssembly head project

The `[AppName]` project in your solution typically includes a manifest file containing settings for the WebAssembly application. This file is typically generated for you under `Platforms/WebAssembly/WasmScripts/AppManifest.js`.

## AppManifest properties

This app manifest file allows you to customize certain aspects of the WebAssembly application, including its loading screen. This loading UI is often referred to as the "splash screen" in documentation. For more information, see [How to manually add a splash screen](xref:Uno.Development.SplashScreen#5-webassembly).

## Add a missing manifest file

If you created an application without using the default Uno [templates](xref:Uno.GetStarted.dotnet-new), you may need to add the manifest file manually.

To do this, create a folder named `Platforms/WebAssembly/WasmScripts` in your `[AppName]` project, with a file containing the JavaScript code below
(e.g. `AppManifest.js`).

If the project is not using the [Uno.Sdk](xref:Uno.Features.Uno.Sdk), Set the manifest file's build action to `Embedded resource`, and edit the contents of this file to resemble the following:

```javascript
var UnoAppManifest = {
    splashScreenImage: "Assets/SplashScreen.scale-200.png",
    splashScreenColor: "transparent",
    displayName: "SplashScreenSample"
}
```

## See also

- [WebAssembly: Supported AppManifest properties](xref:Uno.Development.SplashScreen#5-webassembly)
- [Deep-dive: How Uno works on WebAssembly](xref:Uno.Contributing.Wasm#web-webassembly)
- [Get Started: Get the Uno Platform templates](xref:Uno.GetStarted)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/interop/wasm-javascript-1.md

---
uid: Uno.Interop.WasmJavaScript1
---

# Embedding Existing JavaScript Components Into Uno-WASM - Part 1

## HTML5 is a Rich and Powerful Platform

Uno Platform fully embraces HTML5 as its display backend when targeting WebAssembly, for both Native and Skia renderers. As a result, it is possible to integrate with almost any existing JavaScript library to extend the behavior of an app.

## Embedding assets

In the HTML world, everything running in the browser is assets that must be downloaded from a server. To integrate existing JavaScript frameworks, they can be either downloaded from another location on the Internet (usually from a CDN service) or embedded and deployed with the app.

The Uno Bootstrapper can automatically embed any asset and deploy it with the app. Some of them (CSS & JavaScript) can also be loaded with the app. Here's how to declare them in a *Uno Wasm* project:

1. **JavaScript files** should be in the `Platforms/WebAssembly/WasmScripts` folder. They will be copied to the output folder and loaded automatically by the bootstrapper when the page loads.

2. **CSS Style files** should be in the `Platforms/WebAssembly/WasmCSS` folder. They will be copied to the output folder and referenced in the *HTML head* of the application.

3. **Asset files** can be placed in the `Assets` folder. These files will be copied to the output folder and will preserve the same relative path to the `Assets` folder.

4. Alternatively, **any kind of asset file** can be placed directly in the `wwwroot` folder as with any standard ASP.NET Core project. They will be deployed with the app, but the application code is responsible for fetching and using them.

   > **Is it an ASP.NET Core "web" project?**
   > No, but it shares a common structure. Some of the deployment features, like the `wwwroot` folder, and the Visual Studio integration for running/debugging are reused in a similar way to an ASP.NET Core project. The C# code put in the project will run in the browser, using the .NET runtime. There is no need for a server side component in Uno-Wasm projects.

## Embedding Native Elements

Embedding native JavaScript elements is done through the `Uno.UI.NativeElementHosting.BrowserHtmlElement` class, which serves as an entry point to interact with your native element.

> [!IMPORTANT]
> The `BrowserHtmlElement` class is available on all target frameworks, eliminating the need for `#if` condition code, but it is only usable on WebAssembly. You'll need to guard its use by validating the platform with the `OperatingSystem` class.

```csharp
using Uno.UI.NativeElementHosting.BrowserHtmlElement;

public sealed partial class MyControlHost : ContentControl
{
  private BrowserHtmlElement? _element;

  public MyControlHost()
  {
    if (OperatingSystem.IsBrowser())
    {
      _element = BrowserHtmlElement.CreateHtmlElement("div");
      Content = _element;
    }
    else
    {
      Content = "This control only supported on WebAssembly on the Browser";
    }
  }
}
```

This way, your native element is hosted inside a content control of your choosing. You can replace it with any available HTML tag.

Once created, it is possible to interact directly with this element by calling `BrowserHtmlElement` methods.

Here is a list of helper methods used to facilitate the integration with the HTML DOM:

* The method `element.SetCssStyle()` can be used to set a CSS Style on the HTML element. Example:

  ```csharp
  // Setting only one CSS style
  _element.SetCssStyle("text-shadow", "2px 2px red");

  // Setting many CSS styles at once using C# tuples
  _element.SetCssStyle(("text-shadow", "2px 2px blue"), ("color", "var(--app-fg-color1)"));
  ```

* The `element.ClearCssStyle()` method can be used to set CSS styles to their default values. Example:

  ```csharp
  // Reset text-shadow style to its default value
  _element.ClearCssStyle("text-shadow");

  // Reset both text-shadow and color to their default values
  _element.ClearCssStyle("text-shadow", "color");
  ```

* The `element.SetHtmlAttribute()` and `element.ClearHtmlAttribute()` methods can be used to set HTML attributes on the element:

  ```csharp
  // Set the "href" attribute of an <a> element
  _element.SetHtmlAttribute("href", "#section2");

  // Set many attributes at once (less interop)
  _element.SetHtmlAttribute(("target", "_blank"), ("referrerpolicy", "no-referrer"));

  // Remove attribute from DOM element
  _element.ClearHtmlAttribute("href");

  // Get the value of an attribute of a DOM element
  var href = _element.GetHtmlAttribute("href");
  ```

* The `element.SetCssClass()` and `element.UnsetCssClass()` methods can be used to add or remove CSS classes to the HTML Element:

  ```csharp
  // Add the class to element
  _element.SetCssClass("warning");

  // Add many classes at once (less interop)
  _element.SetCssClass("warning", "level2");

  // Remove class from element
  _element.UnsetCssClass("paused");

  // You can also set one class from a list of possible values.
  // Like a radio-button, like non-selected values will be unset
  var allClasses = new [] { "Small", "Medium", "Large"};
  _element.SetCssClass(allClasses, 2); // set to "Large"
  ```

* The `element.SetHtmlContent()` method can be used to set arbitrary HTML content as child of the control.

  ```csharp
  _element.SetHtmlContent("<h2>Welcome to Uno Platform!</h2>");
  ```

* Finally, it is possible to make calls from and to JavaScript code by using [JSImport/JSExport](xref:Uno.Wasm.Bootstrap.JSInterop). The javascript code is directly executed in the context of the browser, giving the ability to perform anything that JavaScript can do. See next section for more details.

## Raising custom Javascript events

It's also possible to have Javscript components raise events to be handled by C# code.

From your Javascript or TypeScript code, you can raise events:

```javascript
  // Generate a custom generic event from JavaScript/Typescript
  htmlElement.dispatchEvent(new Event("simpleEvent"));

  // Generate a custom event with a string payload
  const payload = "this is the payload of the event";
  htmlElement.dispatchEvent(new CustomEvent("stringEvent", { detail: payload }));

  // Generate a custom event with a complex payload
  const payload = { property:"value", property2: 1234 };
  htmlElement.dispatchEvent(new CustomEvent("complexEvent", { detail: payload }));
```

Then from your C# code, add the following:

```csharp
  protected override void OnLoaded()
  {
      // Note: following extensions are in the namespace "Uno.Extensions"
      this.RegisterHtmlEventHandler("simpleEvent", OnSimpleEvent);
      this.RegisterHtmlEventHandler("stringEvent", OnStringEvent);
      this.RegisterHtmlEventHandler("complexEvent", OnComplexEvent);
  }

  private void OnSimpleEvent(object sender, JSObject args)
  {
      // You can react on "simpleEvent" here
  }

  private void OnStringEvent(object sender, JSObject args)
  {
      // You can react on "stringEvent" here
      var detail = args.GetPropertyAsString("detail");
  }

  private void OnComplexEvent(object sender, JSObject args)
  {
      // You can react on "complexEvent" here
      var detail = args.GetPropertyAsJSObject("detail");
      var property = detail?.GetPropertyAsString("property");
      var property2 = detail?.GetPropertyAsInt32("property2");
  }
```

## 🔬 Going further

* [Continue with Part 2](xref:Uno.Interop.WasmJavaScript2) - an integration of a syntax highlighter component.
* [Continue with Part 3](xref:Uno.Interop.WasmJavaScript3) - an integration of a more complex library with callbacks to application.
* Read the [Uno Wasm Bootstrapper](xref:UnoWasmBootstrap.Overview) documentation.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/interop/wasm-javascript-2.md

---
uid: Uno.Interop.WasmJavaScript2
---

# Embedding Existing JavaScript Components in Uno Platform - Part 2

Let's create an app to integrate a Syntax Highlighter named [`PrismJS`](https://prismjs.com/). This library is simple and is self-contained - there's no external dependencies.

## Integration of PrismJS in a project

### 0. Before starting

📝 To reproduce the code in this article, you must [prepare a development environment using Uno's _Getting Started_ article](xref:Uno.GetStarted).

### 1. Create the projects

🎯 This section is very similar to the [Create a Counter App with Uno Platform](xref:Uno.Workshop.Counter) tutorial in the official documentation.

Create a [new Uno Platform App project](xref:Uno.GetStarted) using one of the getting started **blank** or **recommended** presets.

### 2. Create a control in managed code

🎯  In this section, a control named `PrismJsView` is created in code and used in the XAML page (`MainPage.xaml`) to present it.

1. From the `[MyApp]` project, create a new class file named `PrismJsView.cs`. and copy the following code:

    ```csharp
    using System;
    using System.Collections.Generic;
    using System.Text;
    using Uno.Foundation;
    using Uno.UI.Runtime.WebAssembly;
   
    namespace PrismJsDemo;
   
    using Uno.UI.NativeElementHosting;

    namespace PrismJsDemo;

    class PrismJsView : ContentControl
    {
        private BrowserHtmlElement? _element;

        // *************************
        // * Dependency Properties *
        // *************************
        public static readonly DependencyProperty CodeProperty = DependencyProperty.Register(
            nameof(Code),
            typeof(string),
            typeof(PrismJsView),
            new PropertyMetadata(default(string), CodeChanged));

        public string Code
        {
            get => (string)GetValue(CodeProperty);
            set => SetValue(CodeProperty, value);
        }
        public static readonly DependencyProperty LangProperty = DependencyProperty.Register(
            "Lang",
            typeof(string),
            typeof(PrismJsView),
            new PropertyMetadata(default(string), LangChanged));

        public string Lang
        {
            get => (string)GetValue(LangProperty);
            set => SetValue(LangProperty, value);
        }

        // ***************
        // * Constructor *
        // ***************
        public PrismJsView()
        {
            _element = BrowserHtmlElement.CreateHtmlElement("code");
            Content = _element;
        }

        // ******************************
        // * Property Changed Callbacks *
        // ******************************
        private static void CodeChanged(DependencyObject dependencyobject, DependencyPropertyChangedEventArgs args)
        {
            // TODO: generate HTML using PrismJS here
        }
        private static void LangChanged(DependencyObject dependencyobject, DependencyPropertyChangedEventArgs args)
        {
            // TODO: generate HTML using PrismJS here
        }
    }
    ```

   This will define a control having 2 properties, one code `Code` and another one for `Lang`.

2. Change the `MainPage.xaml` file to the following content:

   ```xml
   <Page
       x:Class="PrismJsDemo.MainPage"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:local="using:PrismJsDemo"
       xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
       xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
       mc:Ignorable="d">
       <Grid Padding="10">
           <Grid.RowDefinitions>
               <RowDefinition Height="Auto" />
               <RowDefinition Height="*" />
               <RowDefinition Height="*" />
           </Grid.RowDefinitions>
           <TextBox x:Name="lang" Text="csharp" Grid.Row="0" />
           <TextBox x:Name="code" Text="var x = 3;&#xA;var y = 4;" AcceptsReturn="True" VerticalAlignment="Stretch" Grid.Row="1" />
           <Border BorderBrush="Blue" BorderThickness="2" Background="LightBlue" Padding="10" Grid.Row="2">
               <local:PrismJsView Code="{Binding Text, ElementName=code}" Lang="{Binding Text, ElementName=lang}"/>
           </Border>
       </Grid>
   </Page>
   ```

3. Press CTRL-F5.  You should see this:

   ![Browser image](assets/image-20200414144707425.png)

4. Press F12 (on Chrome, may vary on other browsers).
5. Click on the first button and select the light-blue part in the app.

   ![Select Item button - F12](assets/image-20200325132528604.png)

6. It will bring the DOM explorer to a `code` node. The `PrismJsView` should be right below after opening it.

   ![Html Explorer](assets/image-20200325132859849.png)

   The `code` control is there!

👌 The project is now ready to integrate PrismJS.

### 3. Add JavaScript & CSS files

🎯  In this section, PrismJS files are downloaded from their website and placed as assets in the app.

1. Go to [Prism download page](https://prismjs.com/download.html).
2. Choose desired Themes & Languages (`Default` theme + all languages is used for the demo).
3. Press the `DOWNLOAD JS` button and put the `prism.js` file in the `WasmScripts` folder of the `.Wasm` project.

   > Putting the `.js` file in this folder will instruct the Uno Wasm Bootstrapper to automatically load the JavaScript file during startup.
4. Press the `DOWNLOAD CSS` button and put the `prism.css` file in the `WasmCSS` folder of the `.Wasm` project.

   > Putting the `.css` file in this folder will instruct the Uno Wasm Bootstrapper to automatically inject a `<link>` HTML instruction in the resulting `index.html` file to load it with the browser.
5. Right-click on the `.Wasm` project node in the Solution Explorer, and pick `Edit Project File` (it can also work by just selecting the project, if the `Preview Selected Item` option is activated).
6. Insert this in the appropriate `<ItemGroup>`:

   ```xml
   <ItemGroup>
     <EmbeddedResource Include="WasmCSS\Fonts.css" />
     <EmbeddedResource Include="WasmCSS\prism.css" /> <!-- This is new -->
     <EmbeddedResource Include="WasmScripts\AppManifest.js" />
     <EmbeddedResource Include="WasmScripts\prism.js" /> <!-- This one too -->
   </ItemGroup>
   ```

   > For the Uno Wasm Bootstrapper to take those files automatically and load them with the application, they have to be put as embedded resources. A future version of Uno may remove this requirement.
7. Compile & run
8. Once loaded, press F12 and go into the `Sources` tab. Both `prism.js` & `prism.css` files should be loaded this time.

   ![Prism Loaded in browser](assets/image-20200414143931953.png)

### 4. Invoke JavaScript from Managed Code

🎯  In this section, PrismJS is used from the app.

1. First, there is a requirement for _PrismJS_ to set the  `white-space` style at a specific value, as [documented here](https://github.com/PrismJS/prism/issues/1237#issuecomment-369846817). An easy way to do this is to set in directly in the constructor like this:

    ```csharp
    public PrismJsView()
    {
        _element = BrowserHtmlElement.CreateHtmlElement("code");
        Content = _element;

        // This is required to set to <code> style for PrismJS to works well
        // https://github.com/PrismJS/prism/issues/1237#issuecomment-369846817
        _element.SetCssStyle("white-space", "pre-wrap");
    }
    ```

2. Now, we need to create an `UpdateDisplay()` method, used to generate HTML each time there's a new version to update. Here's the code for the method to add in the `PrismJsView` class:

   ```csharp
    private void UpdateDisplay(string oldLanguage = null, string newLanguage = null)
    {
        string javascript = 
            $$"""
            (function(){
                // Prepare Prism parameters
                const code = "{{BrowserHtmlElement.EscapeJs(Code)}}";
                const oldLanguageCss = "language-{{BrowserHtmlElement.EscapeJs(oldLanguage)}}";
                const newLanguageCss = "language-{{BrowserHtmlElement.EscapeJs(newLanguage)}}";
                const language = "{{BrowserHtmlElement.EscapeJs(newLanguage ?? Lang)}}";
                // Process code to get highlighted HTML
                const prism = window.Prism;
                let html = code;
                if(prism.languages[language]) {
                    // When the specified language is supported by PrismJS...
                    html = prism.highlight(code, prism.languages[language], language);
                }

                // Display result
                element.innerHTML = html;
                // Set CSS classes, when required
                if(oldLanguageCss) {
                    element.classList.remove(oldLanguageCss);
                }
                if(newLanguageCss) {
                    element.classList.add(newLanguageCss);
                }
            })();
            """;

        _element.ExecuteJavascript(javascript);
    }
    ```

3. Change `CodeChanged()` and `LangChanged()` to call the new `UpdateDisplay()` method:

   ```csharp
   private static void CodeChanged(DependencyObject dependencyobject, DependencyPropertyChangedEventArgs args)
   {
       (dependencyobject as PrismJsView)?.UpdateDisplay();
   }
   private static void LangChanged(DependencyObject dependencyobject, DependencyPropertyChangedEventArgs args)
   {
       (dependencyobject as PrismJsView)?.UpdateDisplay(args.OldValue as string, args.NewValue as string);
   }
   ```

4. We also need to update the result when the control is loaded in the DOM. So we need to change the constructor again like this:

   ```csharp
   public PrismJsView()
   {
       // This is required to set to <code> style for PrismJS to works well
       // https://github.com/PrismJS/prism/issues/1237#issuecomment-369846817
       _element.SetCssStyle("white-space", "pre-wrap");
       // Update the display when the element is loaded in the DOM
       Loaded += (snd, evt) => UpdateDisplay(newLanguage: Lang);
   }
   ```

5. Compile & run. It should work like this:

   ![Final browser result](assets/image-20200415135422628.png)

## 🔬 Going further

This sample is a very simple integration as there is no _callback_ from HTML to managed code and _PrismJS_ is a self-contained framework (it does not download any other JavaScript dependencies).
Some additional improvements can be done to make the code more production ready:

* **Make the control multi-platform**. Another would be to use a [WebView](xref:Uno.Controls.WebView2) on other platforms, giving the exact same text-rendering framework everywhere. The code of this sample won't run on non-WebAssembly targets.
* **Use script files instead of using `ExecuteJavascript`**. That would have the advantage of improving performance and making it easier to debug the code.
* **Support more PrismJS features**. There are many [_plugins_ for PrismJS](https://prismjs.com/#plugins) that can be used. Most of them are very easy to implement.
* [Continue with Part 3](xref:Uno.Interop.WasmJavaScript3) - an integration of a more complex library with callbacks to application.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/interop/wasm-javascript-3.md

---
uid: Uno.Interop.WasmJavaScript3
---

# Embedding Existing JavaScript Components Into Uno-WASM - Part 3

In the previous article, we used a simple _syntax highlighter_ to enhance the display of text in HTML. It may not be enough for some apps: it's often required for JavaScript components to call back into the C# side of the application. The easiest way to do that in Uno for WebAssembly is by using [_DOM Events_](https://developer.mozilla.org/docs/Web/Guide/Events/Creating_and_triggering_events). Uno Platform apps can [consume DOM Events](xref:Uno.Interop.WasmJavaScript1l) very easily.

Let's create an application using this feature.

## Integration of Flatpickr - Callback to app from JavaScript

📝 [Flatpickr](https://flatpickr.js.org/) is a lightweight, self-contained date and time picker. It is an easy way to explore how JavaScript-side code can call back to the managed application using a `CustomEvent`. In this case, this will be used to report when the picker is opened and a date and time was picked.

### 0. Before starting

📝 To reproduce the code in this article, you must [prepare a development environment using Uno's _Getting Started_ article](xref:Uno.GetStarted).

### 1. Create the solution in Visual Studio

📝 This part is very short because it is similar to the previous article ([part 2](wasm-javascript-2.md)):

1. Create a `Uno Platform App` project and name it `FlatpickrDemo`.
1. Compile & Run to make sure everything works.

### 2. Inject Flatpickr from CDN

🎯 This section is using a CDN to get Flatpickr instead of hosting the JavaScript directly in the application. It is not always the best solution as it creates a dependency on the Internet availability. Any change made server-side could break the application.

An easy way to achieve this is to add JavaScript code to load the CSS file directly from the CDN. The JavaScript portion of Flatpickr will be lazy-loaded with the control later.

Create a new _JavaScript_ file `flatpickrloader.js` in the `Platforms/WebAssembly/WasmScripts` folder of the project:

   ```javascript
   (function () {
       const head = document.getElementsByTagName("head")[0];

       // Load Flatpickr CSS from CDN
       const link = document.createElement("link");
       link.rel = "stylesheet";
       link.href = "https://cdn.jsdelivr.net/npm/flatpickr/dist/flatpickr.min.css";
       head.appendChild(link);
   })();
   ```

   This will load the Flatpickr assets directly from CDN.

### 3. Uno controls and XAML

🎯 This section is creating a control used in the XAML. It will activate `Flatpickr` on the control's `<input>` element.

1. Create a `FlatpickrView.cs` class in the `[MyApp]` project like this:

    ```csharp
    using Uno.UI.NativeElementHosting;

    namespace FlatpickrDemo;

    public class FlatpickrView : ContentControl
    {
        private BrowserHtmlElement? _element;

        // *************************
        // * Dependency Properties *
        // *************************
        public static readonly DependencyProperty SelectedDateTimeProperty = DependencyProperty.Register(
            nameof(SelectedDateTime), typeof(DateTimeOffset?), typeof(FlatpickrView), new PropertyMetadata(default(DateTimeOffset?)));

        public DateTimeOffset? SelectedDateTime
        {
            get => (DateTimeOffset)GetValue(SelectedDateTimeProperty);
            set => SetValue(SelectedDateTimeProperty, value);
        }

        public static readonly DependencyProperty IsPickerOpenedProperty = DependencyProperty.Register(
            nameof(IsPickerOpened), typeof(bool), typeof(FlatpickrView), new PropertyMetadata(false));

        public bool IsPickerOpened
        {
            get => (bool)GetValue(IsPickerOpenedProperty);
            set => SetValue(IsPickerOpenedProperty, value);
        }

        // ***************
        // * Constructor *
        // ***************
        public FlatpickrView()
        {
            if (OperatingSystem.IsBrowser())
            {
                _element = BrowserHtmlElement.CreateHtmlElement("input");
                Content = _element;
            }
            else
            {
                Content = "Only supported on WebAssembly";
            }

            // Load Flatpickr using JavaScript
            LoadJavaScript();
        }

        // ******************
        // * Initialization *
        // ******************
        private void LoadJavaScript()
        {
            // For demo purposes, Flatpickr is loaded directly from CDN.
            // Uno Platform uses AMD module loading, so you must give a callback when the resource is loaded.
            // We can access the corresponding DOM HTML Element by using the "element" variable available in the scope
            var javascript = $@"require([""https://cdn.jsdelivr.net/npm/flatpickr""], f => f(element));";

            _element?.ExecuteJavascript(javascript);
        }

        // ******************
        // * Event Handlers *
        // ******************
    }
    ```

2. Change the `MainPage.xaml` in the `[MyApp]` project like this:

   ```xml
   <Page
       x:Class="FlatpickrDemo.MainPage"
       xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
       xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
       xmlns:local="using:FlatpickrDemo"
       xmlns:d="http://schemas.microsoft.com/expression/blend/2008"
       xmlns:mc="http://schemas.openxmlformats.org/markup-compatibility/2006"
       mc:Ignorable="d"
       Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
   
       <StackPanel Spacing="10" Padding="20">
         <TextBlock FontSize="15">
        Is Picker opened: <Run FontSize="20" FontWeight="Bold" Text="{Binding IsPickerOpened, ElementName=picker}" />
            <LineBreak />Picked Date/Time: <Run FontSize="20" FontWeight="Bold" Text="{Binding SelectedDateTime, ElementName=picker}" />
         </TextBlock>
         <TextBlock FontSize="20">Flatpickr control:</TextBlock>
   
         <local:FlatpickrView Height="20" Width="300"  x:Name="picker" HorizontalAlignment="Left" />
       </StackPanel>
   </Page>
   ```

3. After pressing CTRL-F5, after clicking on the `<input>` rectangle, this should appear:

   ![Calendar picker 1](assets/image-20200415144159362.png)

📝 Almost there, still need to _call back_ to the managed code portion of the application.

### 4. Add a way to call managed code from JavaScript

🎯 This section will use `CustomEvent` to route Flatpickr's events to managed code.

1. Register event handlers for 2 custom events: `DateChanged` and `OpenedStateChanged`. To achieve this, put this code at the end of the `FlatpickrView` constructor:

    ```csharp
    // Register event handler for events from the DOM
    _element.RegisterHtmlEventHandler("DateChanged", OnDateChanged);
    _element.RegisterHtmlEventHandler("OpenedStateChanged", OnOpenedStateChanged);
    ```

2. Add the implementation for the two handlers in the class:

    ```csharp
    private void OnDateChanged(object sender, JSObject e)
    {
        if (DateTimeOffset.TryParse(e.GetPropertyAsString("detail"), DateTimeFormatInfo.InvariantInfo, DateTimeStyles.AssumeLocal, out var dto))
        {
            SelectedDateTime = dto;
        }
    }

    private void OnOpenedStateChanged(object sender, JSObject e)
    {
        switch (e.GetPropertyAsString("detail"))
        {
            case "open":
                IsPickerOpened = true;
                break;
            case "closed":
                IsPickerOpened = false;
                break;
        }
    }
    ```

3. Change the initialization of `Flatpickr` in injected JavaScript to raise events. Change the implementation of the `OnLoaded` method to this instead:

   ```csharp
   private void LoadJavaScript()
   {
       // For demo purposes, Flatpickr is loaded directly from CDN.
       // Uno uses AMD module loading, so you must give a callback when the resource is loaded.
       // We can access the corresponding DOM HTML Element by using the "element" variable available in the scope
       var javascript = $@"require([""https://cdn.jsdelivr.net/npm/flatpickr""], f => {{
           // Route Flatpickr events following Uno's documentation
           // https://platform.uno/docs/articles/wasm-custom-events.html
           const options = {{
               onChange: (dates, str) => element.dispatchEvent(new CustomEvent(""DateChanged"", {{detail: str}})),
               onOpen: () => element.dispatchEvent(new CustomEvent(""OpenedStateChanged"", {{detail: ""open""}})),
               onClose: () => element.dispatchEvent(new CustomEvent(""OpenedStateChanged"", {{detail: ""closed""}}))
            }};
   
            // Instantiate Flatpickr on the element
            f(element, options);
       }});";
   
       this.ExecuteJavascript(javascript);
   }
   ```

4. Compile & Run. Here's the result:

   ![Final result](assets/flatpickr-final.gif)

### Troubleshooting

If your JavaScript integration is not behaving properly, you can troubleshoot with hints below.

#### My JavaScript control does not accept pointer input

When using the WebAssembly Native renderer, in the constructor of your wrapper control, add the following:

```csharp
// XAML behavior: a non-null background is required on an element to be "visible to pointers".
// Uno reproduces this behavior, so we must set it here even if we're not using the background.
// Not doing this will lead to a `pointer-events: none` CSS style on the control.
Background = new SolidColorBrush(Colors.Transparent);
```

#### `TextBlock` content is not visible in browsers with the dark theme

`TextBlock` defaults the text color as White correctly but `Page` background needs to be set correctly.

```xml
<Page 
    ...
    Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
```

## 🔬 Going further

This article illustrates how to integrate external assets (JavaScript and css files) and how to leverage JavaScript's `CustomEvent` in an Uno application.

More steps could be done to make the code production ready:

* **Make the control multi-platform**. Many date/time pickers exist on all platforms. It should be easy on other platforms to connect the same control to another great date picker native to the platform - no need to embed a WebView for this on other platforms.
* **Create script files instead of generating dynamic JavaScript**. As in previous article, this would have the advantage of improving performance and increase the ability to debug it.
* **Support more Flatpickr features**. There are a [lot of features in Flatpickr](https://flatpickr.js.org/examples/) you can leverage to make a perfect versatile control.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/ways-to-contribute.md

---
uid: Uno.Contributing.WaysToContribute
---

# Ways to contribute to Uno Platform

There are lots of ways to contribute to the Uno Platform, and all of them are appreciated. You can provide feedback, report bugs, give suggestions, contribute code, and share your Uno expertise with others.

## Provide feedback

The Uno Platform is an ongoing effort. Bug reports and feature requests are important for prioritizing where that effort goes, and identifying the most pressing user needs. Your feedback is important to us - we want to hear about your experience, scenarios, and requirements.

### Report a bug by opening an issue

If you think you've found a bug, the first thing to do is [search the existing issues](https://github.com/unoplatform/Uno/issues?q=is%3Aissue+is%3Aopen+label%3Akind%2Fbug) to check if it's already been reported. If it has been opened, provide additional commentary so we know more users are being affected.

The best way to get your bug fixed is to be as detailed as you can be about the problem.
**Providing a minimal project, stripped off as much code as possible, with steps to reproduce the problem (typed or screen-capture) is ideal.**

Here are questions you can consider before you file a bug to make sure you're not missing any important information. The bug submission template will also ask for this information.

Pre-Submission check:

1. Did you read the [documentation](https://platform.uno/docs/articles/intro.html)?
2. Did you check the latest [pre-release](https://www.nuget.org/packages/Uno.UI/absoluteLatest) of Uno Platform to see if the issue has been fixed?
3. Does the issue exist on the WinUI project (in which case it is not an Uno Platform issue)

Issue Filing [via logging a new bug report](https://github.com/unoplatform/uno/issues/new?labels=kind%2Fbug%2C+triage%2Funtriaged&template=bug-report.md).:

1. Did you include the snippet of the broken code in the issue?
2. What are the *EXACT* steps to reproduce this problem?
3. What specific Uno Platform version or build are you using?
4. What operating system are you using?
5. What platform(s) are you targeting that are experiencing the issue? Is it working on some platform(s) and not on others.
6. What IDE and version are you using?

[Log a new bug report](https://github.com/unoplatform/uno/issues/new?labels=kind%2Fbug%2C+triage%2Funtriaged&template=bug-report.md)

GitHub supports [Markdown](https://help.github.com/articles/github-flavored-markdown/), so when filing issues, be sure to check the formatting in the 'Preview' tab before hitting submit.

### Request a feature

If you need a [WinUI feature](https://learn.microsoft.com/uwp/api/microsoft.ui.xaml.controls) that Uno Platform doesn't support yet, you should [submit a feature request](https://github.com/unoplatform/uno/issues/new?labels=kind%2Fenhancement%2C+triage%2Funtriaged&template=enhancement.md). Check [existing issues first](https://github.com/unoplatform/uno/issues?q=is%3Aissue+is%3Aopen+label%3Akind%2Fenhancement) in case the same feature request already exists (in which case you can upvote the existing issue).

To help us understand and prioritize your request, please provide as much detail as possible about your scenario and why the feature or enhancement would be useful.

Wherever we can, we prefer to implement WinUI APIs for maximum cross-platform compatibility and existing code support, but for features/functionality not covered by WinUI's API, the same feature request process applies.

### Ask (and answer) questions

If you have a question, be sure first to check out our [documentation](https://platform.uno/docs/articles/intro.html). But if you are still stuck, please visit [GitHub Discussions](https://github.com/unoplatform/uno/discussions) where our engineering team and community will be able to help you.

If you've already done some Uno development, maybe there's a GitHub discussion question you can answer, giving another user the benefit of your experience.

For a more direct conversation, [visit our Discord Server](https://platform.uno/discord).

### Spreading the word

We love to see the community grow, and whether you're trying Uno for the first time or you're an old pro, it's great to share whatever you've learnt.

You can:

- write a blog post
- present Uno at a local user group
- share your open-source Uno projects

Whatever you do, let us know [through X/Twitter](https://x.com/unoplatform), our [Discord Server](https://platform.uno/discord) in #contributing, or by emailing us at [info@platform.uno](mailto:info@platform.uno).

## Contributing code

The WinUI framework is pretty big, but many hands make light work. We welcome code and content contributions from the community, and the core team is more than happy to help new contributors ramp up and familiarize themselves with Uno Platform's codebase.

### Diving into the code

The [contributor's guide](contributing-intro.md) has plenty of resources to help you get up and running with Uno's code, including a [guide to building and debugging Uno.UI](debugging-uno-ui.md), and a [guide to Uno's internals](uno-internals-overview.md).

### Finding an issue to work on

Not sure what to work on? Take a look through the currently open [good first issues](https://github.com/unoplatform/Uno/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - these are all issues that have been identified by the core team as suitable for new contributors, with a well-defined scope and a relatively gentle learning curve.

Maybe you have something in mind to work on already. That's great! Make sure there's an [opened issue](https://github.com/unoplatform/Uno/issues) for it, either by creating it yourself or searching for an existing report, as described above.

In either case, once you're ready, leave a comment on the issue indicating that you'd like to work on it. A member of the core team will assign the issue to you, so as to make sure no one inadvertently duplicates your work (and you're not duplicating someone else's).

### Getting down to work

The [contributor's guide](contributing-intro.md) has the information you need. The most important points are:

- Work in [your own fork of Uno](https://help.github.com/en/github/getting-started-with-github/fork-a-repo)
- Be sure to use the [Conventional Commits format](git-conventional-commits.md)
- Once you're done, you'll probably need to [add a test](../contributing/guidelines/creating-tests.md)

### Creating a PR

Once you're ready to create a PR, check out the [Guidelines for pull requests](../contributing/guidelines/pull-requests.md) in Uno.

### Need help?

If there's anything you need, [ping us on our Discord Server](https://platform.uno/discord).

## Sponsors & Grants

Please consider sponsoring Uno Platform development, especially if your company benefits from this library.

Your contribution will go towards adding new features and closing issues raised by the community at Uno Platform backlog on GitHub ([Issues · unoplatform/uno (github.com)](https://github.com/unoplatform/uno/issues)) and making sure all functionality continues to meet our high-quality standards.

A grant for continuous full-time development has the biggest impact on progress. Periods of 2 to 5 days allow a contributor to tackle substantial complex issues that are otherwise left to linger until somebody can’t afford to not fix them.

Contact [@jlaban](https://github.com/jeromelaban) or [@sasakrsmanovic](https://github.com/sasakrsmanovic) to arrange a grant to Uno Platform and its core contributors.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/web-authentication-broker.md

---
uid: Uno.Features.WAB
---

# Web Authentication Broker

* The timeout is set by default to 5 minutes. You can change it using `WinRTFeatureConfiguration.WebAuthenticationBroker.AuthenticationTimeout`.

## Usage on WebAssembly

* The *redirect URI* **MUST** be with the origin (protocol + hostname + port) of the application. It is not possible to use a custom scheme URI.
* When using the `<iframe>` mode (see *advanced usages* below), the server must allow for using CSP (Content Security Policy).
* Default *redirect URI* is `<origin>/authentication-callback`. For example `http://localhost:5000/authentication-callback`.
* It is not possible for applications to clear cookies for the authentication server when this one is from another origin. The only way clear cookies is to deploy the app and the authentication server on the same site (sharing the same origin).
* You can change the size and the initial title of the open window by setting corresponding settings in `WinRTFeatureConfiguration.WebAuthenticationBroker` .

## Usage on iOS & macOS

* The *redirect URI* **MUST** use a custom scheme URI and this scheme must be registered in the `Info.plist` of the application.
* Default *redirect URI* will be `<scheme>:/authentication-callback`. Ex: `my-app-auth:/authentication-callback`
* The default *redirect URI* will be automatic if there's only one custom scheme defined in the application. If there are more than one scheme, the first one will be used. You may want to set the right one using the `WinRTFeatureConfiguration.WebAuthenticationBroker.DefaultReturnUri` property.

## Usage on Android

* The *redirect URI* **MUST** use a custom scheme URI. This one will launch a special *Activity* declared in the application.

* You **MUST** declare an activity inheriting from `WebAuthenticationBrokerActivityBase` in the Android head. Note the `[Activity]` attribute needs to include `Exported = true` if you are targeting Android 12.

  ```csharp
  // Android: add this class near the MainActivity, in the head project
  [Activity(NoHistory = true, LaunchMode = LaunchMode.SingleTop, Exported = true)]
  [IntentFilter(
      new[] {Android.Content.Intent.ActionView},
      Categories = new[] {Android.Content.Intent.CategoryDefault, Android.Content.Intent.CategoryBrowsable},
      // To be changed for a scheme specific to the application
      DataScheme = "myapplication")]
  public class WebAuthenticationBrokerActivity : WebAuthenticationBrokerActivityBase
  {
      // Note: the name of this class is not important
  }
  ```

* To use the automatic discovery of the *redirect URI*, it is required to set the `IntentFilter` using the attributes like in the previous point. If you put it in the manifest, you'll need to set the URI using the `WinRTFeatureConfiguration.WebAuthenticationBroker.DefaultReturnUri` property.

* Default *redirect URI* will be `<scheme>:/authentication-callback`. Ex: `my-app-auth:/authentication-callback`

* The default implementation of the `WebAuthenticationBroker` on Android will launch the system browser and the result will come back through the custom scheme of the *Return Uri*. The *AndroidX Chrome Custom Tabs* may also be used. *Advanced* section below contains instructions about this.

## Advanced Usages

### Custom Implementation

For special needs, it is possible to create a custom implementation of the Web Authentication Broker by using the `[ApiExtension]` mechanism of Uno and implementing the `IWebAuthenticationBrokerProvider` interface:

```csharp
[assembly: ApiExtension(typeof(MyNameSpace.MyBrokerImplementation), typeof(Uno.AuthenticationBroker.IWebAuthenticationBrokerProvider))]

public class MyBrokerImplementation : Uno.AuthenticationBroker.IWebAuthenticationBrokerProvider
{
    Uri GetCurrentApplicationCallbackUri() => [TODO]

    Task<WebAuthenticationResult> AuthenticateAsync(WebAuthenticationOptions options, Uri requestUri, Uri callbackUri, CancellationToken ct)
    {
        [TODO]
    }
}
```

This implementation can also published as a NuGet package and it will be discovered automatically by the Uno tooling during compilation.

### WebAssembly: How to use `<iframe>` instead of a browser window

On WebAssembly, it is possible to use an in-application `<iframe>` instead of opening a new window. Beware **the authentication server must support this mode**.

1. Create an `<iframe>` control:

   ```csharp
   [HtmlElement("iframe")]
   public class LoginIFrame : Control
   {
       public LoginIFrame()
       {
           // A background is required to allow interactions
           // with the control
           Background = new SolidColorBrush(Colors.Transparent);
       }
   }
   ```

2. Use the `LoginIFrame` control in the page:

   ```xml
   <Page ...>
       <Grid>
           [...]
           <controls:LoginIFrame x:name="loginWebView" />
       </Grid>
   </Page>
   ```

3. Set the `HtmlId` before calling the `WebAuthenticationBroker`:

   ```csharp
   private async void LoginHidden_Click(object sender, RoutedEventArgs e)
   {
       // Set configuration to use the control as the iframe control
       WinRTFeatureConfiguration.WebAuthenticationBroker.IFrameHtmlId = loginWebView.GetHtmlId();
       try
       {
           var userResult = await WebAuthenticationBroker.AuthenticateAsync(WebAuthenticationOptions.None, _startUri);
           [...]
       }
       finally
       {
           // Don't forget to reset it when finished
           WinRTFeatureConfiguration.WebAuthenticationBroker.IFrameHtmlId = null;
       }
   }
   ```

NOTES:

* The IFrame control should be present in the visual tree or the user won't see it.
* If you want to use a *silent* `<iframe>`, you don't need to create a control, you can simply use the `WebAuthenticationOptions.SilentMode` as the first parameter to `WebAuthenticationBroker.AuthenticateAsync()`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/concepts/overview/why-uno-platform.md

---
uid: Uno.Overview.WhyUno
---

# Why use Uno Platform for your project?

Thank you for considering Uno Platform for your next project. While we always recommend trying out any stack before deciding on your next project, here are some tips you can use for your in-depth evaluation.

## It's a platform, not just a UI framework

Uno Platform is a developer productivity **platform** and much **more than a UI framework**, for building single codebase, native, mobile, web, desktop, and embedded apps with .NET.

At the core is a cross-platform .NET UI framework, that allows apps to run everywhere with a single codebase.

However, built on top of this foundation is also a rich platform which includes libraries, extensions, and tools that accelerate the design, development, and testing of cross-platform applications.

## Uno Platform Studio - Productivity Tools That Set Us Apart

**[Uno Platform Studio](xref:Uno.Platform.Studio.Overview)** revolutionizes how developers design, build, and iterate on cross-platform applications. This comprehensive suite of productivity tools is a key differentiator that sets Uno Platform apart from other alternatives.

### Hot Design® - The Industry's First Visual Designer for Cross-Platform .NET

**[Hot Design](xref:Uno.HotDesign.Overview)** is the industry's first runtime visual designer for cross-platform .NET applications. It transforms your running app into a designer from any IDE on any OS, offering unprecedented productivity gains. Hot Design provides true WYSIWYG design capabilities at runtime across all platforms.

### Hot Design® Agent - AI-Powered UX/UI Creation

**[Hot Design Agent](xref:Uno.HotDesign.Agent)** is an AI tooling assistant that builds your UI while the app is running. It works with data contexts and live previews to help developers design and interact with user interfaces in real time.

### MCP - AI-Powered Development Intelligence

**[Uno MCP](xref:Uno.Features.Uno.MCPs)** leverages semantic understanding to grasp your intent and deliver precise, context-aware answers. It provides instant, accurate guidance grounded in official Uno Platform documentation directly from your IDE.

### App MCP - Agent Control for Running Applications

**App MCP** allows AI agents to control the running app using pointer and keyboard interactions along with visual tree queries. It enables AI agents from Visual Studio, VS Code, Claude Code, GitHub Copilot CLI, Codex, and more to interact with your application.

## True Single Project across Mobile, Web, Desktop, and Embedded

Our Single Project approach is .NET ecosystem’s first and only true Single Project solution, empowering developers with a unified approach, spanning mobile, web, desktop, and embedded apps. This genuine Single Project approach simplifies development, accelerates build times, and facilitates platform-specific development, enhancing your productivity and efficiency.

## It's Free and Open-Source

Uno Platform is free and open source under Apache 2.0.

It is well funded and has a [sustainability model](https://platform.uno/blog/sustaining-the-open-source-uno-platform/) built in so that the project is sustainable in the long term. In addition, it is fueled by support from a thriving community of users who regularly send feedback and contribute.

## Why Choose Uno Platform Over Alternatives?

### Broader Platform Support

Uno Platform supports WebAssembly, enabling your .NET apps to run natively in browsers alongside mobile and desktop platforms. Uno Platform delivers true cross-platform reach including web deployment without additional frameworks.

### Rich Tooling

Uno Platform leverages the mature .NET ecosystem with Visual Studio, VS Code, and Rider support. With **Uno Platform Studio**, you get industry-leading tools like Hot Design®, Hot Design® Agent, and AI-powered development assistance through Uno MCP, providing a wide range of powerful capabilities.

### Pixel-Perfect Control with Multiple Rendering Options

Uno Platform offers both native and Skia-based rendering approaches, giving you flexibility other frameworks lack. You can choose native platform controls for maximum OS integration or Skia rendering for guaranteed pixel-perfect consistency across all platforms—or mix both approaches based on your needs.

## A single codebase that runs everywhere natively

Uno Platform apps run as a single codebase for native mobile, web, desktop, and embedded apps, utilizing the full breadth and reach of .NET. Uno Platform ships its releases in lock step with the latest .NET releases, including support for .NET 9 and .NET 10. You can always benefit from the latest and greatest advancements in the .NET world.

## Keep using your favorite IDE

Need we say more? Use the IDE that works for you – Visual Studio, VS Code, Rider as well as GitHub Codespaces. Wherever you are, Uno Platform is with you.

## Work from your favorite OS

Remain on the operating system that you are on. A detailed list of target platforms for which you can develop from Windows, macOS, or Linux is available. Our docs are designed to be OS agnostic, so every tutorial step works regardless of the system you develop on.

## Use either XAML or C# Markup for your app UI

With Uno Platform, you have a choice of building polished cross-platform UI with concise declarative UI markup using a modern XAML-centric syntax or declarative-style C# Markup. Both approaches are supported right out of the box. Our C# Markup approach works with both 1st party and 3rd party controls and application-level libraries, mapping directly to the underlying object model. All thanks to real-time C# source generators doing the heavy lifting for you.

## Hot Reload that just works

Our Hot Reload offers the most comprehensive solution for fast development loop – make a change and see it live everywhere is running in real-time without recompiling. Uno Platform Hot Reload works on:

- Visual Studio and Visual Studio Code
- All target platforms
- XAML, C# Markup, and C#
- Bindings & x:Bind, Resources, Data Templates, and Styles
- 1st party or 3rd party controls
- Devices and Emulators

For more information, see [Hot Reload](xref:Uno.Features.HotReload).

## Stop typing markup and use Figma code generation

Design handoff is one of the biggest time traps, as design envisioned by the designer needs to be manually translated to markup. With our [Figma plugin](xref:Uno.Figma.GetStarted)\*, this process is automatic, and the result is well-structured, performant XAML or C#. Uno Platform's Design-to-Code feature is part of **Uno Platform Studio**, providing enterprise-grade design handoff capabilities.

For more information, see [Design and Build Uno Platform Applications with Figma](xref:Uno.Figma.Overview.GetStarted).

\*_Note this plugin is optional_

## Quickly create a project using the Templates Wizard

Our [Uno Platform Template Wizard](https://platform.uno/blog/the-new-uno-platform-solution-template-wizard/) and its [live version](https://new.platform.uno/) allow you to get to a working project quickly. You can select your preferred version of .NET, choose the target platforms you want to develop for, pick a design system that suits your app the best, pick from the MVVM or MVUX architectural pattern, and throw in any mix of the rich set of Uno Extensions as starting building blocks. Additionally, you can include support for PWA, first-party API server, UI tests, and even generate initial build scripts for GitHub Actions or Azure DevOps, alleviating the hassle of figuring out the complex, cross-platform YAML specifics.

## Your apps will be pixel-perfect across all platforms

Uno Platform allows you to control each pixel of your UI elements to match the experience you envision. This concept of lookless-controls is very similar to what is named "[headless controls](https://martinfowler.com/articles/headless-component.html)" in the React world. Each built-in and third-party control defines its fundamental logic (e.g. how it responds to interactions, handles data, or behaves once a property value is set) independently of a visual style and template. This approach means you can tailor the appearance of any control to fit a special use case, or to match your brand identity. Changes to control styling can even be performed at runtime. Uno Platform leverages this to offer multiple built-in design systems influenced by guidance from popular platforms.

Under the hood, your app can use either a Native or Skia-based approach for rendering.

The Native rendering approach uses the built-in native UI primitives on each target, for iOS, Android, and WebAssembly. These build up a native view hierarchy and draw the visuals using native OS capabilities. That way, you still get all the benefits of the native world, such as localization and accessibility, but without giving up the rich control of pixel-level details in your app experience.

The [Skia-based](xref:uno.features.renderer.skia) rendering approach uses a Skia-based canvas for fast and rich rendering across platforms and gets the exact same behavior across all platforms. You can also use the Composition API to get advanced rendering and animations across platforms.

All of the above remains possible without needing to replicate the same design for each target platform.

## Multiple design systems included with support for dark mode

Uno Platform controls come pre-built with the Fluent design system, so your app looks the same across all platforms. The [Uno Themes](xref:Uno.Themes.Overview) library is available to provide alternative styles for your controls and help with adapting them to the other design systems Material Design or Cupertino. All three design implementations take advantage of [theme resources](https://learn.microsoft.com/windows/apps/design/style/xaml-theme-resources), enabling out-of-the-box support for light and dark color modes.

## Move forward gradually with Uno Islands

We recognize that many developers have existing WPF applications they want to modernize, and offer such a path via [Uno Islands](xref:Uno.Tutorials.UnoIslands), which allows you to host modern Uno Platform content within WPF UI. This means you can start modernizing your application and bringing it cross-platform step by step, not just all at once!

The _islands_ of hosted content enable any app to take advantage of modern WinUI controls, but preserve compatibility with its existing WPF experience. For example, an app using the list-details pattern can keep its robust, WPF-built details view while upgrading the list control to a WinUI `ListView`. Support for DataBinding between both contexts allows a seamless transition between the two.

## Native performance, never stuck

Uno Platform-built apps are **native apps**. As a developer, you can take advantage of each platform's capabilities and features while enjoying the flexibility to adapt and optimize as needed.

Uno Platform provides access to the **original APIs** provided by the target platform, both for UI and non-UI functionalities. You will be able to use the UI controls that come directly from the respective target platform's native SDK. This ensures that your app seamlessly incorporates the _familiar_ look and feel of the platform it's running on.

This versatility allows for a broader reach with compatibility across all supported platforms and devices.

Uno Platform provides "escape hatches" when needed. This means that you have the flexibility to utilize platform-specific features or optimizations when required, should that functionality not be provided by Uno Platform itself.

Uno Platform simply reuses default behaviors that come from the respective platform itself. This includes features like Input Method Editor (IME), spell checking, password manager integration, autofill, magnifier features (long press on textbox), accessibility features, voice-over, support for TTY (Teletypewriter) and native back swipe gestures.

The resulting app provides a consistent, native user experience your end-users expect.

## Breadth of UI controls – over 500 controls available

Uno Platform gives you automatic access to all controls coming from Microsoft and its 3rd party ecosystem. All controls from WinUI, Windows Community Toolkit, or open-source projects developed for WinUI 2/3 or UWP will work with Uno Platform.

## Controls from Windows Community Toolkit (WCT)

The Windows Community Toolkit (WCT) is a collection of helper functions, controls, and services designed to simplify and enhance Windows app development for developers. You can take those WCT features such as the `DataGrid` or `Expander` controls cross-platform when your project uses Uno Platform.

## More UI controls with MAUI Embedding

Uno Platform allows for embedding .NET MAUI-specific controls from all leading 3rd party vendors like Syncfusion, Grial Kit, Telerik, DevExpress, Esri, Grape City, and the .NET MAUI Community Toolkit. Keep in mind that this cross-platform approach works only for target platforms .NET MAUI reaches – iOS, Android, macOS, and Windows. [We have 6 sample apps](xref:Uno.Extensions.Maui.Overview) showing how to work with MAUI embedding by all leading 3rd party vendors.

> [!NOTE]
> Uno Platform is not built on top of .NET MAUI.

## Uno Toolkit

In addition to hundreds of UI controls available from 3rd party UI vendors as described above, we offer our own set of [higher-level UI Controls](https://platform.uno/uno-toolkit/) designed specifically for multi-platform, responsive applications.

## Consistent shadow effect everywhere

Displaying consistent shadows in cross-platform apps was always a problem. We are confident that we have solved it! Our [ShadowContainer control](xref:Toolkit.Controls.ShadowContainer) will allow you to easily display highly customizable inner and outer shadows in your apps. And if you fancy [neumorphism](xref:Toolkit.Controls.ShadowContainer#neumorphism) depth effects, we have control styles for that too!

## Maps

Uno Platform offers charting components via integration with [Maps UI](https://github.com/Mapsui/Mapsui) (Open Source) on all targets.

Also, for targeting just mobile, you can use [Esri ArcGIS Maps SDK for .NET](xref:Uno.Extensions.Maui.ThirdParty.EsriMaps) via our .NET MAUI embedding feature.

In addition, we are looking into integrating the new WinUI [MapControl](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.mapcontrol?view=windows-app-sdk-1.5) into our core offering.

## Charts

Uno Platform offers charting components via integration with [Live Charts](https://livecharts.dev/) (Open Source) and OxyPlot on all targets.

## DataGrid

Uno Platform offers DataGrid control via our support for Windows Community Toolkit (WCT). You can see the DataGrid implemented by going to [nuget.info](https://nuget.info/), which is the web implementation of the popular NuGet Package Explorer. Furthermore, you can see an implementation of it at [Uno Gallery](https://gallery.platform.uno/), then navigating to "Windows Community Toolkit" tab. Do note that you have options to [performance-tune your Uno Platform web apps](https://platform.uno/blog/optimizing-uno-platform-webassembly-applications-for-peak-performance/).

We will support Windows Community Toolkit [DataTable](https://github.com/CommunityToolkit/Labs-Windows/discussions/415) once it reaches RTM.

## Non-UI APIs

It is a common misconception that Uno Platform is just a UI framework. Nothing could be further from the truth, however! Uno Platform comes with [many non-UI APIs built in](xref:Uno.Features.Accelerometer) – ranging from various ways to retrieve device-related information, through access to user and application preferences, all the way to a range of sensors including GPS, compass, or even Accelerometer! All these APIs are fully cross-platform, so you just write once and run everywhere. For those who have a musical instrument, we even have MIDI!

How's _that_ for music to your ears?

## Our set of extensions for common app needs

[Uno.Extensions](https://platform.uno/uno-extensions/) is built on top of **Microsoft.Extensions** to setup and create a host for your application. The host allows access to a multitude of services for many app features including Configuration, Logging, Serialization, and HTTP. You can even register your own custom services using the same pattern.

## Navigation

As part of Uno.Extensions, Navigation provides a consistent abstraction for navigating within an application. Whether it is navigating to a new page, switching tabs, or opening a dialog, navigation can be initiated from code-behind, XAML, or from within a ViewModel.

## Authentication

Uno.Extensions Authentication is a provider-based authentication service that can be used to authenticate users of an application. It has built-in support for Microsoft Entra ID (formerly Azure AD), OpenIDConnect, Web, and Custom.

## Skia drawing

The Uno Platform provides access to SkiaSharp as a render canvas for your app, enabling rich support for fine-grained drawing primitives. Uno Platform also uses SkiaSharp to render the UI for X11, FrameBuffer, macOS, and Windows 7+ apps. Starting from Uno Platform 6.0, Skia rendering is also available for iOS, Android, and WebAssembly.

## Animations: Beyond storyboards, access to Lottie and Rive

Based on SkiaSharp support, Uno Platform provides AnimatedVisualPlayer to give the ability to render rich [Lottie files](https://airbnb.io/lottie/#/) directly in your app, for all target platforms.

## Performance and app size with AOT/Jiterpreter

Uno Platform allows you to use .NET 9+ features such as Profiled AOT (Ahead Of Time compilation) and the Jiterpreter, to get better performance for your apps with balanced size. Profiled AOT is a powerful feature that allows you to continue using the interpreter for code that is not often used, thus keeping your app's size down while maintaining excellent performance.

## Comprehensive App Packaging for All Platforms

Uno Platform offers comprehensive [app packaging solutions](xref:uno.publishing.overview), allowing you to build, package, and deploy your applications with ease across all supported platforms. Whether you're targeting mobile app stores, desktop environments, or web hosting, our built-in packaging support streamlines your release process. The platform handles all the platform-specific packaging requirements, enabling you to focus on your application logic instead of deployment complexities.

## Accessibility included

Uno Platform comes with built-in support for accessible apps, such as font scaling and support for screen readers. Support is provided for Windows Narrator, Android TalkBack, Apple VoiceOver, and browser-specific narrators when targeting the web. In addition, Uno Platform provides programmatic access to most UI elements, enabling assistive technology products.

## Localization included

Uno Platform supports localization from the `x:Uid` feature in XAML, as well as using resource files from `ResourceManager` in plain C# code. Localization is done once for all your target platforms.

## XAML and Resources Trimming

[XAML and Resources Trimming](xref:Uno.Features.ResourcesTrimming) is a feature that allows for trimming the size of WebAssembly, Desktop and iOS apps down by removing XAML styles and  that are not used in your app, helping to bring down the size of your application.

## Lightweight styling

Lightweight styling is a way to customize the appearance of XAML controls by overriding their default brushes, fonts, and numeric properties. Lightweight styles are changed by providing alternate resources with the same key. All Uno Material styles support the capability to be customized through resource overrides without the need to redefine the style.

Overriding resources from Uno Material can be done at the app, page, or even control level.

## Easily manage and scale image assets

[Resizetizer](xref:Uno.Resizetizer.GettingStarted) is a set of MSBuild tasks designed to manage an application's assets. With this package, there is no need to worry about creating and maintaining various image sizes or setting up a splash screen. Simply provide an SVG file, and the tool will handle everything else.

## Support for SVG

Today's apps run on such a wide range of displays, it is sometimes hard to make sure your icons always look crisp and sharp. To counter this, Uno Platform has a built-in support for the vector-based SVG format!

## Progressive Web Apps (PWAs)

Your Uno Platform WebAssembly app can run as a Progressive Web App. This means users can install it and run as a normal application on their device. In addition, this gives you even more customization options and additional PWA-specific APIs like badge notifications. You can install the [NuGet Package Explorer](https://nuget.info/) PWA like a local app!

## WebView across platforms

When you need to display web content within your cross-platform apps, you can use our `WebView2` control across all Uno Platform targets, at no additional cost. Not only will it easily handle rendering of both remote and in-app HTML content, but it will also allow you to implement bi-directional JavaScript communication without any hassle. We are working on an implementation for the remaining Skia targets.

## Media Player across platforms

Uno Platform provides - at no additional cost - the `MediaPlayerElement` control, which allows your app to play media files back in your app. It is supported on Linux through libVLC.

## Monaco Editor on WebAssembly

For all your in-app text and code editing needs, you can use our port of the Monaco Editor – the same one that is used by Visual Studio Code. With full support for syntax highlighting, you could even build your own WebAssembly IDE!

## Mix and match XAML controls with native components

Because Uno Platform apps are native mobile apps, you can embed any native control on a per platform basis into an Uno Platform app.

Uno Platform views inherit from the base native view defined in .NET binding or the native framework itself, you can incorporate native views into your app's visual tree. For more information, see [UnoConf 2021 - Using Native Controls in Uno Platform Apps](https://www.youtube.com/watch?v=4Cwzk8dDHs0).

Your app's powerful visual tree can also render native components through embedding in Skia targets.

## Choice of presentation framework

With Uno Platform, you get a choice of your favorite presentation framework – MVVM, Prism, or Uno Platform in-box MVUX/Reactive.

## Support for SQLite

Uno Platform supports SQLite for all platforms, including WebAssembly, to allow for your app to use offline or local caching techniques.

## Proven migration path for Xamarin.Forms

In addition to providing 3rd party control MAUI Embedding, Uno Platform is a proven modernization path for Xamarin.Forms apps. We've collated numerous [docs](https://platform.uno/xamarin.forms) to aid you in the migration. Big brands such as **TOYOTA** have already migrated some of their apps to Uno Platform.

> [!NOTE]
> Uno Platform is not built on top of .NET MAUI.

Watch TOYOTA's [video testimonial](https://youtu.be/TeA6zEq5MGk?t=1449).

## Standing on the shoulders of giants

Uno Platform was designed to be source compatible with the APIs of WinUI. This gives us the great advantage of being able to port existing code for even the most complex controls directly from Microsoft, preserving all their feature richness. And, because WinUI sources are now publicly available, everyone from the community can help!

## Developed by App Builders, for App Builders

We are first and foremost app builders who have built hundreds of applications for consumer brands via our sister company – nventive. We use our platform and tooling daily (dog fooding) and understand the pains of app development first-hand.

## Used to build countless apps for over a decade

Uno Platform started as an internal project at Nventive over 10 years ago, which we have used to develop [countless apps for top worldwide-recognized brands](https://nventive.com/en/our-work). In addition, many Fortune 500 companies use Uno Platform for their internal, line of business applications. Some of those can be found on the [Uno Platform case studies](https://platform.uno/case-studies/) page. This production-proven track record demonstrates that Uno Platform is not just experimental—it's enterprise-ready and battle-tested at scale.

## Support: Community and Paid

We are well known for a friendly and welcoming community which is always willing to help. If you need support time directly from the core team, there are also paid plans available which is how we sustain Uno Platform, a process explained in the [Sustaining the Open-Source Uno Platform blog post](https://platform.uno/blog/sustaining-the-open-source-uno-platform/).

To see your free & paid support options, see our official [support page](https://platform.uno/support/).

## Workshops

Getting started is easy with our workshops that will give you all the necessary intro into cross-platform app development. And the fact that we have multiple workshops means you can pick and choose based on the time you have available and the level of difficulty! Give our [Simple Calculator](https://platform.uno/simple-calc/) or [Tube Player](https://platform.uno/tube-player/) workshop a go.

## Books/Content

XAML for UI is a mature & well documented technology – you'll always find an example suiting your needs. In addition, there are [dozens of training courses and books](https://platform.uno/blog/uno-platform-learning-resources-2023-update/) written to help you learn Uno Platform.

## Fast ship cadence

Uno Platform ships official releases 6-8 times per year, and dozens of dev builds in between. This flexibility has traditionally allowed us to ship on day-0 alongside .NET, WinUI, and Windows App SDK.

## Amazing team behind it

As Uno Platform grows, the team behind it grows as well. The product is in good hands, with a group of focused and highly motivated experts in many areas. The project thrives because of this, as new features and improvements are added daily.

## Integrates with any .NET Library

In addition to the UI components mentioned above, Uno Platform apps also integrate perfectly with your existing .NET libraries. This includes both .NET Standard 2.0 and libraries targeting .NET 6 through .NET 10 and beyond. Because of this, your Uno Platform app has compatibility with packages like Json.NET, LiteDB, SQLite, SkiaSharp, and the vast NuGet ecosystem.

## The Community

Welcoming, tight, and helpful community on GitHub Discussions and Discord, with over 300 contributors to the project. Popular with over 70,000,000 NuGet downloads of its various packages and is used among the [biggest companies](https://platform.uno/case-studies/), including Fortune 500 enterprises. Our core team is always ready to help, and the community provides excellent support for developers at all skill levels.

## Wealth of Samples

To show Uno Platform's versatility, we tinker around with technology and share with you our full-blown apps and code samples that you can learn from.

Check out: [Cross-Platform Sample Apps with XAML and C# - Uno Platform](https://platform.uno/code-samples/)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/winapp-sdk-specifics.md

---
uid: Uno.Features.WinAppSDK
---

# Specific considerations for WinAppSDK

## Adjusting Windows SDK References

When building a WinUI3 app, you may encounter the following error message:

```output
error NETSDK1148: A referenced assembly was compiled using a newer version of Microsoft.Windows.SDK.NET.dll. Please update to a newer .NET SDK in order to reference this assembly.
```

This indicates that your application, or current .NET SDK is using a version of the Windows .NET SDK which is lower than the SDKs used to compile any of your projects dependent nuget packages.

To fix this, find or add the following block in your Windows `.csproj` file:

```xml
<ItemGroup>
    <!--
    If you encounter this error message:

        error NETSDK1148: A referenced assembly was compiled using a newer version of Microsoft.Windows.SDK.NET.dll. Please update to a newer .NET SDK in order to reference this assembly.

    This means that the two packages below must be aligned with the "build" version number of
    the "Microsoft.Windows.SDK.BuildTools" package above, and the "revision" version number
    must be the highest found in https://www.nuget.org/packages/Microsoft.Windows.SDK.NET.Ref.
    -->

    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" RuntimeFrameworkVersion="10.0.22000.25" />
    <FrameworkReference Update="Microsoft.Windows.SDK.NET.Ref" TargetingPackVersion="10.0.22000.25" />
</ItemGroup>
```

To find the appropriate version:

- The two `FrameworkReference` packages must be aligned with the "build" version number (`22000` in the example above) of the "Microsoft.Windows.SDK.BuildTools" package defined earlier in the project
- The "revision" version number (`25` in the example above) must be the highest found in the versions of https://www.nuget.org/packages/Microsoft.Windows.SDK.NET.Ref.

## Un-packaged application support

By default the **Uno Platform App** Visual Studio template creates a packaged application. If you want to add un-packaged support, you'll need to do the following:

- Add a new entry in the launchSettings.json file:

    ```json
    {
        "profiles": {
            "UnoWinUIQuickStart.Windows (Package)": {
                "commandName": "MsixPackage"
            },
            "UnoWinUIQuickStart.Windows (Unpackaged)": {
                "commandName": "Project"
            }
        }
    }
    ```

- Add this new set of properties in your `.Windows` csproj:

    ```xml
      <PropertyGroup>
        <!-- Bundles the WinAppSDK binaries (Uncomment for unpackaged builds) -->
        <WindowsAppSDKSelfContained>true</WindowsAppSDKSelfContained>
        <!-- This bundles the .NET Core libraries (Uncomment for packaged builds)  -->
        <!-- <SelfContained>true</SelfContained> -->
    </PropertyGroup>
    ```

    You will need to adjust which property is enabled based on the deployment target that you are choosing. Both properties are not supported (as of WinAppSDK 1.0.3).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-applicationmodel-calls.md

---
uid: Uno.Features.WAMCalls
---

# Phone calls

> [!TIP]
> This article covers Uno-specific information for `PhoneCallManager`. For a full description of the feature and instructions on using it, see [PhoneCallManager Class](https://learn.microsoft.com/uwp/api/windows.applicationmodel.calls.phonecallmanager).

* `Windows.ApplicationModel.Calls.PhoneCallManager` allows apps to present a phone call UI to the user to allow them to initiate a call.
* The current call state can be checked using `IsCallActive` and `IsCallIncoming` properties.
* `CallStateChanged` event is raised when a call is incoming, accepted or dropped.

## Supported features

| Feature                   | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|---------------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `ShowPhoneCallUI`         | ✔       | ✔       | ✔   | ✔          | ✖     | ✖            | ✖            |
| `ShowPhoneCallSettingsUI` | ✔       | ✔       | ✖   | ✖          | ✖     | ✖            | ✖            |
| `CallStateChanged`        | ✔       | ✔       | ✔   | ✖          | ✖     | ✖            | ✖            |
| `IsCallActive`            | ✔       | ✔       | ✔   | ✖          | ✖     | ✖            | ✖            |
| `IsCallActive`            | ✔       | ✔       | ✔   | ✖          | ✖     | ✖            | ✖            |

## Examples

### Show phone call UI

```csharp
PhoneCallManager.ShowPhoneCallUI("123456789", "Jon Doe");
```

### Observe phone call state

```csharp
PhoneCallManager.CallStateChanged += PhoneCallManager_CallStateChanged;

private void PhoneCallManager_CallStateChanged(object sender, object e)
{
    var isCallActive = PhoneCallManager.IsCallActive;
    var isCallIncoming = PhoneCallManager.IsCallIncoming;
}
```

## Limitations

For the `ShowPhoneCallUI` method, the second parameter (`displayName`) is not utilized on non-Windows targets - only the phone number is displayed to the user.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-applicationmodel-chat.md

---
uid: Uno.Features.WAMChat
---

# Chat

> [!TIP]
> This article covers Uno-specific information for the `Windows.ApplicationModel.Chat` namespace. For a full description of the feature and instructions on using it, see [Windows.ApplicationModel.Chat Namespace](https://learn.microsoft.com/uwp/api/windows.applicationmodel.chat).

* The `Windows.ApplicationModel.Chat` namespace provides classes for accessing and managing chat messages.

## `ChatMessageManager`

### Limitations

**macOS**
`ShowComposeSmsMessageAsync` method is implemented but due to limitations of iMessage `sms:` scheme implementation, it doesn't support multiple `Recipients` (will only use the first one).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-applicationmodel-contacts.md

---
uid: Uno.Features.WAMContacts
---

# Contacts

> [!TIP]
> This article covers Uno-specific information for the `Windows.ApplicationModel.Contacts` namespace. For a full description of the feature and instructions on using it, see [Windows.ApplicationModel.Contacts Namespace](https://learn.microsoft.com/uwp/api/windows.applicationmodel.contacts).

* The `Windows.ApplicationModel.Contacts.ContactPicker` namespace provides classes for picking contacts from the OS contact store.

## `ContactPicker`

The `ContactPicker` class allows picking contacts from the OS contact store.

To check whether the class is supported on the target platform, use `IsSupportedAsync()` method:

```csharp
if (await ContactPicker.IsSupportedAsync())
{
    // you can use ContactPicker
}
```

To pick contacts, call either the `PickContactAsync()` or `PickContactsAsync()` method. Uno Platform supports picking multiple contacts on Windows, iOS, WebAssembly, and Tizen. On Android, we currently support picking a single contact only (for simplicity, the `PickContactsAsync()` method can still be called, but will still let the user pick only a single contact).

### Platform-specific

#### Android

Your app must declare `android.permission.READ_CONTACTS` permission:

```csharp
[assembly: UsesPermission("android.permission.READ_CONTACTS")]
```

#### Tizen

Your app must declare `http://tizen.org/privilege/contact.read` and `http://tizen.org/privilege/appmanager.launch` permissions in the app manifest:

```xml
<privileges>
    <privilege>http://tizen.org/privilege/contact.read</privilege>
    <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
</privileges>
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-applicationmodel-datatransfer.md

---
uid: Uno.Features.WAMDataTransfer
---

# Sharing Content

The data transfer manager allows sharing content from your application using the OS sharing dialog. To check whether sharing is supported at runtime, use `IsSupported()` method:

```csharp
if (DataTransferManager.IsSupported())
{
    // Sharing is supported    
}
```

Currently, the following types of content can be shared:

| Type of content | Android | iOS | macOS | WASM | Tizen |
|-----------------|---------|-----|-------|------|-------|
| Text            | ✔       | ✔   | ✔     | ✔    | ✔     |
| Uri             | ✔       | ✔   | ✔     | ✔    | ✔     |
| File            | ✖       | ✖   | ✖     | ✖    | ✖     |

To set up the `DataTransferManager` use the following snippet:

```csharp
var dataTransferManager = DataTransferManager.GetForCurrentView();
dataTransferManager.DataRequested += DataRequested;
DataTransferManager.ShowShareUI();
```

Make sure to unregister the `DataRequested` event after finished sharing.

In the `DataRequested` method, you can set the data to be shared in the `DataRequestedEventArgs`:

```csharp
private void DataRequested(DataTransferManager sender, DataRequestedEventArgs args)
{        
    args.Request.Data.Properties.Title = "Sharing dialog title";
    args.Request.Data.Properties.Description = "Description";

    args.Request.Data.SetText("Text to share");
    args.Request.Data.SetWebLink(new Uri("https://platform.uno/"));
}
```

If you need to prepare the data asynchronously, you can use a deferral:

```csharp
private async void DataRequested(DataTransferManager sender, DataRequestedEventArgs args)
{        
    var deferral = args.Request.GetDeferral();

    args.Request.Data.Properties.Title = "Sharing dialog title";
    args.Request.Data.Properties.Description = "Description";

    var text = await SomeOperationAsync();
    args.Request.Data.SetText(text);
    
    deferral.Complete();
}
```

To control the location where the sharing dialog shows up on iOS and macOS, use the `ShowShareUI(ShareUIOptions)` overload. `ShareUIOptions.SelectionRect` denotes the area the user is interacting with and will be taken into account by the OS. On iOS, you can also specify `ShareUIOptions.Theme` to make the dialog dark/light based on your app's preference. On other Uno targets, these properties have no effect.

On Tizen, the `http://tizen.org/privilege/appmanager.launch` privilege must be declared in the application manifest to allow sharing.

```xml
<privileges>
    <privilege>http://tizen.org/privilege/appmanager.launch</privilege>
</privileges>
```

## Windows App SDK Usage

In the case of Windows App SDK, a different initialization approach is currently unfortunately required due to the multi-window capabilities of the framework. Please, follow the [official documentation](https://learn.microsoft.com/windows/apps/develop/ui-input/display-ui-objects#winui-3-with-c-also-wpfwinforms-with-net-6-or-later-1) and wrap the Windows-specific code in `#if WINDOWS` blocks.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-applicationmodel-email.md

---
uid: Uno.Features.WAMEmail
---

# E-mail

> [!TIP]
> This article covers Uno-specific information for the `Windows.ApplicationModel.Email` namespace. For a full description of the feature and instructions on using it, see [Windows.ApplicationModel.Email Namespace](https://learn.microsoft.com/uwp/api/windows.applicationmodel.email).

* The `Windows.ApplicationModel.Email` namespace provides classes for accessing and managing e-mail messages.

## `EmailManager`

The `ShowComposeNewEmailAsync` method is supported.

On Android, it lets the user choose the target e-mail application before composing the e-mail.

On iOS, it uses `MFMailComposeViewController` but falls back to `mailto:` in case user has not set up any e-mail account yet.

On other platforms, the `mailto:` URI is used to try to compose the e-mail. This uses the `Launcher` API to launch the URI, so works on all platforms where `Launcher` is supported.

E-mail attachments are not supported yet.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-applicationmodel.md

---
uid: Uno.Features.WAM
---

# Package Information

> [!TIP]
> This article covers Uno-specific information for ApplicationModel. For a full description of the feature and instructions on using it, see [Windows.ApplicationModel Namespace](https://learn.microsoft.com/uwp/api/windows.applicationmodel).

* The `Windows.ApplicationModel.PackageId` class allows retrieving information about the application package.

## `PackageId`

### Android

* Due to the fact that version strings can be arbitrary on Android, we first try to parse `PackageInfo.VersionName`, if it fails, we try to use `PackageInfo.LongVersionCode`, and if that fails (this is a `long` value while WinUI uses `ushort`), we fall back to default to avoid exceptions (1.0.0.0).
* `FamilyName` and `Name` properties have the same value as the `Publisher` and cannot be retrieved programmatically.
* `FullName` property ends with the value of `LongVersionCode`, similar to WinUI, where it contains the app version.

### iOS

* Version strings may potentially be arbitrary on iOS as well (such version string would fail validation only during App Store upload), so we first try to parse the user-facing `CFBundleShortVersionString`, if it fails, we try to use `CFBundleVersion` and if that fails, we fall back to default to avoid exceptions (1.0.0.0).
* `FamilyName` and `Name` properties have the same value as the `Publisher` cannot be retrieved programmatically.
* `FullName` property ends with the value of `CFBundleVersion`, similarly to WinUI, where it contains the app version.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-devices-enumeration.md

---
uid: Uno.Features.WDEnumeration
---

# Uno Support for Windows.Devices.Enumeration

Device enumeration is partially supported in Uno Platform. It currently supports enumerating the following device classes:

- MIDI input devices
- MIDI output devices

To enumerate devices of a given class, please use the respective `GetDeviceSelector()` method, for example: `MidiInPort.GetDeviceSelector()`.

## For contributors

To add support for a new device class, several steps are required:

1. Add the device class GUID to `Uno.Devices.Enumeration.Internal.DeviceClassGuids`. You can discover the GUID by reading the `GetDeviceSelector` methods output.
2. Add provider implementations to `Uno.UWP\Devices\Enumeration\Internal\Providers`. The providers must implement `IDeviceClassProvider`.
3. Add the provider classes to `DeviceInformation.providers` partial classes in `Uno.UWP\Devices\Enumeration`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-devices-geolocation.md

---
uid: Uno.Features.WDGeolocation
---

# Geolocation

> [!TIP]
> This article covers Uno-specific information for Geolocation. For a full description of the feature and instructions on using it, see [Windows.Devices.Geolocation Namespace](https://learn.microsoft.com/uwp/api/windows.devices.geolocation)

* The `Windows.Devices.Geolocation.Geolocator` class provides APIs for getting the current location or tracking the device's location over time. Location information may come from estimating a position from beacons like Wi-Fi access points and cell towers, from the device's IP address, or may come from other sources such as a GNSS or GPS device.

## `Geolocator`

The following `Geolocator` APIs are implemented on Android, iOS, macOS, and WASM:

* `RequestAccessAsync`
* `GetGeolocationAsync`
* `PositionChanged`
* `StatusChanged`
* `DefaultGeoposition`
* `IsDefaultGeopositionRecommended`
* `LocationStatus`
* `DesiredAccuracy`
* `DesiredAccuracyInMeters`

### Platform-specific Requirements

#### Android

When using the `RequestAccessAsync` method on Android, you must configure one permission before using this API in your project. To do so, add the following to your `AndroidManifest.xml` file:

```xml
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" />
```

Additionally, when checking for this permission, ensure that `IsLocationEnabled` returns `true`; otherwise, the method will return `GeolocationAccessStatus.Denied`.

### Implementation notes

`StatusChanged` event is delivered to all `Geolocator` instances that have subscribers as a "broadcast". This is unusual, but in line with the WinUI implementation.

#### WASM

On WebAssembly, `RequestAccessAsync` requires querying for position info, which triggers the user permission dialog. For the developer, it should behave the same way as in WinUI. We recommend showing the user instructions on how to enable geolocation if it is `Denied` via a dialog message, for example, if you require the feature for the functionality of your app.

`GetGeolocationAsync` creates a single request for position. The parameterless version of the method works a bit differently from WinUI - the default timeout period is 60 seconds there, but in reality, the code never waits for so long, even if the user requests higher accuracy. Hence, the default timeout in the Uno Platform implementation is currently set to 10 seconds.

WebAssembly does not allow setting explicit meter-based accuracy for Geolocation and has only a standard and high level of accuracy. The high accuracy option is used when `DesiredAccuracy` is `High` or `DesiredAccuracyInMeters` is lower than 50. The `GetGeolocationAsync` implementation utilizes the set timeout period to try to improve the accuracy of the positioning. If better accuracy is not achieved, the last available result is used.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-devices-haptics.md

---
uid: Uno.Features.WDHaptics
---

# Haptics

> [!TIP]
> This article covers Uno-specific information for the `Windows.Devices.Haptics` namespace. For a full description of the feature and instructions on using it, see [Windows.Devices.Haptics Namespace](https://learn.microsoft.com/uwp/api/windows.devices.haptics).

* The `Windows.Devices.Haptics` namespace provides classes for accessing and managing vibration devices and haptic feedback.

## `VibrationDevice` class

The `GetDefaultAsync` method is implemented on all platforms and returns `null` for the unsupported platforms (Skia Desktop).

### Platform-specific requirements

#### Android

For Android, there is one permission you must configure before using this API in your project. To do that, add the following to `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.VIBRATE" />
```

#### Tizen

For Tizen, the `http://tizen.org/privilege/haptic` privilege needs to be declared in `tizen-manifest.xml` file.

## `SimpleHapticsController`

The `SupportedFeedback` property returns the list of supported feedback types for the given platform. In most cases this includes `Click` and `Press`.

The following code snippet illustrates the usage of `VibrationDevice` and `SimpleHapticsController`:

```csharp
var result = await VibrationDevice.RequestAccessAsync();
if (result == VibrationAccessStatus.Allowed)
{
    var vibrationDevice = await VibrationDevice.GetDefaultAsync();
    if (vibrationDevice != null)
    {
        var simpleHapticsController = vibrationDevice.SimpleHapticsController;
        var feedbackType = simpleHapticsController.SupportedFeedback.FirstOrDefault(
            feedback => feedback.Waveform == KnownSimpleHapticsControllerWaveforms.Press);
        if (feedbackType != null)
        {
            simpleHapticsController.SendHapticFeedback(feedbackType);
        }
    }
}
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-devices-midi.md

---
uid: Uno.Features.WDMidi
---

# MIDI

MIDI device input and output are supported across iOS, Android, macOS, and WebAssembly.

To see how to implement MIDI support in your application, you can follow the sample project provided in the [UWP samples repository](https://github.com/microsoft/Windows-universal-samples/tree/master/Samples/MIDI). This shows MIDI device enumeration, various forms of input as well as output.

In the case of **WebAssembly**, an additional security check is required to be able to receive/send system-exclusive MIDI messages. If you require this functionality, please set the `WinRTFeatureConfiguration.Midi.RequestSystemExclusiveAccess` flag early in the application lifecycle.

```csharp
#if __WASM__
WinRTFeatureConfiguration.Midi.RequestSystemExclusiveAccess = true;
#endif
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-media-capture.md

---
uid: Uno.Features.Capture
---

# Capture

> [!TIP]
> This article covers Uno-specific information for the `Windows.Media.Capture` namespace. For a full description of the feature and its instructions, see [Windows.Media.Capture Namespace](https://learn.microsoft.com/uwp/api/windows.media.capture).

The `Windows.Media.Capture` namespace provides classes for capturing photos, audio recordings, and videos.

## `CameraCaptureUI`

`CameraCaptureUI` is currently only supported on Android, iOS, and WinUI. On other platforms, `CaptureFileAsync` will return `null`.

> [!IMPORTANT]
> `CaptureFileAsync` should only be called from the UI thread. Calling them from a background thread will throw an `InvalidOperationException`.

### Platform-specific

#### Android

If you are planning to use the `CameraCaptureUI`, your app must declare `android.permission.CAMERA` and `android.permission.WRITE_EXTERNAL_STORAGE` permissions, otherwise the functionality will not work as expected:

```csharp
[assembly: UsesPermission("android.permission.CAMERA")]
[assembly: UsesPermission("android.permission.WRITE_EXTERNAL_STORAGE")]
```

#### iOS

On iOS, CameraCaptureUI uses the native `UIImagePickerController` to capture media. To request the necessary permissions, ensure that the `NSCameraUsageDescription` and `NSMicrophoneUsageDescription` keys are added to the `Info.plist` file.

> [!NOTE]
> The `NSMicrophoneUsageDescription` key is required only if you are capturing videos. If you are only capturing photos, you can omit this key.

```xml
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>NSCameraUsageDescription</key>
    <string>We need access to the camera to take photos.</string>
    <key>NSMicrophoneUsageDescription</key>
    <string>We need access to the microphone to record videos.</string>
</dict>
</plist>
```

> [!IMPORTANT]
> iOS simulators do not have access to a camera. To test the camera functionality, you need to run the app on a physical device. When using a simulator, your app will open the Photo Library instead of the camera, but the functionality will work as expected once the app is deployed to a physical device.

#### WinUI

On WinUI, `CameraCaptureUI` provides a unified interface for capturing photos and videos, fully leveraging the platform's APIs. WinUI support is coming with v1.7+.

### Example

```csharp
#if __ANDROID__ || __IOS__ || __WINDOWS__
using Windows.Media.Capture;
#endif

public async Task CapturePhotoAsync()
{
#if __ANDROID__ || __IOS__ || __WINDOWS__
    var captureUI = new CameraCaptureUI();
    captureUI.PhotoSettings.Format = CameraCaptureUIPhotoFormat.Jpeg;
    
    var file = await captureUI.CaptureFileAsync(CameraCaptureUIMode.Photo);

    if (file != null)
    {
        // Handle the captured file (e.g., save or display it)
    }
    else
    {
        // Handle the cancellation or error
    }
#endif
}
```

You can also check out our [sample](https://github.com/unoplatform/Uno.Samples/tree/master/UI/CameraCaptureUI) for more details.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-networking.md

---
uid: Uno.Features.WNetworking
---

# Networking

> [!TIP]
> This article provides specific information about Uno within the `Windows.Networking` namespace. For a comprehensive overview of the feature and guidance on how to use it, visit [Windows.Networking](https://learn.microsoft.com/uwp/api/windows.networking).

The `Windows.Networking` namespace offers classes to access and manage network connections within your app.

## NetworkInformation

The `Windows.Networking.Connectivity.NetworkInformation` class provides access to network connection information and allows you to monitor changes in network connectivity. For more details, refer to the official documentation: [NetworkInformation Class](https://learn.microsoft.com/uwp/api/windows.networking.connectivity.networkinformation).

### Supported features

| Feature                        | Windows | Android | iOS | Web (WASM) | macOS | Linux (Skia) | Win 7 (Skia) |
|--------------------------------|---------|---------|-----|------------|-------|--------------|--------------|
| `GetInternetConnectionProfile` | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |
| `NetworkStatusChanged`         | ✔       | ✔       | ✔   | ✔          | ✔     | ✔            | ✔            |

### Checking Network Connectivity in Uno

For more detailed guidance on network connectivity, watch our video tutorial:

> [!Video https://www.youtube-nocookie.com/embed/sK9IbkBAXIo]

### Platform-specific

#### Android

Android recognizes all values of the `NetworkConnectivityLevel` [enum](https://learn.microsoft.com/uwp/api/windows.networking.connectivity.networkconnectivitylevel). In contrast, iOS, macOS, and WASM only return either `None` or `InternetAccess`.

The `android.permission.ACCESS_NETWORK_STATE` permission is necessary and must be included in the application manifest or specified using the following attribute in the Android platform head:

```csharp
[assembly: UsesPermission("android.permission.ACCESS_NETWORK_STATE")]
```

#### iOS/macOS reachability host name

iOS and macOS use a 'ping' request to check internet connectivity. The default domain is `www.example.com`; however, you can change it to any other domain by setting the `WinRTFeatureConfiguration.NetworkInformation.ReachabilityHostname` property.

```csharp
WinRTFeatureConfiguration.NetworkInformation.ReachabilityHostname = "platform.uno";
```

### Example

#### Checking for internet connectivity

Use the snippet below to check internet connectivity levels in a cross-platform manner.

```csharp
using Windows.Networking.Connectivity;

var profile = NetworkInformation.GetInternetConnectionProfile();
var level = profile?.GetNetworkConnectivityLevel();
if (level is NetworkConnectivityLevel.InternetAccess)
{
    // Connected to the internet
}
```

#### Observing changes in connectivity

Use the following snippet to observe changes in connectivity:

```csharp
using Windows.Networking.Connectivity;

NetworkInformation.NetworkStatusChanged += NetworkInformation_NetworkStatusChanged;

private void NetworkInformation_NetworkStatusChanged(object sender)
{
    // read the current connectivity state/level
    var profile = NetworkInformation.GetInternetConnectionProfile();
    var level = profile?.GetNetworkConnectivityLevel();
}
```

#### Unsubscribing from the changes

```csharp
NetworkInformation.NetworkStatusChanged -= NetworkInformation_NetworkStatusChanged;
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-phone-devices-notification-vibrationdevice.md

---
uid: Uno.Features.WPDNotification
---

# Vibration

> [!TIP]
> This article covers Uno-specific information for the `Windows.Phone.Devices.Notification` namespace. For a full description of the feature and instructions on using it, see [Windows.Phone.Devices.Notification Namespace](https://learn.microsoft.com/uwp/api/windows.phone.devices.notification).

- The `Windows.Phone.Devices.Notification.VibrationDevice` allows for managing the vibration device on the phone.

## `VibrationDevice` class

### Platform-specific requirements

#### Android

For Android, there is one permission you must configure before using this API in your project. To do that, add the following to `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.VIBRATE" />
```

### Limitations

#### iOS

- The `Cancel` method is not supported.
- The parameter of the `Vibrate(TimeSpan)` method is not taken into account - iOS supports only a default vibration duration.

#### WinUI

- The `Windows.Phone.Devices.Notification` namespace is no longer supported in WinUI.
- Developers should use the [Windows.Devices.Haptics](xref:Uno.Features.WDHaptics) namespace for vibration functionality.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-storage-pickers.md

---
uid: Uno.Features.WSPickers
---

# File and Folder Pickers

> [!TIP]
> This article covers Uno-specific information for the `Windows.Storage.Pickers` namespace. For a full description of the feature and instructions on using it, see [Windows.Storage.Pickers Namespace](https://learn.microsoft.com/uwp/api/windows.storage.pickers).

* The `Windows.Storage.Pickers` namespace provides classes that allow the user to pick a folder or a file on the local file system so that the application can work with it.

![Android JumpList sample](../Assets/features/filepickers/fileopenpicker.png)

The following table shows which file picker experiences are available across Uno Platform targets. For detailed information, see the next sections.

Legend

* ✔  Supported
* 💬 Partially supported (see below for more details)
* ✖ Not supported

| Picker         | Windows App SDK   | WebAssembly | Android | iOS    | Desktop |
|----------------|-------|-------------|---------|--------|-------|
| FileOpenPicker | ✔    | ✔ (1)       | ✔      | ✔      | ✔    |
| FileSavePicker | ✔    | ✔ (1)       | ✔      | 💬 (2) | ✔    |
| FolderPicker   | ✔    | ✔           | ✔      | ✔      | ✔    |

*(1) - Multiple implementations supported - see WebAssembly section below*\
*(2) - See iOS section below*

On some platforms, you can further customize the file-picking experience by utilizing additional properties:

| Feature                 | Windows App SDK  | WebAssembly | Android | iOS   | Desktop |
|-------------------------|------|-------------|---------|-------|-----|
| SuggestedFileName       | ✔   | ✔           | ✖      | ✖     | ✔ |
| SuggestedStartLocation  | ✔   | ✔ (1)       | 💬 (4) | ✔ (3) | ✔ |
| SettingsIdentifier      | ✔   | ✔ (1)       | ✔      | ✖     | ✔ |
| SetMultipleFilesLimit   | ✖   | ✖           | ✖      | ✔     | ✖ |

*(1) - Only for the native file pickers - see WebAssembly section below*\
*(2) - For FileOpenPicker, VideosLibrary and PicturesLibrary are used to apply `image/*` and `video/*` filters*\
*(3) - PicturesLibrary opens the picture library with the image picker controller*\
*(4) - See Android section below*

On platforms where the additional features are not supported yet, setting them will not have any effect.

## Uno.WinUI-specific Initialization

If you are using Uno.WinUI (Windows App SDK-based form of Uno Platform), you need to make sure the pickers are initialized for the current window, otherwise the code would fail on Windows. This is done using `WinRT.Interop` and it is required for all file and folder pickers. For example, in the case of `FileOpenPicker`:

```csharp
var picker = new FileOpenPicker();

// ...

// Get the current window's HWND by passing a Window object
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(window);
// Associate the HWND with the file picker
WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd);

await picker.PickSingleFileAsync();
```

To get the `Window` instance in single-window apps, it is easiest to create an `internal static MainWindow` property in the `App.cs` or `App.xaml.cs` file, initialize it in `OnLaunched`, and then use it for this purpose:

```csharp
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
```

The latest Uno Platform app templates already contain such a `MainWindow` property, so you can use it out of the box.

## Examples

### FolderPicker

```csharp
var folderPicker = new FolderPicker();
folderPicker.SuggestedStartLocation = PickerLocationId.ComputerFolder;
folderPicker.FileTypeFilter.Add("*");

// For Uno.WinUI-based apps
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(folderPicker, hwnd);

StorageFolder pickedFolder = await folderPicker.PickSingleFolderAsync();
if (pickedFolder != null)
{
    // Folder was picked you can now use it
    var files = await pickedFolder.GetFilesAsync();
}
else
{
    // No folder was picked or the dialog was cancelled.
}
```

> [!NOTE]
> While the `SuggestedStartLocation` has currently no effect in Uno Platform targets, and `FileTypeFilter` has no effect for `FolderPicker`, they both must be set, otherwise the dialog crashes on WinUI.

### FileOpenPicker

#### Picking a single file

```csharp
var fileOpenPicker = new FileOpenPicker();
fileOpenPicker.SuggestedStartLocation = PickerLocationId.ComputerFolder;
fileOpenPicker.FileTypeFilter.Add(".txt");
fileOpenPicker.FileTypeFilter.Add(".csv");

// For Uno.WinUI-based apps
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(fileOpenPicker, hwnd);

StorageFile pickedFile = await fileOpenPicker.PickSingleFileAsync();
if (pickedFile != null)
{
    // File was picked, you can now use it
    var text = await FileIO.ReadTextAsync(pickedFile);
}
else
{
    // No file was picked or the dialog was cancelled.
}
```

> [!NOTE]
> While the `SuggestedStartLocation` has currently no effect on Uno Platform targets, it must be set, otherwise, the dialog crashes on WinUI. `FileTypes` must include at least one item. You can add extensions in the format `.extension`, with the exception of `*` (asterisk), which allows picking any type of file.

#### Picking multiple files

```csharp
var fileOpenPicker = new FileOpenPicker();
fileOpenPicker.SuggestedStartLocation = PickerLocationId.ComputerFolder;
fileOpenPicker.FileTypeFilter.Add(".jpg");
fileOpenPicker.FileTypeFilter.Add(".png");

// For Uno.WinUI-based apps
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(fileOpenPicker, hwnd);

var pickedFiles = await fileOpenPicker.PickMultipleFilesAsync();
if (pickedFiles.Count > 0)
{
    // At least one file was picked, you can use them
    foreach (var file in pickedFiles)
    {
        global::System.Diagnostics.Debug(file.Name);
    }
}
else
{
    // No file was picked or the dialog was cancelled.
}
```

> [!IMPORTANT]
> On Uno Platform Targets, the `Path` information found on the `StorageFile` object returned from either the `PickMultipleFilesAsync()` or `PickSingleFileAsync()` method cannot be used with Windows File System APIs. This means that, for example, this `Path` cannot be used to initialize a `FileInfo` object.
> If you need to access file size, use the `GetBasicProperties()` or `GetBasicPropertiesAsync()` methods. Both methods provide access to the `Size` and the `DateModified.` For the file extension, use the `FileType` property.

##### Accessing information about the File

```csharp
var fileOpenPicker = new FileOpenPicker();
...

var pickedFile = await fileOpenPicker.PickSingleFileAsync();

if (pickedFile != null)
{
    var extension = pickedFile.FileType;

    var properties = await pickedFile.GetBasicPropertiesAsync();    
    var size = properties.Size;
}
```

> [!NOTE]
> On iOS, when making multiple selections, you can limit the number of items selected by calling the `SetMultipleFilesLimit()` method and specifying the maximum number of items.
>

##### Limiting the number of items

```csharp
var fileOpenPicker = new FileOpenPicker();
fileOpenPicker.SuggestedStartLocation = PickerLocationId.PicturesLibrary;
fileOpenPicker.FileTypeFilter.Add(".jpg");
fileOpenPicker.FileTypeFilter.Add(".png");
//The user will be able to pick up to three files.
fileOpenPicker.SetMultipleFilesLimit(3);

var pickedFiles = await fileOpenPicker.PickMultipleFilesAsync();
...
```

> [!NOTE]
> `SuggestedStartLocation` should be set to prevent crashes on WinUI. `FileTypes` must include at least one item. You can add extensions in the format `.extension`, with the exception of `*` (asterisk), which allows picking any type of file.
>
> [!NOTE]
> On iOS, the built-in image picker does not support the selection of multiple files. Therefore, we fall back to the document picker instead. However, this requires you to specify not only the `SuggestedStartLocation` set to `PicturesLibrary`, but also specify file type extensions in `FileTypeFilter` (e.g. `.jpg` and `.png`), otherwise the OS will not display the Photos app as a file provider in the picker.

### FileSavePicker

```csharp
var fileSavePicker = new FileSavePicker();
fileSavePicker.SuggestedStartLocation = PickerLocationId.ComputerFolder;
fileSavePicker.SuggestedFileName = "myfile.txt";
fileSavePicker.FileTypeChoices.Add("Plain Text", new List<string>() { ".txt", ".text" });

// For Uno.WinUI-based apps
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(fileSavePicker, hwnd);

StorageFile saveFile = await fileSavePicker.PickSaveFileAsync();
if (saveFile != null)
{
    CachedFileManager.DeferUpdates(saveFile);

    // Save file was picked, you can now write in it
    await FileIO.WriteTextAsync(saveFile, "Hello, world!");

    await CachedFileManager.CompleteUpdatesAsync(saveFile);
}
else
{
    // No file was picked or the dialog was cancelled.
}
```

> [!NOTE]
> The `CachedFileManager` only affects Windows and WebAssembly. For more information, see [WebAssembly section](#webassembly) below.
>
> [!NOTE]
> While the `SuggestedStartLocation` has no effect, it must be set for WinUI. You must declare at least one item for `FileTypeChoices`. Each has a description and one or more extensions.

## Picker configuration

File pickers have various configuration options that customize the experience. For a full list of properties, see the [WinUI documentation](https://learn.microsoft.com/uwp/api/windows.storage.pickers.fileopenpicker). Not all options are supported on all target platforms, in which case these are ignored.

To set which file type extensions you want to allow, use the `FileTypeFilter` property on `FileOpenPicker` and `FolderPicker`, and the `FileTypeChoices` property on `FileSavePicker`. Extensions must be in the format ".xyz" (starting with a dot). For `FileOpenPicker` and `FolderPicker`, you can also include a "*" (star) entry, which represents the fact that any file extension is allowed.

Some systems use `MIME` types to specify the file type. Uno includes a list of common predefined mappings. For more information, see [Common MIME types in MDN docs](https://developer.mozilla.org/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Common_types). If a MIME type you require is missing, you can provide it by adding it to the `Uno.WinRTFeatureConfiguration.FileTypes.FileTypeToMimeMapping` dictionary:

```csharp
Uno.WinRTFeatureConfiguration.FileTypes.FileTypeToMimeMapping.Add(".myextension", "some/mimetype");
```

For iOS and macOS, `UTType` is utilized for the same purpose. Here you can provide a custom mapping using `Uno.WinRTFeatureConfiguration.FileTypes.FileTypeToUTTypeMapping` dictionary:

```csharp
Uno.WinRTFeatureConfiguration.FileTypes.FileTypeToUTTypeMapping.Add(".myextension", "my.custom.UTType");
```

Custom Uniform Type Identifiers must be declared in the `info.plist` of your iOS and macOS applications. See a full example of this in [Uniform Type Identifiers Overview from Apple documentation](https://developer.apple.com/library/archive/documentation/FileManagement/Conceptual/understanding_utis/understand_utis_declare/understand_utis_declare.html).

## WebAssembly

There are two implementations of file pickers available in WebAssembly - **File System Access API pickers** and **download/upload pickers**.

### File System Access API pickers

The most powerful picker implementation on WebAssembly uses the <a href="https://wicg.github.io/file-system-access/" target="_blank">**File System Access API**</a>. This is not yet widely implemented across all browsers. See the following support tables for each picker:

* [`FolderPicker`](https://caniuse.com/?search=showDirectoryPicker)
* [`FileOpenPicker`](https://caniuse.com/?search=showOpenFilePicker)
* [`FileSavePicker`](https://caniuse.com/?search=showSaveFilePicker)

`FolderPicker` is only supported for these types of pickers.

File System Access API pickers allow direct access to the picked files and folders. This means that any modifications the user does to the files are persisted on the target file system.

However, writing to the target file system is limited, so when a write-stream is opened for a file, Uno Platform creates a copy of the file in temporary storage, and your changes are applied to this temporary file instead. When your file stream is then flushed, closed, or disposed of, the changes are written to the source file, and the temporary file is discarded.

### Download/upload pickers

In case the **File System Access API** is not available in the browser, Uno Platform also offers a fallback to "download" and "upload" experiences.

For the upload picker, the browser triggers a file picker dialog and Uno Platform then copies the selected files into temporary storage of the app. The `StorageFile` instance you receive is private for your application and the changes are not reflected in the original file. To save the changes, you need to trigger the "download picker".

For the download picker, the experience requires the use of [`CachedFileManager`](https://learn.microsoft.com/uwp/api/Windows.Storage.CachedFileManager). Triggering `PickSaveFileAsync` does not actually show the download picker to the user. Instead, only a temporary file is created to allow you to write any content. Afterward, calling `CompleteUpdatesAsync` opens the download dialog, which allows the user to save the file.

The `CachedFileManager` class works transparently with both the **Download picker** and the **File System Access API**, which means you can write a single snippet of code that handles both scenarios correctly:

```csharp
var savePicker = new FileSavePicker():
savePicker.SuggestedStartLocation = PickerLocationId.DocumentsLibrary;
savePicker.FileTypeChoices.Add("Text file", new List<string>() { ".txt" });
savePicker.SuggestedFileName = "New Document";

// For Uno.WinUI-based apps
var hwnd = WinRT.Interop.WindowNative.GetWindowHandle(App.MainWindow);
WinRT.Interop.InitializeWithWindow.Initialize(savePicker, hwnd);

// For download picker, no dialog is actually triggered here
// and a temporary file is returned immediately.
// For File System Access API, this triggers the picker to allow
// user to select a local file.
var file = await savePicker.PickSaveFileAsync();

CachedFileManager.DeferUpdates(file);

// Write some content to the file
await FileIO.WriteTextAsync(file, "Hello, world!");

// For download picker this starts the download process of the browser
// and triggers the save dialog for the user.
// For File System Access API, this is a no-op and immediately
// completes.
await CachedFileManager.CompleteUpdatesAsync(file);
```

### Checking whether File System Access API is supported

In some cases, you might want to check whether File System Access API is supported in the current runtime environment. A typical reason might be to ensure only **Save As** functionality is available to the user when the browser only supports download pickers. You can utilize the WASM specific `Uno.Storage.Pickers.FileSystemAccessApiInformation` API:

```csharp
#if __WASM__
if (FileSystemAccessApiInformation.IsOpenPickerSupported)
{
    // File System Access API open picker is available.
}

if (FileSystemAccessApiInformation.IsSavePickerSupported)
{
    // File System Access API open picker is available.
}

if (FileSystemAccessApiInformation.AreFilePickersSupported)
{
    // Both file open and file save pickers from the
    // File System Access API are available.
}

if (FileSystemAccessApiInformation.IsFolderPickerSupported)
{
    // File System Access API folder picker is available.
}
#endif
```

### Checking the source of opened file

To know how the file needs to be handled, you need to check the type of storage provider it comes from. To do this, access the `Provider` property of the file:

```csharp
if (file.Provider.Id == "jsfileaccessapi")
{
    // File was picked using File System Access pickers.
}

if (file.Provider.Id == "computer")
{
    // File is a temporary file created using Upload picker.
}
```

The local files have a provider ID of `computer`, which matches the WinUI behavior. `jsfileaccessapi` is used for files coming from the File System Access API.

### Choosing supported type of pickers

By default, Uno Platform attempts to use File System Access API and falls back to download/upload pickers if not available. To control this behavior, you can use `WinRTFeatureConfiguration`:

```csharp
#if __WASM__
Uno.WinRTFeatureConfiguration.Storage.Pickers.WasmConfiguration =
    WasmPickerConfiguration.FileSystemAccessApiWithFallback;
#endif
```

The allowed values for the configuration are:

-`FileSystemAccessApiWithFallback` - defaults to File System Access API, but falls back to download/upload pickers if not available
-`FileSystemAccessApi` - uses File System Access API only. If not available, pickers will throw `NotSupportedException`
-`DownloadUpload` - uses download/upload pickers only.

### Security considerations

Browsers generally treat file opening/saving operations as sensitive operations, and the following message may appear when using this APIs:

```output
SecurityError: Failed to execute 'showSaveFilePicker' on 'Window': Must be handling a user gesture to show a file picker.
```

This generally means that the Uno file picking APIs have been invoked without explicit user interaction or have been rescheduled from the original user interaction callback (e.g., using `DispatcherQueue.TryRun()` inside a `Button.Click` handler to open a picker).

## Android

Files picked from file pickers on Android are provided by the *Storage Access Framework API*. Due to its limitations, it is not possible to write to existing file in-place. Instead, Uno Platform creates a copy of the file in temporary storage and your changes are applied to this temporary file instead. When your file stream is then flushed, closed, or disposed of, the changes are written to the source file, and the temporary file is discarded.

The `SuggestedStartLocation` property has no effect on certain Android devices, and the file picker will always open in the root directory of the internal storage. When using VideosLibrary or PicturesLibrary locations, the file picker will open the picture library with the image picker controller. Still, for those devices that do not support it, it will open the root directory of the internal storage and suggest all the applications that can handle file types.

The `FileSavePicker` API, which uses `ACTION_CREATE_DOCUMENT` on Android, has various limitations. To allow for the best possible compatibility across different Android versions, you should always add your file type extension to `FileTypeChoices`, and, if possible, provide only one such file type. In addition, if the `SuggestedFileName` or the user-typed file name matches an existing file, the resulting file will be renamed with `(1)` in the name, e.g., `test.txt` will become `test (1).txt` and the existing file will not be overwritten. However, if the user explicitly taps an existing file in the file browser, the system will show a dialog allowing the app to overwrite the existing file. This inconsistent behavior is caused by Android itself, so there is, unfortunately, no way to work around it from our side. See [this issue](https://issuetracker.google.com/issues/37136466) for more information.

If you want to have further influence on the pickers and, for example, create permanent access to the file for the `FileOpenPicker` (flag with GrantPersistableUriPermission), you can do this with the `FilePickerHelper`. The `FolderPicker` can be extended analogue, the `FolderPickerHelper` is available for this purpose.

```csharp
FileOpenPicker fileOpenPicker = new FileOpenPicker
{
    SuggestedStartLocation = PickerLocationId.ComputerFolder
};

#if __ANDROID__
FilePickerHelper.RegisterOnBeforeStartActivity(fileOpenPicker, (intent) =>
{
    // your code... for example
    intent.AddFlags(Android.Content.ActivityFlags.GrantPersistableUriPermission);
});
#endif

var result = await fileOpenPicker.PickSingleFileAsync();
```

## iOS

iOS does not offer a built-in `FileSavePicker` experience. Luckily, it is possible to implement this functionality, for example, using a combination of a `FolderPicker` and `ContentDialog`.

To provide your own custom implementation, create a class that implements the `IFileSavePickerExtension`, which is only available on iOS. This class must have a `public` constructor with an `object` parameter. This will actually be an instance of `FileSavePicker` when invoked later. Then implement the `PickSaveFileAsync` method:

```csharp
#if __IOS__
namespace Custom.Pickers
{
    public class CustomFileSavePickerExtension : IFileSavePickerExtension
    {
        private readonly FileSavePicker _fileSavePicker;

        public CustomFileSavePickerExtension(object owner)
        {
            _fileSavePicker = (FileSavePicker)owner;
        }

        public async Task<StorageFile> PickSaveFileAsync(CancellationToken token)
        {
            // ... your own implementation
        }
    }
}
#endif
```

When done, register this extension in `App.cs` or `App.xaml.cs`:

```csharp
public App()
{
...
#if __IOS__
    ApiExtensibility.Register(
        typeof(Uno.Extensions.Storage.Pickers.IFileSavePickerExtension),
        picker => new CustomFileSavePickerExtension(picker));
#endif
...
}
```

As this is quite complex, you can find a working implementation of a folder-based save file picker in [Uno.Samples repository](https://github.com/unoplatform/Uno.Samples/tree/master/UI/FileSavePickeriOS). You can modify and adjust this implementation as you see fit for your specific use case.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-system-display.md

---
uid: Uno.Features.WSDisplay
---

# Keeping Screen On

> [!TIP]
> This article covers Uno-specific information for the `Windows.System.Display` namespace. For a full description of the feature and instructions on using it, see [Windows.System.Display Namespace](https://learn.microsoft.com/uwp/api/windows.system.display).

* The `Windows.System.Display.DisplayRequest` class enables an application to request to keep the device's screen on.

## `DisplayRequest` class

The `DisplayRequest` API is supported on all platforms.

In the case of WASM, it is implemented using the [Screen Wake Lock API](https://w3c.github.io/screen-wake-lock/) which is not yet supported in many browsers. On unsupported browsers, the API calls are ignored. In addition, because the JS API is asynchronous, it is recommended not to request and release the screen lock multiple times in quick succession (as the promise may not be completed yet).

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-system-power.md

---
uid: Uno.Features.WSPower
---

# Battery Information

> [!TIP]
> This article covers Uno-specific information for the `Windows.System.Power` namespace. For a full description of the feature and instructions on using it, see [Windows.System.Power Namespace](https://learn.microsoft.com/uwp/api/windows.system.power).

* You can use the `Windows.System.Power.PowerManager` class to query the battery and charging status of the device and subscribe to the related events when these change.

## `PowerManager`

**Legend**

* ✔  Supported
* ✖ Not supported

| Picker         | WinUI   | WebAssembly | Android | iOS   | macOS | Skia Desktop |
|----------------|-------|-------------|---------|-------|-------|-----|
| `BatteryStatus` | ✔   | ✔  | ✔     | ✔    |✖ ️   | ✖ |
| `EnergySaverStatus` | ✔   |  ✖ | ✔     | ✔    |✖ ️   | ✖ |
| `PowerSupplyStatus` | ✔   | ✔  | ✔     | ✔   |✖ ️   | ✖ |
| `RemainingChargePercent` | ✔   | ✔ | ✔     | ✔   |✖ ️   | ✖ |
| `RemainingDischargeTime` | ✔   | ✔ |  ✖    | ✖ |✖ ️   | ✖ |
| `BatteryStatusChanged` | ✔   | ✔  | ✔     | ✔   |✖ ️   | ✖ |
| `EnergySaverStatusChanged` | ✔   |  ✖ | ✔     | ✔    |✖ ️   | ✖ |
| `PowerSupplyStatusChanged` | ✔   | ✔  | ✔     | ✔   |✖ ️   | ✖ |
| `RemainingChargePercentChanged` | ✔   | ✔| ✔     | ✔   |✖ ️   | ✖ |
| `RemainingDischargeTimeChanged` | ✔   | ✔     |  ✖     |  ✖  |✖ ️   | ✖ |

### Usage

For general usage, see [PowerManager Class](https://learn.microsoft.com/uwp/api/windows.system.power.powermanager).

## Platform-specific requirements

### Android

For Android, there is one permission you must configure before using this API in your project. To do that, add the following to `AndroidManifest.xml`:

```xml
<uses-permission android:name="android.permission.BATTERY_STATS" />
```

### Limitations

#### Android

`RemainingChargePercentChanged` event is not updated continuously as there is no API that provides such events. It is triggered by system `Low` and `Ok` battery state broadcasts only. The `RemainingChargePercent` property always returns the up-to-date value. For continuous monitoring you can set up periodic polling.

#### WebAssembly

Before any of the properties/events of `PowerManager` can be accessed, the class needs to be initialized via a platform-specific `InitializeAsync` method:

```csharp
#if HAS_UNO
var isAvailable = await PowerManager.InitializeAsync();
#endif
```

If the returned value is `false`, refrain from using `PowerManager` in your code, as it is not available in the browser the user is using.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-system-profile.md

---
uid: Uno.Features.WSProfile
---

# Device Information

> [!TIP]
> This article covers Uno-specific information for the `Windows.System.Profile` namespace. For a full description of the feature and instructions on using it, see [Windows.System.Profile Namespace](https://learn.microsoft.com/uwp/api/windows.system.profile).

- The `Windows.System.Profile` namespace provides classes for accessing and managing information about the device.

## `AnalyticsInfo`

### `DeviceForm` property

The `DeviceForm` property now returns string from the following set:

- Mobile
- Tablet
- Television
- Car
- Watch
- VirtualReality
- Desktop
- Unknown

In the case of `WebAssembly`, this property currently always returns `Unknown` as there is no reliable way to check for device form factor via JavaScript.

## `VersionInfo.DeviceFamily`

This string is in the form of `OSType.DeviceForm` where `OSType` is:

- **Android** - `Android`
- **iOS/iPadOS** - `iOS`
- **WASM** - `Browser`

## `VersionInfo.DeviceFamilyVersion`

This returns the "OS version" the app is running on. Values are the following:

- **Android** - `Build.VERSION.Release`
- **iOS** - `UIDevice.CurrentDevice.SystemVersion`
- **WASM** - returns the full user agent string (`navigator.userAgent`)

> [!NOTE]
> On WASM, the `userAgent` can easily be spoofed by malicious users.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-system-userprofile.md

---
uid: Uno.Features.WSUserProfile
---

# Wallpaper and Lock Screen

> [!TIP]
> This article covers Uno-specific information for the `Windows.System.UserProfile` namespace. For a full description of the feature and instructions on using it, see [Windows.System.UserProfile Namespace](https://learn.microsoft.com/uwp/api/windows.system.userprofile).

* The `Windows.System.UserProfile.UserProfilePersonalizationSettings` class provides functionality for setting the lock screen and wallpaper images.

The functionality of this class is available only on Android. On other platforms, the `IsSupported()` method always returns `false`.

To be able to set wallpaper and lock screen image, add the following permission to the Android project head:

```csharp
[assembly: UsesPermission("android.permission.SET_WALLPAPER")]
```

To set the wallpaper, use the following code snippet:

```csharp
using Windows.System.UserProfile;

private async Task<bool> SetWallpaperAsync(StorageFile imageFile) 
{ 
    var success = false;
    if (UserProfilePersonalizationSettings.IsSupported())
    {
        var profileSettings = UserProfilePersonalizationSettings.Current;
        success = await profileSettings.TrySetWallpaperImageAsync(file);
    }
    return success;
} 
```

Analogously for `TrySetLockScreenImageAsync`.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-system.md

---
uid: Uno.Features.WS
---

# URI Launcher

> [!TIP]
> This article covers Uno-specific information for the `Windows.System` namespace. For a full description of the feature and instructions on using it, see [Windows.System Namespace](https://learn.microsoft.com/uwp/api/windows.system).

* The `Windows.System.Launcher` class provides functionality for launching URIs and apps.

## `LaunchUriAsync`

This API is supported on iOS, Android, WASM, and macOS.

On iOS, Android, and macOS the `ms-settings:` special URI is supported.

### Platform-specifics

On iOS, launching the special URI opens the main page of system settings because deep-linking to specific settings is not available.

For WASM, launching the special URI will work properly only when opening the website on Windows. The method will return `true` even if the user cancels the application launch, as there is currently no way to detect if the app was successfully launched. When using `LaunchUriAsync` on WASM, note that there should be no await between user interaction (button click / command etc) and the Launcher invocation. Otherwise, the browser may ignore it due to security reasons.

In case of Android, we support the following nested URIs.

| Settings URI | Android Mapping |
|--------------|----------|
| `ms-settings:sync` | `Settings.ActionSyncSettings` |
| `ms-settings:appsfeatures-app` | `Settings.ActionApplicationDetailsSettings` |
| `ms-settings:appsfeatures` | `Settings.ActionApplicationSettings` |
| `ms-settings:defaultapps` | `Settings.ActionManageDefaultAppsSettings` |
| `ms-settings:appsforwebsites` | `Settings.ActionManageDefaultAppsSettings` |
| `ms-settings:cortana` | `Settings.ActionVoiceInputSettings` |
| `ms-settings:bluetooth` | `Settings.ActionBluetoothSettings` |
| `ms-settings:printers` | `Settings.ActionPrintSettings` |
| `ms-settings:typing` | `Settings.ActionHardKeyboardSettings` |
| `ms-settings:easeofaccess` | `Settings.ActionAccessibilitySettings` |
| `ms-settings:network-airplanemode` | `Settings.ActionAirplaneModeSettings` |
| `ms-settings:network-celluar` | `Settings.ActionNetworkOperatorSettings` |
| `ms-settings:network-datausage` | `Settings.ActionDataUsageSettings` |
| `ms-settings:network-wifiSettings` | `Settings.ActionWifiSettings` |
| `ms-settings:nfctransactions` | `Settings.ActionNfcSettings` |
| `ms-settings:network-vpn` | `Settings.ActionVpnSettings` |
| `ms-settings:network-wifi` | `Settings.ActionWifiSettings` |
| `ms-settings:network` | `Settings.ActionWirelessSettings` |
| `ms-settings:personalization` | `Settings.ActionDisplaySettings` |
| `ms-settings:privacy` | `Settings.ActionPrivacySettings` |
| `ms-settings:about` | `Settings.ActionDeviceInfoSettings` |
| `ms-settings:apps-volume` | `Settings.ActionSoundSettings` |
| `ms-settings:batterysaver` | `Settings.ActionBatterySaverSettings` |
| `ms-settings:display` | `Settings.ActionDisplaySettings` |
| `ms-settings:screenrotation` | `Settings.ActionDisplaySettings` |
| `ms-settings:quiethours` | `Settings.ActionZenModePrioritySettings` |
| `ms-settings:quietmomentshome` | `Settings.ActionZenModePrioritySettings` |
| `ms-settings:nightlight` | `Settings.ActionNightDisplaySettings` |
| `ms-settings:taskbar` | `Settings.ActionDisplaySettings` |
| `ms-settings:notifications` | `Settings.ActionAppNotificationSettings` |
| `ms-settings:storage` | `Settings.ActionInternalStorageSettings` |
| `ms-settings:sound` | `Settings.ActionSoundSettings` |
| `ms-settings:dateandtime` | `Settings.ActionDateSettings` |
| `ms-settings:keyboard` | `Settings.ActionInputMethodSettings` |
| `ms-settings:regionlanguage` | `Settings.ActionLocaleSettings` |
| `ms-settings:developers` | `Settings.ActionApplicationDevelopmentSettings` |

In case of macOS, Uno supports the following nested URIs, mapped to Preference Panes (/System/Library/PreferencePanes)

| Settings URI | macOS Mapping |
|--------------|----------|
| `ms-settings:signinoptions-launchfaceenrollment` | `TouchID` |
| `ms-settings:launchfingerprintenrollment` | `TouchID` |
| `ms-settings:signinoptions` | `Accounts` |
| `ms-settings:emailandaccounts` | `InternetAccounts` |
| `ms-settings:appsforwebsites` | `Settings.ActionManageDefaultAppsSettings` |
| `ms-settings:tabletmode` | `Expose` |
| `ms-settings:personalization-start` | `Expose` |
| `ms-settings:personalization-background` | `DesktopScreenEffectsPref` |
| `ms-settings:personalization` | `Appearance` |
| `ms-settings:bluetooth` | `Bluetooth` |
| `ms-settings:dateandtime` | `DateAndTime` |
| `ms-settings:region` | `Localization` |
| `ms-settings:typing` | `Keyboard` |
| `ms-settings:display` | `Displays` |
| `ms-settings:screenrotation` | `Displays` |
| `ms-settings:taskbar` | `Dock` |
| `ms-settings:batterysaver` | `EnergySaver` |
| `ms-settings:powersleep` | `EnergySaver` |
| `ms-settings:otherusers` | `FamilySharingPrefPane` |
| `ms-settings:mousetouchpad` | `Mouse` |
| `ms-settings:devices-touchpad` | `Trackpad` |
| `ms-settings:network` | `Network` |
| `ms-settings:privacy-notifications` | `Notifications` |
| `ms-settings:printers` | `PrintAndFax` |
| `ms-settings:privacy` | `Security` |
| `ms-settings:crossdevice` | `SharingPref` |
| `ms-settings:quiethours` | `ScreenTime` |
| `ms-settings:quietmomentshome` | `ScreenTime` |
| `ms-settings:sound` | `Sound` |
| `ms-settings:windowsupdate` | `SoftwareUpdate` |
| `ms-settings:cortana-windowssearch` | `Spotlight` |
| `ms-settings:cortana` | `Speech` |
| `ms-settings:storage` | `StartupDisk` |
| `ms-settings:backup` | `TimeMachine` |
| `ms-settings:easeofaccess` | `UniversalAccessPref` |

### Exceptions

* When the `uri` argument is `null`, `NullReferenceException` is thrown. Note this differs from WinUI, where `AccessViolationException` is thrown.
* When the method is called from a non-UI thread, `InvalidOperationException` is thrown.

Exceptions are in line with WinUI.

## `QueryUriSupportAsync`

This API is supported on iOS, Android, and macOS, and the implementation does not respect the `LaunchQuerySupportType` parameter yet. It also reports the aforementioned special `ms-settings` URIs on Android and iOS as supported.

### Platform-specific requirements

#### Android

When targeting Android 11 (API 30) or newer, you may notice the `QueryUriSupportAsync` returning false. To avoid this, make sure to add any URL schemes passed to it as `<queries>` entries in your `AndroidManifest.xml`:

```xml
<queries>
  <intent>
    <action android:name="android.intent.action.VIEW" />
    <data android:scheme="tel" />
  </intent>

  <intent>
    <action android:name="android.intent.action.VIEW" />
    <category android:name="android.intent.category.DEFAULT" />
    <category android:name="android.intent.category.BROWSABLE" />
    <data android:scheme="https" />
  </intent>
</queries>
```

#### iOS

Add any URL schemes passed to `QueryUriSupportAsync` as `LSApplicationQueriesSchemes` entries in your `Info.plist` file, otherwise, it will return false:

```xml
<key>LSApplicationQueriesSchemes</key>
<array>
  <string>tel</string>
  <string>https</string>
</array>
```

### Exceptions

* When the `uri` argument is `null`, `NullReferenceException` is thrown. Note this differs from WinUI, where a plain `Exception` with HRESULT is thrown.

Exceptions are in line with WinUI.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-ui-markup-extensions.md

---
uid: Uno.Features.WinUIMarkupExtension
---

# Markup Extensions

Uno Platform supports the `MarkupExtension` class, which gives the ability to enhance the XAML-first experience.

## Support for ProvideValue()

Given the following code:

```csharp
using System;
using System.Collections.Generic;
using System.Text;
using Windows.UI.Xaml.Markup;

namespace MyMarkupExtension;

[MarkupExtensionReturnType(ReturnType = typeof(string))]
public class Simple : Windows.UI.Xaml.Markup.MarkupExtension
{
    public string TextValue { get; set; }

    protected override object ProvideValue()
    {
        return TextValue + " markup extension";
    }
}
```

This class can be used as follows in the XAML:

```xml
<Grid xmlns:ex="using:MyMarkupExtension">
    <TextBlock Text="{ex:Simple TextValue='Just a simple '}"
                FontSize="16"
                Margin="0,0,0,40" />
</Grid>
```

## Support for ProvideValue(IXamlServiceProvider)

WinUI 3 provides enhanced support for MarkupExtension with the ability to get the markup context.

### IProvideValueTarget

```csharp
using System;
using System.Collections.Generic;
using System.Text;
using Windows.UI.Xaml.Markup;

namespace MyMarkupExtension;

public class SampleProvideValueTarget : MarkupExtension
{
    protected override object ProvideValue(IXamlServiceProvider serviceProvider)
    {
        var provideValueTarget = (IProvideValueTarget)context.GetService(typeof(IProvideValueTarget));

        return $"TargetProperty:{provideValueTarget.TargetProperty}, TargetObject:{provideValueTarget.TargetObject}";
    }
}
```

This class can be used as follows in the XAML:

```xml
<Grid xmlns:ex="using:MyMarkupExtension">
    <TextBlock Text="{ex:SampleProvideValueTarget}"
                FontSize="16"
                Margin="0,0,0,40" />
</Grid>
```

### IRootObjectProvider

With access to IRootObjectProvider becomes possible for a Markup extension to browse the visual tree, starting from the root of the XAML file.

This following example [from the WinUI specifications](https://github.com/microsoft/microsoft-ui-xaml-specs/blob/34b14114af141ceb843413bedb85705c9a2e9204/active/XamlServiceProvider/XamlServiceProviderApi.md#irootobjectprovider) give a glimpse of this feature.

Using the following XAML:

```csharp
public class DynamicBindExtension : MarkupExtension
{
    public DynamicBindExtension() { }

    public string Name { get; set; } = "";

    protected override object? ProvideValue(IXamlServiceProvider serviceProvider)
    {
        var root = ((IRootObjectProvider)serviceProvider.GetService(typeof(IRootObjectProvider))).RootObject;
        var info = root.GetType().GetProperty(Name);
        return info?.GetValue(root);
    }
}
```

The following XAML will display “Page Tag”:

```xml
<Page Tag='Page tag' 
      x:Class="App1.MainPage"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
      xmlns:local="using:App52"
      Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">

    <Grid>
        <ContentControl>
            <ContentControl.ContentTemplate>
                <DataTemplate>
                    <TextBlock Text="{local:DynamicBind Name=Tag}" />
                </DataTemplate>
            </ContentControl.ContentTemplate>
        </ContentControl>
    </Grid>
</Page>
```

### IUriContext

Not supported as of Uno 4.3

### IXamlTypeResolver

Not supported as of Uno 4.3

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-ui-notifications.md

---
uid: Uno.Features.WinUINotifications
---

# Badge Notifications

> [!TIP]
> This article covers Uno-specific information for the `Windows.UI.Notifications` namespace. For a full description of the feature and instructions on using it, see [Windows.UI.Notifications Namespace](https://learn.microsoft.com/uwp/api/windows.ui.notifications).

* The `Windows.UI.Notifications` namespace provides classes for creating and managing badge notifications.

Badge notifications are supported on iOS, tvOS, and macOS.

macOS supports numeric and textual badges (as opposed to WinUI) but does not support glyphs.

iOS and tvOS allow for numeric badges only. It is also necessary to request user permission prior to executing the badge notification for the first time (this request can be executed when appropriate for your application):

```csharp
#if __IOS__ || __TVOS__
UNUserNotificationCenter.Current
    .RequestAuthorization(
        UNAuthorizationOptions.Badge,
        (granted, error) => {
            if (granted)
            {
                //now setting badge is possible
            }
        });
#endif
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-ui-startscreen.md

---
uid: Uno.Features.WinUIStartScreen
---

# Start Screen

> [!TIP]
> This article covers Uno-specific information for the `Windows.UI.StartScreen` namespace. For a full description of the feature and instructions on using it, see [Windows.UI.StartScreen Namespace](https://learn.microsoft.com/uwp/api/windows.ui.startscreen).

* The `Windows.UI.StartScreen` namespace provides classes for creating and managing app jump lists.

## `JumpList` &amp; `JumpListItem`

The APIs are implemented on iOS and Android. Other platforms return `false` when calling the `JumpList.IsSupported()` method.

`JumpListItem` supports `DisplayName`, `Description`, `Arguments`, and `Logo` properties on both Android and iOS.

`DisplayName` may not be empty on Android and iOS - this behavior differs from WinUI. If left empty, a single space will be used instead.

`Logo` property can be initialized only with `ms-appx:`-based images. This behavior matches WinUI and actually matches native support on both platforms as well.

To handle `JumpListItem` activation, check the `LaunchActivatedEventArgs.Arguments` in the `App.OnLaunched` method. Note that when the application is running, the method will still be called again (this behavior matches WinUI).

The API supports interoperability with native "app shortcuts". This means items you add using the native API instead of `JumpList` API will not be overwritten by `JumpList` and will appear first in the list of shortcuts. These non-Uno shortcuts will not be accessible in the `JumpList.Items` collection. To identify Uno-specific app shortcuts, a `UnoShortcut` key is used and set in `ShortcutInfo.Extras` on Android and `UIApplicationShortcutItem.UserInfo` on iOS.

Note the order of shortcut items on iOS is **reversed**. This is the default system, but you can write a platform-specific snippet that reverses the list before saving to have the same top-down order as on Android and WinUI. iOS also limits the number of items that can be displayed at the same time (for example, 4 on iPhone 6 Plus), this is device-specific.

## Example

![Android JumpList sample](../Assets/features/jumplist/android.png)

![iOS JumpList sample](../Assets/features/jumplist/ios.png)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-ui-storecontext.md

---
uid: Uno.Features.StoreContext
---

# Store Context

> [!TIP]
> This article provides Uno Platform-specific information for the `Windows.Services.Store.StoreContext` namespace. For a comprehensive overview of this feature and detailed usage instructions, refer to the official documentation for [Windows.Services.Store.StoreContext Namespace](https://learn.microsoft.com/uwp/api/Windows.Services.Store.StoreContext).

## In-App Review

The in-app review feature is currently supported on iOS and Android through Google Play.

### Google Play Integration

#### References in a Single Project

In an Uno Platform Single Project, you'll need to add the `GooglePlay` [Uno Feature](xref:Uno.Features.Uno.Sdk#uno-platform-features) as follows:

```xml
<UnoFeatures>
    ...
    GooglePlay;
    ...
</UnoFeatures>
```

#### References in a Legacy Project

On all Uno Platform targets, you'll need the to add the `Uno.WinUI.GooglePlay` package to your project. This package is available on [nuget.org](https://www.nuget.org/packages/Uno.WinUI.GooglePlay).

### Usage

For iOS, no additional steps are needed—you can use the feature via the following snippet directly. On Android, ensure that you've added the above package to your project first.

```csharp
await Windows.Services.Store.StoreContext.GetDefault().RequestRateAndReviewAppAsync();
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-ui-succinct-syntax.md

---
uid: Uno.Features.WinUISuccinctSyntax
---

# Uno Support for WinUI succinct syntax

Uno supports the [succinct syntax](https://github.com/microsoft/microsoft-ui-xaml-specs/blob/master/active/gridsyntax/GridSyntaxSpec.md) WinUI XAML language feature that allows the initialization of collection-type properties (including read-only properties) using element attribute syntax.

## Examples

### New succinct syntax

The code below has the same functionality as the code shown above with the original syntax. It creates a grid and defines five different rows and columns, each with their own specific height/width, and adds them to the Grid.

```xml
<Grid ColumnDefinitions="1*, 2*, Auto, *, 300"
      RowDefinitions="1*, Auto, 25, 14, 20">
</Grid>
```

### Grid-specific syntax using assigned ContentProperty

The code below has the same functionality as the code shown above with the original syntax, but uses the ColumnDefinition and RowDefinition content property assignments to write it in the following way.

```xml
<Grid>
    <Grid.ColumnDefinitions>
          <ColumnDefinition>1*</ColumnDefinition>
          <ColumnDefinition>2*</ColumnDefinition>
          <ColumnDefinition>Auto</ColumnDefinition>
          <ColumnDefinition>*</ColumnDefinition>
          <ColumnDefinition>300</ColumnDefinition>
    </Grid.ColumnDefinitions>
    <Grid.RowDefinitions>
          <RowDefinition>1*</RowDefinition>
          <RowDefinition>Auto</RowDefinition>
          <RowDefinition>25</RowDefinition>
          <RowDefinition>14</RowDefinition>
          <RowDefinition>20</RowDefinition>
    </Grid.RowDefinitions>
</Grid>
```

## Notes

- Uno currently only supports this syntax for Grid.
  
See the [WinUI documentation](https://github.com/microsoft/microsoft-ui-xaml-specs/blob/master/active/gridsyntax/GridSyntaxSpec.md) for more details.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-ui-viewmanagement.md

---
uid: Uno.Features.WinUIViewManagement
---

# View Management

> [!TIP]
> This article covers Uno-specific information for the `Windows.UI.ViewManagement` namespace. For a full description of the feature and instructions on using it, see [Windows.UI.ViewManagement Namespace](https://learn.microsoft.com/uwp/api/windows.ui.viewmanagement).

* The `Windows.UI.ViewManagement.ApplicationViewTitleBar` class allows working with the title bar of the application window.
* The `Windows.UI.ViewManagement.StatusBar` class allows working with the status bar on mobile.
* The `Windows.UI.ViewManagement.UISettings` class allows retrieving the current system visual settings.

## `ApplicationViewTitleBar` class

The `BackgroundColor` property is implemented on WASM and uses the `theme-color` `<meta>` tag.

If you set `theme_color` in the PWA application manifest, setting this property will override this configuration.

This functionality is currently supported in Chrome, Edge (Chromium), and Opera when the app is installed as PWA and in Chrome mobile (even without installing).

![Blue title bar](../Assets/features/applicationviewtitlebar/blue.png)
![Red title bar](../Assets/features/applicationviewtitlebar/red.png)

## `StatusBar` class

The `StatusBar` is located at the top of the screen on mobile devices. The properties below are implemented for both iOS and Android.

You may style the status bar using the `BackgroundColor` and `ForegroundColor` properties.

> [!NOTE]
> While you can assign any color to `ForegroundColor`, the status bar will render it as either light or dark. It will automatically choose the closest match to the specified color.

If you don’t explicitly set the `ForegroundColor`, the app will automatically choose between a light or dark foreground to try to maximize contrast with the `BackgroundColor` you provide.

> [!IMPORTANT]
> In order for the status bar colors to be customizable on iOS, the [`UIViewControllerBasedStatusBarAppearance` property](https://developer.apple.com/documentation/bundleresources/information-property-list/uiviewcontrollerbasedstatusbarappearance) needs to be set to false in the platform's Info.plist file.

![Blue Android Status Bar](../Assets/features/statusbar/blue.png)
![Dark blue iOS Status Bar](../Assets/features/statusbar/darkblue.png)

## `UISettings`

Using the `GetColorValue` method, you can retrieve the system `Background` and `Foreground` color, which is useful to check if the system is currently using dark or light theme. To get notified about the color scheme changes, subscribe to the `ColorValuesChanged` event. Similarly to UWP, make sure to keep a reference to the `UISettings` instance, otherwise the instance will be collected and the event will not be raised.

On Android, the `AnimationsEnabled` property is implemented and allows you to check whether animations were disabled on the system level (for accessibility or battery saving). You can then use this information to disable custom animations within your app.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-ui-xaml-application.md

---
uid: Uno.Features.WinUIApplication
---

# Application

> [!TIP]
> This article covers Uno-specific information for `Microsoft.UI.Xaml.Application`. For a full description of the feature and instructions on using it, see [Application Class](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.application).

* The `Microsoft.UI.Xaml.Application` class enables an application to manage the lifetime of the application and to query the application's state.

## Application.Suspending event

This event is invoked when the application is about to be suspended.

### Limitations

#### WebAssembly

The application cannot perform asynchronous work during the execution of the handler of Suspending, as the browser window will be closed thereafter the execution of a [`beforeunload`](https://developer.mozilla.org/en-US/docs/Web/API/Window/beforeunload_event) handler.

The handler must invoke the deferral at the end.

```csharp
private void OnSuspending(object sender, SuspendingEventArgs e)
{
    var deferral = e.SuspendingOperation.GetDeferral();
    //TODO: Save application state
    deferral.Complete();
}
```

If the application wants to make a network call, the [navigation.sendBeacon](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/sendBeacon) can be used past the closing of the current browser page.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-ui-xaml-window.md

---
uid: Uno.Features.WinUIWindow
---

# Windowing

> [!TIP]
> This article covers Uno-specific information for `Microsoft.UI.Xaml.Window` and windowing. For a full description of the feature and instructions on using it, see [Window Class](https://learn.microsoft.com/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.window) and [Windowing Overview](https://learn.microsoft.com/windows/apps/windows-app-sdk/windowing/windowing-overview).
>
> [!Video https://www.youtube-nocookie.com/embed?listType=playlist&list=PLl_OlDcUya9qHAzFlO5Z6SGJ8zHg-nYkh]
For more information and detailed walkthroughs on Windowing, please refer to the rest of the [video playlist](https://www.youtube.com/playlist?list=PLl_OlDcUya9qHAzFlO5Z6SGJ8zHg-nYkh).

* The `Microsoft.UI.Xaml.Window` class allows for managing the window of the application.
* This article also describes window management in Uno Platform apps

## Explaining basic Windowing APIs

There are several "window" types in Uno Platform apps, some are legacy only and will be removed in future releases.

* `Microsoft.UI.Xaml.Window` - the main type representing a XAML-based Window. Allows for basic manipulation and setting content.
* `Microsoft.UI.Windowing.AppWindow` - represents a general Window (may not be XAML based in case of WinUI target). Includes advanced capabilities not present on `Window` itself.

The legacy types are:

* `Windows.UI.Core.CoreWindow`
* `Windows.UI.WindowManagement.AppWindow`

While these are still available for backward compatibility purposes, they will be deprecated and no longer retrievable in future releases of Uno Platform.

## Creating a new window

To display a new window (both primary and secondary), you can utilize the `Microsoft.UI.Xaml.Window` constructor:

```csharp
var window = new Window();
window.Content = new TextBlock() { "Hello, world" };
window.Activate();
```

### Support for secondary windows

All Uno Platform desktop targets support displaying secondary windows. Attempt to create a second window on Android and iOS will result in a `InvalidOperation` exception. Support for multi-windowing in mobile targets is actively investigated.

## Making the window full screen

`AppWindow` provides various ways to manipulate the display of a window including the ability to make it run in full-screen mode. Use the `SetPresenter` method to switch to this mode:

```csharp
myWindow.AppWindow.SetPresenter(AppWindowPresenterKind.FullScreen); 
```

To exit full-screen mode, switch back to default:

```csharp
myWindow.AppWindow.SetPresenter(AppWindowPresenterKind.Default);
```

## Minimizing or maximizing a window

Use the `OverlappedPresenter` to minimize or maximize your window in desktop environments. The `Overlapped` presenter is set by default, unless you switch to full screen (see above).

```csharp
var overlappedPresenter = (OverlappedPresenter)myWindow.AppWindow.Presenter;
// Minimize the window
overlappedPresenter.Minimize();

// Restore window
overlappedPresenter.Restore();

// Maximize the window
overlappedPresenter.Maximize();
```

## Fixing a window size and preventing resizing

To set a fixed size for the main window on the desktop target, configure the `OverlappedPresenter` in the `OnLaunched` method of App.Xaml.cs. This change will prevent users from resizing the window.

```csharp
protected async override void OnLaunched(LaunchActivatedEventArgs args)
{
    //...
    const int targetWidth = 2048;
    const int targetHeight = 1536;

    MainWindow.AppWindow.Resize(new Windows.Graphics.SizeInt32 { Width = targetWidth, Height = targetHeight });

    // Disable resizing
    if (MainWindow.AppWindow.Presenter is Microsoft.UI.Windowing.OverlappedPresenter presenter)
    {
        presenter.IsResizable = false; // Disable window resizing
        presenter.IsMaximizable = false; // Disable window maximizing
        presenter.PreferredMinimumWidth = targetWidth; // Set minimum width
        presenter.PreferredMinimumHeight = targetHeight; // Set minimum height
    }
}
```

## Allowing window size within specific limits

You can set maximum dimensions using `PreferredMaximumWidth` and `PreferredMaximumHeight`:

```csharp
if (MainWindow.AppWindow.Presenter is Microsoft.UI.Windowing.OverlappedPresenter presenter)
{
    presenter.PreferredMaximumWidth = 2560; // Set maximum width
    presenter.PreferredMaximumHeight = 1440; // Set maximum height
}
```

These properties allow you to set the maximum dimensions for the window. When set, the window cannot be resized beyond these values by the user. This is useful for constraining the window size to fit specific design requirements or to prevent the window from becoming too large for the content to display properly.

> [!NOTE]
> If your app uses Uno Navigation, set the sizing options before you start the Host (see the code below). This makes sure the window appears as expected.

```csharp
// Set the window size here
Host = await builder.NavigateAsync<Shell>();
```

## Enumerating windows

WinUI currently does not provide a way to enumerate open windows of an application. Due to this limitation, we recommend you to track the windows manually.

To simplify this on non-WinUI targets, we provide the `ApplicationHelper.Windows` property to enumerate currently available windows:

```csharp
#if HAS_UNO
foreach (var window in ApplicationHelper.Windows)
{
    // Do something.
}
#endif
```

> [!NOTE]
> Make sure to access this property from the UI thread.

## Retrieving the native window

On some platforms, the window is backed by a native type. For those cases, you can use the `GetNativeWindow` helper:

```csharp
#if HAS_UNO
var nativeWindow = Uno.UI.Xaml.WindowHelper.GetNativeWindow(MainWindow);
#endif
```

The `nativeWindow` is an `object`, so you need to cast it to the specific type on the given platform. See the table below:

|                                |   Skia+GTK   |               Skia+X11                |        Skia+WPF         |       iOS        |        Android        |       macOS       | WebAssembly |
| ------------------------------ | :----------: | :-----------------------------------: | :---------------------: | :--------------: | :-------------------: | :---------------: | :---------: |
| `WindowHelper.GetNativeWindow` | `Gtk.Window` | `Uno.UI.Runtime.Skia.X11NativeWindow` | `System.Windows.Window` | `UIKit.UIWindow` | `Android.View.Window` | `AppKit.NSWindow` |   `null`    |

## Avoiding `Window.Current`

`Window` type has a static `Current` property which previously served as a way to access the main, singleton window instance. This is no longer relevant in multi-window scenarios. For legacy reasons and to maintain compatibility with existing Uno Platform apps, we opted to keep this property and it returns the first window that was created. You should not rely on this behavior going forward as it will be deprecated.

## Customizing window border and title bar

### Checking if title bar customization is supported

Before customizing the title bar, you should always check if title bar customization is available on the current platform:

```csharp
if (AppWindowTitleBar.IsCustomizationSupported())
{
    // Customize the title bar
    myWindow.AppWindow.TitleBar.ExtendsContentIntoTitleBar = true;
}
```

Currently, `IsCustomizationSupported()` returns `true` on Desktop Windows (net9.0-desktop, net10.0-desktop) and WinAppSDK (net9.0-windows10.0.x, net10.0-windows10.0.x) targets.

### Setting border and title bar visibility

The `OverlappedPresenter.SetBorderAndTitleBar` method allows you to control whether the window displays a border and title bar:

```csharp
var overlappedPresenter = (OverlappedPresenter)myWindow.AppWindow.Presenter;
// Remove both border and title bar
overlappedPresenter.SetBorderAndTitleBar(hasBorder: false, hasTitleBar: false);

// Show border but hide title bar
overlappedPresenter.SetBorderAndTitleBar(hasBorder: true, hasTitleBar: false);

// Show both border and title bar
overlappedPresenter.SetBorderAndTitleBar(hasBorder: true, hasTitleBar: true);
```

> [!NOTE]
> This API is currently supported on Desktop Windows (net9.0-desktop, net10.0-desktop) and WinAppSDK (net9.0-windows10.0.x, net10.0-windows10.0.x) targets. On other platforms, the method exists but may have limited or no effect.

### Extending content into title bar

The `AppWindowTitleBar.ExtendsContentIntoTitleBar` property allows you to extend your app content into the title bar area, giving you full control over the title bar region:

```csharp
myWindow.AppWindow.TitleBar.ExtendsContentIntoTitleBar = true;
```

When you extend content into the title bar, you typically want to provide a custom title bar element using `Window.SetTitleBar`:

```csharp
myWindow.AppWindow.TitleBar.ExtendsContentIntoTitleBar = true;
myWindow.SetTitleBar(myCustomTitleBarElement);
```

> [!NOTE]
> This API is currently supported on Desktop Windows (net9.0-desktop, net10.0-desktop) and WinAppSDK (net9.0-windows10.0.x, net10.0-windows10.0.x) targets. On other platforms, the property exists but may have limited or no effect.

### Configuring title bar height

When extending content into the title bar, you can control the height of the title bar using the `PreferredHeightOption` property:

```csharp
// Standard height (32px at default DPI)
myWindow.AppWindow.TitleBar.PreferredHeightOption = TitleBarHeightOption.Standard;

// Tall height (48px at default DPI)
myWindow.AppWindow.TitleBar.PreferredHeightOption = TitleBarHeightOption.Tall;

// Collapsed (0px)
myWindow.AppWindow.TitleBar.PreferredHeightOption = TitleBarHeightOption.Collapsed;
```

The actual height in pixels (not scaled points) is calculated based on the DPI scaling of the window and can be retrieved from the `Height` property:

```csharp
int titleBarHeight = myWindow.AppWindow.TitleBar.Height; // Height in actual pixels
```

> [!NOTE]
> `PreferredHeightOption` is supported on Desktop Windows (net9.0-desktop, net10.0-desktop) and WinAppSDK (net9.0-windows10.0.x, net10.0-windows10.0.x) targets when the title bar is extended into the content area. The `Height` property returns the value in actual pixels, not scaled points.

### Setting drag rectangles

The `AppWindowTitleBar.SetDragRectangles` method allows you to define specific rectangular regions in the title bar area that the user can drag to move the window:

```csharp
var dragRectangles = new[]
{
    new RectInt32(10, 0, 200, 32),  // Draggable region from x=10 to x=210
    new RectInt32(250, 0, 300, 32)  // Another draggable region from x=250 to x=550
};

myWindow.AppWindow.TitleBar.SetDragRectangles(dragRectangles);
```

> [!IMPORTANT]
>
> * The rectangles are specified in actual pixels, not scaled points.
> * Drag rectangles must be updated when the window size or DPI scaling changes, otherwise they will be incorrectly positioned.
> * This API is supported on Desktop Windows (net9.0-desktop, net10.0-desktop) and WinAppSDK (net9.0-windows10.0.x, net10.0-windows10.0.x) targets.

Example of updating drag rectangles on window size changes:

```csharp
myWindow.SizeChanged += (sender, args) =>
{
    // Recalculate and update drag rectangles based on new window size
    UpdateDragRectangles();
};
```

### Advanced: Setting non-client pointer source regions

The `InputNonClientPointerSource.SetRegionRects` method provides advanced control over non-client regions, which is particularly useful when you use `SetBorderAndTitleBar(true, false)` and render your own caption buttons (minimize, maximize, close).

By setting the region rectangles for caption buttons, you enable Windows features like the Snap Layouts popup that appears when hovering over the maximize button:

![Snap Layouts popup](https://github.com/user-attachments/assets/bade7d00-1559-4022-a8c7-820d42e4ed74)

```csharp
using Microsoft.UI.Input;

var appWindow = myWindow.AppWindow;
var nonClientInputSrc = InputNonClientPointerSource.GetForWindowId(appWindow.Id);

// Define the maximize button region to enable Snap Layouts
var maximizeButtonRect = new RectInt32(100, 0, 46, 32); // x, y, width, height in actual pixels

nonClientInputSrc.SetRegionRects(NonClientRegionKind.Caption, new[] { maximizeButtonRect });
```

> [!IMPORTANT]
>
> * Region rectangles are specified in actual pixels, not scaled points.
> * These rectangles must be updated when the window size or DPI scaling changes.
> * This API is supported on Desktop Windows (net9.0-desktop, net10.0-desktop) and WinAppSDK (net9.0-windows10.0.x, net10.0-windows10.0.x) targets.

## Setting the background color for the Window

WinUI and UWP does not support the ability to provide a background color for `Window`, but Uno provides such an API through:

```csharp
#if HAS_UNO
Uno.UI.Xaml.WindowHelper.SetBackground(Window.Current, new SolidColorBrush(Colors.Red));
#endif
```

This feature can help blend the background of the window with the background of the rendered app content when the window is resized.

### Supported platforms

|                              | Skia Desktop | iOS | Android | macOS | WebAssembly |
| ---------------------------- | :----------: | :-: | :-----: | :---: | :---------: |
| `WindowHelper.SetBackground` |      ✔️     | ❌  |   ❌    |  ❌  |     ❌     |

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/windows-ui-xaml-xbind.md

---
uid: Uno.Features.WinUIxBind
---

# Uno Support for x:Bind

Uno supports the [`x:Bind`](https://learn.microsoft.com/windows/uwp/xaml-platform/x-bind-markup-extension) WinUI feature, which gives the ability to:

- bind to normal fields and properties
- static classes fields
- functions with multiple parameters
- events
- `x:Bind` on _"Plain-old C# Objects"_ (POCO) created in XAML

## Examples

- Properties
  - Page or control property

    ```xml
    <TextBlock Text="{x:Bind MyProperty}" />
    ```

  - Member function

    ```xml
    <TextBlock Text="{x:Bind MyProperty.ToUpper()}" />
    ```

  - Static types field or properties OneTime binding

    ```xml
    <TextBlock Text="{x:Bind local:StaticType.PropertyIntValue}" />
    ```

  - OneWay local member function with multiple observable parameters

    ```xml
    <TextBlock Text="{x:Bind Multiply(slider1.Value, slider2.Value), Mode=OneWay}" />
    ```

  - OneWay static class function with  multiple observable parameters

    ```xml
    <TextBlock Text="{x:Bind local:StaticType.Add(slider1.Value, slider2.Value), Mode=OneWay}" />
    ```

  - Literal boolean parameters (`x:True`, `x:False`)

    ```xml
    <TextBlock Text="{x:Bind BoolFunc(x:False)}" />
    ```

  - Null parameter (`x:Null`)

    ```xml
    <TextBlock Text="{x:Bind TestString(x:Null)}" />
    ```

  - Quote escaping

    ```xml
    <TextBlock Text="{x:Bind sys:String.Format('{0}, ^'{1}^'', InstanceProperty, StaticProperty)}" />
    ```

  - Literal numeric value

    ```xml
    <TextBlock Text="{x:Bind Add(InstanceProperty, 42.42)}" />
    ```

- Use of system functions (given `xmlns:sys="using:System"`):
  - Single parameter formatting:

    ```xml
    <TextBlock Text="{x:Bind sys:String.Format('Formatted {0}', MyProperty), Mode=OneWay}" />
    ```

  - Multi parameters formatting:

    ```xml
    <TextBlock Text="{x:Bind sys:String.Format(x:Null, 'slider1: {0}, slider2:{1}', slider1.Value, slider2.Value), Mode=OneWay}" />
    ```

  - TimeParsing:

    ```xml
    <CalendarDatePicker Date="{x:Bind sys:DateTime.Parse(TextBlock1.Text)}" />
    ```

- Use of `BindBack`

  ```xml
  <TextBlock Text="{x:Bind sys:String.Format('{0}', MyInteger), BindBack=BindBackMyInteger, Mode=TwoWay}" />
  ```

  where this methods is available in the control:

  ```csharp
  public void BindBackMyInteger(string text)
  {
    MyInteger = int.Parse(text);
  }
  ```

- Bind to events

  ```xml
  <CheckBox Checked="{x:Bind OnCheckedRaised}" Unchecked="{x:Bind OnUncheckedRaised}" />
  ```

  where these methods are available in the code behind:

  ```csharp
  public void OnCheckedRaised() { }
  public void OnUncheckedRaised(object sender, RoutedEventArgs args) { }
  ```

- [Attached Properties](https://learn.microsoft.com/windows/uwp/xaml-platform/x-bind-markup-extension#attached-properties)

  ```xml
  <Button x:Name="Button22" Content="Click me!" Grid.Row="42" />
  <TextBlock Text="{x:Bind Button22.(Grid.Row)}" />
  ```

- Type casts

  - ```xml
    <TextBox FontFamily="{x:Bind (FontFamily)MyComboBox.SelectedValue}" />
    ```

  - ```xml
    <TextBox Text="{x:Bind (x:String)MyObject}" />
    ```

  - ```xml
    <TextBox Text="{x:Bind MyFunction((x:String)MyObject, (x:String)MyObject)}" />
    ```

  - ```xml
    <TextBox Tag="{x:Bind ((x:String)MyObject).Length}" />
    ```

  where this methods is available in the code behind:

  ```csharp
  public void MyFunction(string p1, string p2) { }
  ```

- [Pathless casting](https://learn.microsoft.com/windows/uwp/xaml-platform/x-bind-markup-extension#pathless-casting)

  ```xml
  <Page
    x:Class="AppSample.MainPage"
    ...
    xmlns:local="using:AppSample">

    <Grid>
        <ListView ItemsSource="{x:Bind Songs}">
            <ListView.ItemTemplate>
                <DataTemplate x:DataType="local:SongItem">
                    <TextBlock
                        Margin="12"
                        FontSize="40"
                        Text="{x:Bind local:MainPage.GenerateSongTitle((local:SongItem))}" />
                </DataTemplate>
            </ListView.ItemTemplate>
        </ListView>
    </Grid>
  </Page>
  ```

- `x:Load` binding

  ```xml
  <TextBox x:Load="{x:Bind IsMyControlVisible}" />
  ```

  See the [{x:Bind} markup extension from WinUI documentation](https://learn.microsoft.com/windows/uwp/xaml-platform/x-bind-markup-extension) for more details.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/winui-doc-links-design.md

---
uid: Uno.Development.WinUIDesignDoc
---

# WinUI documentation - Design

Uno Platform's API is derived from the WinUI application framework. Microsoft provides [extensive documentation for WinUI](https://learn.microsoft.com/windows/uwp/). Rather than duplicate all of it, here we list selected entries that are especially applicable to Uno Platform developers.

These resources can serve as a starting point when designing your Uno Platform application.

Some of the points of guidance may be specific to Windows 10's [Fluent design language](https://www.microsoft.com/design/fluent/). When designing your cross-platform application, feel free to choose the principles that best apply to your users and the app experience you're aiming for.

## Basic design principles

* [Navigation principles](https://learn.microsoft.com/windows/uwp/design/basics/navigation-basics)
* [Interactive elements](https://learn.microsoft.com/windows/uwp/design/basics/commanding-basics)
* [Content presentation](https://learn.microsoft.com/windows/uwp/design/basics/content-basics)
* [Page layout](https://learn.microsoft.com/windows/uwp/design/layout/page-layout)

## Responsive design

* [Screen sizes and breakpoints](https://learn.microsoft.com/windows/uwp/design/layout/screen-sizes-and-breakpoints-for-responsive-design)
* [Responsive design](https://learn.microsoft.com/windows/uwp/design/layout/responsive-design)

## Individual controls

* [Controls list](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/) _(note: not all controls may be implemented on non-Windows platforms - check the [individual control entries](implemented-views.md) in the Uno Platform API reference for details)_

## Patterns

* [Forms](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/forms)
* [Master/details pattern](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/master-details)
* [Integrating search](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/search)

## Writing

* [Writing style](https://learn.microsoft.com/windows/uwp/design/style/writing-style)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/winui-doc-links-development.md

---
uid: Uno.Development.WinUIDevelopmentDoc
---

# WinUI documentation - Development

Uno Platform's API is derived from the WinUI application framework. Microsoft provides [extensive documentation for WinUI](https://learn.microsoft.com/windows/uwp/). Rather than duplicate all of it, here we list selected entries that are especially applicable to Uno Platform developers.

The resources below explain many aspects of the API shared by WinUI and Uno Platform in more detail, including layouting, styling and templating, data binding, and more.

## Layouting

* [Basic layout concepts](https://learn.microsoft.com/windows/uwp/design/layout/layouts-with-xaml)
* [Alignment, margin, padding](https://learn.microsoft.com/windows/uwp/design/layout/alignment-margin-padding)
* [Panels](https://learn.microsoft.com/windows/uwp/design/layout/layout-panels)
* [Custom panels](https://learn.microsoft.com/windows/uwp/design/layout/custom-panels-overview)
* [Transforms](https://learn.microsoft.com/windows/uwp/design/layout/transforms)

## Drawing

* [Images and image brushes](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/images-imagebrushes)
* [Shapes](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/shapes)
* [Path geometry syntax](https://learn.microsoft.com/windows/uwp/xaml-platform/move-draw-commands-syntax)
* [Brushes](https://learn.microsoft.com/windows/uwp/design/style/brushes) _(note: see [Brush types supported on non-Windows platforms](features/shapes-and-brushes.md#implemented-brushes--properties))_

## Styling and templating

* [Styling](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/xaml-styles)
* [Control templates](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/control-templates)
* [XAML resources and ResourceDictionary](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/resourcedictionary-and-xaml-resource-references)
* [Theme resources](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/xaml-theme-resources)

## Controls

* [Control basics](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/controls-and-events-intro)
* [Navigation view](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/navigationview)
* [Tab view](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/tab-view)

### Lists

* [Item templating](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/item-containers-templates)
* [Data template selection](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/data-template-selector)
* [Selection modes](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/selection-modes)
* [Filtering lists](https://learn.microsoft.com/windows/uwp/design/controls-and-patterns/listview-filtering)

## Animations

* [Storyboarded animations](https://learn.microsoft.com/windows/uwp/design/motion/storyboarded-animations)

## Events and pointer input

* [Pointer input](https://learn.microsoft.com/windows/uwp/design/input/handle-pointer-input)
* [Events and routed events](https://learn.microsoft.com/windows/uwp/xaml-platform/events-and-routed-events-overview)

## Data binding and dependency properties

* [Data binding overview](https://learn.microsoft.com/windows/uwp/data-binding/data-binding-quickstart)
* [Data binding in depth](https://learn.microsoft.com/windows/uwp/data-binding/data-binding-in-depth)
* [x:Bind to functions](https://learn.microsoft.com/windows/uwp/data-binding/function-bindings)
* [Dependency properties overview](https://learn.microsoft.com/windows/uwp/xaml-platform/dependency-properties-overview)
* [Custom dependency properties](https://learn.microsoft.com/windows/uwp/xaml-platform/custom-dependency-properties)
* [Attached properties overview](https://learn.microsoft.com/windows/uwp/xaml-platform/attached-properties-overview)
* [Custom attached properties](https://learn.microsoft.com/windows/uwp/xaml-platform/custom-attached-properties)
* [MVVM architecture](https://learn.microsoft.com/windows/uwp/data-binding/data-binding-and-mvvm)

## XAML

* [XAML overview](https://learn.microsoft.com/windows/uwp/xaml-platform/xaml-overview)
* [XAML syntax and terminology](https://learn.microsoft.com/windows/uwp/xaml-platform/xaml-syntax-guide)
* [Property path syntax rules](https://learn.microsoft.com/windows/uwp/xaml-platform/property-path-syntax)
* [XAML namespaces](https://learn.microsoft.com/windows/uwp/xaml-platform/xaml-namespaces-and-namespace-mapping)

### XAML attributes

* [x:Class attribute](https://learn.microsoft.com/windows/uwp/xaml-platform/x-class-attribute)
* [x:DefaultBindMode attribute](https://learn.microsoft.com/windows/uwp/xaml-platform/x-defaultbindmode-attribute)
* [x:FieldModifier attribute](https://learn.microsoft.com/windows/uwp/xaml-platform/x-fieldmodifier-attribute)
* [x:Key attribute](https://learn.microsoft.com/windows/uwp/xaml-platform/x-key-attribute)
* [x:Load attribute](https://learn.microsoft.com/windows/uwp/xaml-platform/x-load-attribute)
* [x:Name attribute](https://learn.microsoft.com/windows/uwp/xaml-platform/x-name-attribute)
* [x:Phase attribute](https://learn.microsoft.com/windows/uwp/xaml-platform/x-phase-attribute)
* [x:Uid directive](https://learn.microsoft.com/windows/uwp/xaml-platform/x-uid-directive)

### Markup extensions

* [x:Bind markup extension](https://learn.microsoft.com/windows/uwp/xaml-platform/x-bind-markup-extension)
* [`{Binding}` markup extension](https://learn.microsoft.com/windows/uwp/xaml-platform/binding-markup-extension)
* [CustomResource markup extension](https://learn.microsoft.com/windows/uwp/xaml-platform/customresource-markup-extension)
* [RelativeSource markup extension](https://learn.microsoft.com/windows/uwp/xaml-platform/relativesource-markup-extension)
* [StaticResource markup extension](https://learn.microsoft.com/windows/uwp/xaml-platform/staticresource-markup-extension)
* [TemplateBinding markup extension](https://learn.microsoft.com/windows/uwp/xaml-platform/templatebinding-markup-extension)
* [ThemeResource markup extension](https://learn.microsoft.com/windows/uwp/xaml-platform/themeresource-markup-extension)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/winui-doc-links-tutorials.md

---
uid: Uno.Development.WinUITutorialsDoc
---

# WinUI documentation - Tutorials

Uno Platform's API is derived from the WinUI application framework. Microsoft provides [extensive documentation for WinUI](https://learn.microsoft.com/windows/uwp/). Rather than duplicate all of it, here we list selected entries that are especially applicable to Uno Platform developers.

You can work through these tutorials either as single-platform WinUI applications or as multi-platform Uno Platform applications. In the latter case, when the tutorial instructs you to create a new WinUI application in Visual Studio, you should create a [new Uno Platform application](get-started.md) instead.

* [Navigate between two pages](https://learn.microsoft.com/windows/uwp/design/basics/navigate-between-two-pages)
* [Create a simple weather app with Grid and StackPanel](https://learn.microsoft.com/windows/uwp/design/layout/grid-tutorial)
* [BoxPanel, an example custom panel](https://learn.microsoft.com/windows/uwp/design/layout/boxpanel-example-custom-panel)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/winui-doc-links.md

---
uid: Uno.Development.WinUIDoc
---

# Links to WinUI documentation

Uno Platform's API is derived from the WinUI application framework. Microsoft provides [extensive documentation for WinUI](https://learn.microsoft.com/windows/uwp/). Rather than duplicate all of it, here we list selected entries that are especially applicable to Uno Platform developers.

Note that some instructions may not apply when using Uno Platform. For example, some articles will instruct you to create a new WinUI application in Visual Studio - you would, in that case, create a new Uno Platform application](get-started.md) instead.

* [Tutorials](winui-doc-links-tutorials.md)
* [Development](winui-doc-links-development.md)
* [Design](winui-doc-links-design.md)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/working-with-accessibility.md

---
uid: Uno.Features.Accessibility
---

# Accessibility (a11y)

Windows uses the UI Automation framework to provide accessibility information to screen readers.

> Microsoft UI Automation is an accessibility framework for Windows. It provides programmatic access to most UI elements on the desktop. It enables assistive technology products, such as screen readers, to provide information about the UI to end users and to manipulate the UI by means other than standard input. UI Automation also allows automated test scripts to interact with the UI.\
[UI Automation Overview](https://learn.microsoft.com/windows/desktop/WinAuto/uiauto-uiautomationoverview)

Uno.UI implements a subset of WinUI's UI Automation APIs to make your applications work with each platform's built-in screen reader or accessibility support:

| Windows  | Android  | iOS       | macOS     | WebAssembly                  |
|----------|----------|-----------|-----------|------------------------------|
| Narrator | TalkBack | VoiceOver | VoiceOver | OS or Web Browser Integrated |

Read [Expose basic accessibility information](https://learn.microsoft.com/windows/uwp/design/accessibility/basic-accessibility-information) to learn how to use the `AutomationProperties` supported by Uno.UI:

- `AutomationProperties.AutomationId`
- `AutomationProperties.Name`
- `AutomationProperties.LabeledBy`
- `AutomationProperties.AccessibilityView`

## SimpleAccessibility mode

While we were trying to replicate WinUI's behavior on iOS and Android, we realized that iOS doesn't allow nested accessible elements to be focused.
For example, if you select a list item, the screen reader will automatically read the accessible name of all inner elements one after the other, but won't let you focus them individually (unlike Windows and Android).

While this behavior comes with its own set of limitations (e.g., you can't nest buttons), it greatly simplifies the implementation of accessibility.
By comparison, on WinUI, the user would need to navigate through every inner element of every list item, unless the developer manually disables focus for each inner element and aggregates their accessible names into a single string to use as the accessible name of the list item.

Instead of trying to replicate WinUI's behavior on iOS (which *might* be doable using the `UIAccessibilityContainer` interface, although we haven't tried it yet), we decided to go along with the iOS behavior and bring it to Android as well. We called this mode SimpleAccessibility.

Here's how to enable it:

```csharp
// App's constructor (`App.cs` or `App.xaml.cs`)
#if __IOS__ || __TVOS__ || __ANDROID__ || __WASM__
FeatureConfiguration.AutomationPeer.UseSimpleAccessibility = true;
#endif
```

We highly recommend using this mode, as iOS still won't let you focus nested accessible elements even if you don't (see known issues).

## Disabling accessibility text scaling

You have the option to disable accessibility text scaling of iOS and Android devices but Apple [recommends to keep text sizes dynamic](https://developer.apple.com/videos/play/wwdc2017/245)

Here's how to disable it

```csharp
// App's constructor (`App.cs` or `App.xaml.cs`)
Uno.UI.FeatureConfiguration.Font.IgnoreTextScaleFactor = true;
```

## AutomationId

The `AutomationProperties.AutomationId` attached property can be used by UI Testing frameworks to find visual elements.

To avoid performance issues, this property only has an effect when either the `IsUiAutomationMappingEnabled` msbuild property, or `Uno.UI.FrameworkElementHelper.IsUiAutomationMappingEnabled` is set to true.

Setting this property does the following:

- On **Android**, it sets the [`View.ContentDescription`](https://developer.android.com/reference/android/view/View.html#setContentDescription(java.lang.CharSequence)) property
- On **iOS**, it sets the [`UIView.AccessibilityIdentifier`](https://developer.apple.com/documentation/uikit/uiaccessibilityidentification/1623132-accessibilityidentifier) property
- On **macOS**, it sets the [`NSView.AccessibilityIdentifier`](https://developer.apple.com/documentation/appkit/nsaccessibility/1535023-accessibilityidentifier) property
- On **WebAssembly**, it sets [`aria-label`](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-label) and the `xamlautomationid` property on the HTML element. The [`role`](https://www.w3.org/WAI/PF/HTML/wiki/RoleAttribute) HTML Attribute is also set based on the XAML view type whose `AutomationProperties.AutomationId` was set.

This property is generally used alongside [Uno.UITest](https://github.com/unoplatform/Uno.UITest) to create UI Tests, and is particularly useful to select items using data-bound identifiers.

## Windows.UI.ViewManagement.AccessibilitySettings

Some external libraries or UI toolkits may depend on the `AccessibilitySettings` class to check for high contrast settings. As Uno Platform targets cannot check for this via accessible APIs, the properties only return predefined defaults, unless you override them manually via `WinRTFeatureConfiguration.Accessibility`:

```csharp
var accessibilitySettings = new AccessibilitySettings();
accessibilitySettings.HighContrast; // default - false
accessibilitySettings.HighContrastScheme; // default - High Contrast Black

// Override the defaults
WinRTFeatureConfiguration.Accessibility.HighContrast = true;
WinRTFeatureConfiguration.Accessibility.HighContrastScheme = "High Contrast White";

accessibilitySettings.HighContrast; // true
accessibilitySettings.HighContrastScheme; // High Contrast White
```

When the value of `WinRTFeatureConfiguration.Accessibility.HighContrast` is changed, the `AccessibilitySettings.HighContrastChanged` event is raised.

## Known issues

- `Hyperlink` in `TextBlock` is not supported.
- `TextBox` and `PasswordBox` don't use `Header` and `PlaceholderText`.
- `ItemsControl` doesn't use `AutomationProperties.Name` on its `DataTemplate`'s root.
- There are XAML code generation conflicts between `x:Name` and `AutomationProperties.Name`.
- A child with the same accessible name as its parent is accessibility focusable.
- `Control` doesn't receive focus when accessibility focused.
- `TabIndex` is not supported.
- On iOS, nested accessible elements are not accessibility focusable.
- On Android, both `ToggleSwitch` and its native `Switch` can be accessibility focused.
- On Android, both `TextBox` and its native `EditText` can be accessibility focused.
- On Android, `Control` without a non-empty accessible name is not accessibility focusable.
- On Android, the accessible name of the native back button can't be customized.
- On Android, `TextBox` and `PasswordBox` don't hint at "double tap to edit".
- On Android, you can tap to focus an accessible child of an accessible element that has never been focused even if `UseSimpleAccessibility` is enabled.
- `AutomationPeer.GetLocalizedControlType()` is not localized.
- `FlipViewItem` reads "double tap to activate" even if it's not interactive.
- Navigating through accessible elements can slow down when the UI is complex.
- You can't cycle through `FlipView` items using accessibility focus.
- There is no way to control or predict accessibility focus following a navigation (page or modal).
- `Control`s don't announce state changes.
- Only the following elements support accessibility:
  - `Button`
  - `CheckBox`
  - `FlipViewItem`
  - `ListViewItem`
  - `HyperlinkButton`
  - `Image`
  - `PasswordBox`
  - `RadioButton`
  - `TextBlock`
  - `TextBox`
  - `ToggleButton`
  - `ToggleSwitch`

- Only the following `AutomationProperties` are supported:
  - `AccessibilityView`
  - `LabeledBy`
  - `Name`

- On Wasm, only the following elements support accessibility:
  - `Button`
  - `CheckBox`
  - `Image`
  - `RadioButton`
  - `TextBlock`
  - `TextBox`
  - `Slider`

- On Wasm, `PasswordBox` is not currently supported due to external limitations.

## Tips

- Always set and localize `AppBarButton.Label` (even if it's not displayed on Android and iOS). It is used by the screen reader for accessibility.
- Always localize `AutomationProperties.Name`. The name of the resource should look like this: `MyButton.[using:Windows.UI.Xaml.Automation]AutomationProperties.Name`.
- Avoid using `Opacity="0"` and `IsHitTestVisible="False"` when you can use `Visibility="Collapsed"`. The screen reader can still focus the former, but not the latter.
- Avoid stacking `TextBlock`s inside  a `Panel` when you can use `Inlines` inside a `TextBlock` (using `LineBreak` if necessary). This allows the screen reader to read all the text at once, instead of having the user select every part manually.
- Use a converter to trim long text. While a `TextBlock` might ellipsize long text, the screen reader will read the entire text provided.
- Avoid creating custom controls when you can use built-in ones. If you must, make sure to implement and provide an appropriate `AutomationPeer`.
- You can disable accessibility focus of native elements using `android:ImportantForAccessibility="No"` and `ios:IsAccessibilityElement="False"`.
- `ContentControl` based controls (`Button`, `CheckBox`, ...) automatically use the string representation of their `Content` property. In order for the `AutomationProperties.AutomationId` property to be selectable, add `AutomationProperties.AccessibilityView="Raw"` to the control as well.

## Enabling the screen reader

### Narrator (Windows)

1. Press **Windows key** and **Enter** at the same time.

### VoiceOver (iOS)

1. Launch the **Settings** app from your Home screen.
2. Tap on **General**.
3. Tap on **Accessibility**.
4. Tap on **VoiceOver** under the Vision category at the top.
5. Tap the **VoiceOver switch** to enable it.

### TalkBack (Android)

1. Launch the **Settings** app from your launch screen.
2. Tap on **Accessibility**.
3. Tap on **TalkBack**.
4. Tap the **switch** to enable it.
5. Tap the **OK** button to close the dialog.

### VoiceOver (macOS)

1. Launch the **System Preferences** from the macOS logo.
2. Tap on **Accessibility**.
3. Tap on **VoiceOver** under the Vision category at the top.
4. Tap the **Enable VoiceOver switch** to enable it.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/working-with-animations.md

---
uid: Uno.Features.Animations
---

# Animations

Uno Platform supports [storyboarded animations](https://learn.microsoft.com/windows/apps/design/motion/storyboarded-animations). A number of animation types are supported, including `DoubleAnimation`, `ColorAnimation`, and key frame-based animations.

## General guidelines

1. GPU-bound animations are supported for the following properties:
    * `Opacity`
    * `RenderTransform` of type `TranslateTransform`, `RotateTransform`, `ScaleTransform`, or `CompositeTransform`. Transforms cannot be part of a TransformGroup.
1. When animating a `Transform`, you can animate only one property at a time (i.e. `CompositeTransform.TranslateX` *or* `CompositeTransform.TranslateY`),
1. You cannot reuse a `Transform` or an `Animation` declared in resources on multiple controls (instead you have to put your animation in a `Template`)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/working-with-assets.md

---
uid: Uno.Features.Assets
---

# Assets and image display

Uno Platform automatically processes assets from your app's project and makes them available on all platforms.

Support for automatically generating assets in multiple resolutions from SVG or PNG is also provided using [Uno.Resizetizer](xref:Uno.Resizetizer.GettingStarted).

Platform-specific assets such as [`BundleResource`](https://learn.microsoft.com/xamarin/ios/user-interface/controls/image) and [`AndroidAssets`](https://learn.microsoft.com/xamarin/android/app-fundamentals/resources-in-android/android-assets) are also supported on the heads, when required.

## Supported asset types

At the moment, the following image file types are supported as `Content` assets:

|             | `.bmp` (Win BMP) | `.gif`‡ | `.heic` (Apple) | `.jpg` & `.jpeg` (JFIF) | `.png` | `.webp` | `.pdf` | `.svg` |
| ----------- | :-------------: | :---: | :-----------: | :-----------------: | :--: | :---: | :--: | :--: |
| WinUI       |       ✔️        |   ✔️   |       ❌       |          ✔️          |  ✔️   |   ✔️   |  ❌   |  ✔️   |
| Android 10  |       ✔️        |  ✔️‡   |       ✔️       |          ✔️          |  ✔️   |   ✔️   |  ✔️   |  ✔️   |
| iOS 13      |       ✔️        |  ✔️‡   |       ✔️       |          ✔️          |  ✔️   |   ❌   |  ❌   |  ✔️   |
| macOS       |       ✔️        |  ✔️‡   |       ✔️       |          ✔️          |  ✔️   |   ❌   |  ✔️   |  ❌   |
| WebAssembly†       |       ✔️        |  ✔️‡   |      ❌†       |          ✔️          |  ✔️   |  ❌†   |  ❌†  |  ✔️   |
| Skia WPF    |       ✔️        |  ✔️‡   |       ❌       |          ✔️          |  ✔️   |   ✔️   |  ❌   |  ✔️   |

* † Actual WebAssembly image format support is browser dependent. For example, `.webp` is not working on Safari on macOS, but works on Chromium-based browsers. Check-marks (✔️) indicates a format that can safely expected to work on all browsers able to run Wasm applications.
* ‡ **Gif animation support**:
  * Play/Pause not implemented in Uno yet
  * Always animated on Wasm
  * Not animated on other Uno platforms

## Adding an asset to your project

This is just like adding an asset to a WinUI project.

1. Add an image file to the `Assets` directory of the solution's app project.
2. Select the item and set the build action to `Content`, if not already set.

## Referencing an asset

Use assets added to your project with the `ms-appx:///` scheme.

See the examples below for XAML:

```xml
<!-- Relative path without a leading '/' uses assets from the library where the XAML is located -->
<Image Source="Assets/MyImage.png" />
<!-- Explicitly qualify the asset, when used from multiple project libraries -->
<Image Source="ms-appx:///[MyApp]/Assets/MyImage.png" />
```

> [!NOTE]
> For [single project solutions](https://platform.uno/docs/articles/migrating-to-single-project.html#project-structure), the `[MyApp]` qualifier is not required when explicitly qualifying the asset.

```xml
<Image Source="ms-appx:///Assets/MyImage.png" />
```

Or

```xml
<Image Source="ms-appx:///Assets/Images/MyImage.png" />
```

For Uno's latest project template where images are saved in the `Images` folder.

### Referencing an asset from code

You can also reference assets from code using the `ms-appx:///` scheme. For example:

```xaml
<Image x:Name="MyImage" />
```

```csharp
// from XAML code behind
MyImage.Source = "ms-appx:///Assets/MyImage.png";
```

or using bindings:

```csharp
// from a ViewModel
public string ImagePath { get; set ;} = "ms-appx:///Assets/MyImage.png";
```

```xaml
<Image Source="{x:Bind ImagePath}" />
```

You can also get assets directly using [StorageFile.GetFileFromApplicationUriAsync](xref:Uno.Features.FileManagement#support-for-storagefilegetfilefromapplicationuriasync).

## Qualify an asset

When developing Windows apps, developers can load different assets at runtime based on attributes that qualify their visibility in the app's UX. This allows you to tailor your app to different contexts to better suit users' hardware or language preferences.

For instance, such **qualifiers** can selectively load different assets depending on scale, language, theme preferences, etc. This feature is notably useful when supporting high DPI screens or the norms of differing regions.

> [!NOTE]
> To become more familiar with qualifiers, check out Microsoft's documentation for a conceptual overview of the feature:
> [Microsoft: Tailor your resources for language, scale, high contrast, and other qualifiers](https://learn.microsoft.com/windows/apps/windows-app-sdk/mrtcore/tailor-resources-lang-scale-contrast)

Uno Platform allows you to use the same feature on multiple platforms. However, only a subset of those qualifiers currently have support.

### Table of scales

Not all scales are supported on all platforms:

| Scale | WinUI       | iOS/tvOS | Android |
|-------|:-----------:|:---------------:|:-------:|
| `100` | scale-100   | @1x             | mdpi    |
| `125` | scale-125   | N/A             | N/A     |
| `150` | scale-150   | N/A             | hdpi    |
| `200` | scale-200   | @2x             | xhdpi   |
| `300` | scale-300   | @3x             | xxhdpi  |
| `400` | scale-400   | N/A             | xxxhdpi |

We recommend including assets for each of these scales: `100`, `150`, `200`, `300`, and `400`. Only compatible scales will be included in each platform.

> [!NOTE]
> In the Android head project (via the csproj), you can set the `UseHighDPIResources` property to `False` in debug. In those cases, only assets with scale `100` (mdpi) and scale `150` (hdpi) will be included. This reduces deployment time when debugging as fewer assets are processed and transferred to the device or simulator.

#### Examples

```paths
\Assets\Images\logo.scale-100.png
\Assets\Images\logo.scale-200.png
\Assets\Images\logo.scale-400.png

\Assets\Images\scale-100\logo.png
\Assets\Images\scale-200\logo.png
\Assets\Images\scale-400\logo.png
```

### Language

Use it as you would on WinUI/UWP, but keep in mind that some language or region combinations might not work on all platforms.

The following languages have been verified to work on all platforms:

-`en`
-`en-US`
-`en-CA`
-`fr`
-`fr-FR`
-`fr-CA`
-`es`

#### Examples

```paths
\Assets\Images\en\logo.png
\Assets\Images\fr\logo.png
\Assets\Images\es\logo.png

\Assets\Images\logo.language-en.png
\Assets\Images\logo.language-fr.png
\Assets\Images\logo.language-es.png
```

### Dark theme support

> [!TIP]  
> Supported on Android only

A theme qualifier can be specified for the image loader to use an asset based on the current app theme.

#### Examples

```paths
/Assets/theme-light/ThemeTestImage.png
/Assets/theme-dark/ThemeTestImage.png
```

### Custom (platform)

Sometimes, you might want to use a different asset depending on the platform. Because there is no `platform` qualifier on WinUI/UWP, Uno Platform provides the `custom` qualifier.

| Platform | Qualifier value |
|----------|-----------------|
| UWP      | `uwp`           |
| iOS      | `ios`           |
| Android  | `android`       |

Because the `custom` qualifier has no special meaning on WinUI/UWP, we have to interpret its value manually.

On iOS and Android, Uno.UI's `RetargetAssets` task automatically interprets these values and excludes unsupported platforms.

On UWP, you must add the following code to your `App.cs` or `App.xaml.cs` constructor:

```csharp
#if WINDOWS_UWP
    Windows.ApplicationModel.Resources.Core.ResourceContext.SetGlobalQualifierValue("custom", "uwp");
#endif
```

#### Examples

```paths
\Assets\Images\custom-uwp\logo.png
\Assets\Images\custom-ios\logo.png
\Assets\Images\custom-android\logo.png

\Assets\Images\logo.custom-uwp.png
\Assets\Images\logo.custom-ios.png
\Assets\Images\logo.custom-android.png
```

## Android: setting a custom image handler

On Android, to handle the loading of images from a remote URL, the Image control has to be provided a
`ImageSource.DefaultImageLoader`, such as the [Android Universal Image Loader](https://github.com/nostra13/Android-Universal-Image-Loader).

This package is installed by default when using the [Uno Cross-Platform solution templates](https://marketplace.visualstudio.com/items?itemName=unoplatform.uno-platform-addin-2022). If not using the solution template. You can install the [nventive.UniversalImageLoader](https://www.nuget.org/packages/nventive.UniversalImageLoader/) NuGet package and call the following code from your application's App constructor:

```csharp
private void ConfigureUniversalImageLoader()
{
    // Create global configuration and initialize ImageLoader with this config
    ImageLoaderConfiguration config = new ImageLoaderConfiguration
        .Builder(Context)
        .Build();

    ImageLoader.Instance.Init(config);

    ImageSource.DefaultImageLoader = ImageLoader.Instance.LoadImageAsync;
}
```

## iOS/tvOS: referencing bundle images

On iOS/tvOS, bundle images can be selected using "bundle://" (e.g. bundle:///SplashScreen). When selecting the bundle resource, do not include the zoom factor, nor the file extension.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/working-with-codespaces.md

---
uid: Uno.Features.Codespaces
---

# Using Codespaces

## Developing an Uno App using Codespaces

The easiest way to get started is to visit the [Uno.QuickStart](https://github.com/unoplatform/Uno.QuickStart) repository. It allows you to get started with minimal configuration or project creation steps.

To create a new Codespace, visit [GitHub Codespaces](https://github.com/codespaces).

### Developing for WebAssembly

1. Install the suggested [Uno Platform extension](https://marketplace.visualstudio.com/items?itemName=unoplatform.vscode)
1. Open the command palette (Ctrl+Shift+P) and execute the `Run uno-check` command to install the appropriate .NET SDK
1. Open the command palette (Ctrl+Shift+P) and run the `Install the dotnet new templates` command to install the dotnet new templates
1. Once the C# environment is setup, with the command palette use the command "Omnisharp: Select project" (or click on the project name in the status bar)
1. Select the `MyApp` project
1. Using a terminal, navigate to the `MyApp` folder
1. Type `dotnet run -f net9.0-browserwasm`
1. Once the compilation is done, a server will open on port 5000
1. In the **Ports** tab (next to the Terminal tab), right click to make both the port 5000 and the other dotnet opened port (with `uno.winui.devserver` or `uno.ui.remotecontrol` in the running process column) to "public".
   > Failure to make both ports public will prevent the app from starting properly.
1. Codespaces will suggest to open a new browser window or as a preview window

You can now use C# Hot Reload and XAML Hot Reload to develop your application.

See [the VS Code Getting started](../get-started-vscode.md) documentation for additional details about developing with VS Code.

### Creating your Codespace from scratch

If you want to start from an empty repository, follow these steps:

1. Create an empty repository
1. Install the [`unoplatform.vscode extension`](https://marketplace.visualstudio.com/items?itemName=unoplatform.vscode) from the Extensions activity
1. Open the command palette (Ctrl+Shift+P) and execute the `Run uno-check` command to install the appropriate .NET SDK
1. Open the command palette (Ctrl+Shift+P) and run the `Install the dotnet new templates` command to install the dotnet new templates
1. Open a terminal and create a new project using the following command:

    ```dotnetcli
    dotnet new unoapp -o MyApp -ios=false -android=false -macos=false -skia-tizen=false -skia-wpf=false -skia-linux-fb=false --vscode
    ```

1. Using the Codespaces top left menu, open the `MyApp` folder

You're ready to develop for WebAssembly.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/working-with-cookies.md

---
uid: Uno.Features.Cookies
---

# Working with cookies

In the case of WebAssembly, you may need to work with the browser cookies to either read or set values with expiration support. For these purposes, Uno Platform provides the `Uno.Web.Http.CookieManager` class.

## Prerequisites

All types related to cookie management are WebAssembly-specific and reside in the `Uno.Web.Http` namespace. When writing code which uses these types, you must wrap it in `#if __WASM__` blocks and either fully qualify these types (e.g. `Uno.Web.Http.Cookie` or `Uno.Web.Http.SetCookieRequest`) or add a using statement to the top of the file, wrapped within `#if`, as follows:

```csharp
#if __WASM__
using Uno.Web.Http;
#endif
```

## Setting a cookie

To set a cookie, create an instance of `Uno.Web.Http.SetCookieRequest` and initialize the values you are interested in. The following cookie attributes are supported:

- Name
- Value
- Path
- Domain
- Max-age
- Expires
- Secure
- SameSite

Then set the cookie using the `SetCookie` method.

```csharp
#if __WASM__

var cookie = new Cookie("MyCookie", "somevalue");
var request = new SetCookieRequest(cookie)
{
    Path = "/",
    Expires = DateTimeOffset.UtcNow.AddDays(2),
    Secure = true,
};

CookieManager.GetDefault().SetCookie(request);

#endif

```

> [!NOTE]
> If your cookie contains special characters, you may use `Uri.EscapeDataString` to escape those characters when setting the cookie and later use `Uri.UnescapeDataString` to decode them.

## Getting active cookies

To retrieve the active cookies, use the `GetCookies` method:

```csharp
#if __WASM__

var cookies = CookieManager.GetDefault().GetCookies();
foreach (var cookie in cookies)
{
    Debug.WriteLine(cookie.Name);
    Debug.WriteLine(cookie.Value);
}

#endif

```

> [!NOTE]
> Browser only provides the `Name` and `Value` properties for reading. Other attributes can be only used as part of the `SetCookie` request.

## Deleting a cookie

To delete a cookie, provide its `Name` and optionally the `Domain` and `Path` to the `DeleteCookie` method:

```csharp
#if __WASM__

CookieManager.GetDefault().DeleteCookie("MyCookie", path: "/");

#endif
```

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/working-with-gitpod.md

---
uid: Uno.Features.Gitpod
---

# Using Ona

## Developing an Uno App using Ona

The easiest way to get started is to visit the [Uno.QuickStart](https://github.com/unoplatform/Uno.QuickStart) repository. It allows you to get started with minimal configuration or project creation steps.

### Creating the environment from scratch

If you want to start from an empty repository, follow these steps:

1. Create an empty repository
1. Create a file named `.gitpod.yml` at the root of the repository, and set it to the following

    ```yml
    image:
      file: .gitpod.Dockerfile

    tasks:
      # Mitigation for https://github.com/gitpod-io/gitpod/issues/6460 
      - name: Postinstall .NET 6.0 and dev certificates
        init: |
          mkdir -p $DOTNET_ROOT && curl -fsSL https://dot.net/v1/dotnet-install.sh | bash /dev/stdin --channel $DOTNET_VERSION --install-dir $DOTNET_ROOT 
          dotnet dev-certs https 
    ```

1. Create a file named `.gitpod.Dockerfile`, with the following content:

    ```dockerfile
    FROM gitpod/workspace-dotnet-vnc

    USER gitpod
    #.NET installed via .gitpod.yml task until the following issue is fixed: https://github.com/gitpod-io/gitpod/issues/5090
    ENV DOTNET_VERSION=6.0
    ENV DOTNET_ROOT=/workspace/.dotnet
    ENV PATH=$DOTNET_ROOT:$PATH
    ```

1. Commit these changes and open a Ona workspace
1. Install the `unoplatform.vscode` extension from [OpenVSX](https://open-vsx.org/extension/unoplatform/vscode)
1. Open the command palette (Ctrl+Shift+P) and run the `Install the dotnet new templates` command to install the dotnet new templates
1. Create a new project using the following command:

    ```dotnetcli
    dotnet new unoapp -o MyApp -ios=false -android=false -macos=false -skia-tizen=false -skia-wpf=false -skia-linux-fb=false --vscode
    ```

1. Using the Ona top left menu, open the `MyApp` folder

You're ready to develop for WebAssembly or the Linux desktop (Skia Desktop).

## Contributing to Uno using Ona

To contribute to Uno using Ona:

1. [![Open Uno in Ona](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/unoplatform/uno)
1. In the opened shell, type the following to build the Uno solution:

    ```bash
    build/gitpod/build-wasm.sh
    ```

    The build should end without any errors
1. If you want to enable XAML Hot Reload, open another shell, then run:

    ```sh
    build/gitpod/serve-remote-control.sh
    ```

1. Open another shell, then start the Uno http server:

    ```sh
    build/gitpod/serve-sampleapp-wasm.sh
    ```

Once the server is started, Ona will automatically open a browser window on the side to show the sample application.

You can make your changes in XAML directly, to view the changes through Hot Reload. If you make changes in the code, you'll need to rerun the `build-wasm.sh` script, then refresh the browser section on the side.

Once you're done with your changes, make a Pull Request through the [Gitpod's GitHub integration](https://www.gitpod.io/docs/58_pull_requests/) and let us know about it on our [Discord Server](https://platform.uno/discord)!

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/working-with-strings.md

---
uid: Uno.Features.Localization
---

# String resources and localization

> [!TIP]
> Relevant tutorials on this topic:
>
> - [How to localize text resources](xref:Uno.Tutorials.Localization)
> - [How to change app language at runtime](xref:Uno.Tutorials.ChangeAppLanguage)

Localization is done through the `resw` files in the current project. Normally, you would put these files in the `strings/[lang]` folder in the `[AppName]` project.  Resources are then referenced using [`x:Uid`](https://learn.microsoft.com/windows/uwp/xaml-platform/x-uid-directive).

See the WinUI documentation on [localizing strings in your UI](https://learn.microsoft.com/windows/uwp/app-resources/localize-strings-ui-manifest).

Resources may be placed in the default scope file `Resources.resw`, or in a custom-named file. Custom-named file content
can be used with the `x:Uid="/myResources/MyResource"` format, see [how to factor strings into multiple resource files](https://learn.microsoft.com/windows/uwp/app-resources/localize-strings-ui-manifest#factoring-strings-into-multiple-resources-files).

Note that the default language can be defined using the `DefaultLanguage` MSBuild property, using an IETF Language Tag (e.g. `en` or `fr-FR`).

By default, the app will use the operating system's language first, falling back to the `DefaultLanguage` second. If you would like to change localization at the app level, you can use the [`ApplicationLanguages.PrimaryLanguageOverride`](https://learn.microsoft.com/uwp/api/windows.globalization.applicationlanguages.primarylanguageoverride?view=winrt-22621) property:

```csharp
ApplicationLanguages.PrimaryLanguageOverride = "fr-CA"; // or, any IETF language tag
```

Note that changing the `PrimaryLanguageOverride` will not retroactively update any loaded pages. You will need to reload the page or navigate to a new one.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/uno-development/working-with-the-samples-apps.md

---
uid: Uno.Contributing.SamplesApp
---

# Using the SamplesApp

The SamplesApp in Uno.UI is an Uno application containing a large number of UI and non-UI samples. It serves a few purposes:

* Allow for manually testing new features and investigating bugs,
* Provide UI for [automated UI tests](creating-ui-tests.md),
* Allow automated comparison of static snapshots between Uno versions,
* Document the functionality supported by Uno.

This article details how to run SamplesApp and how to add a new sample.

For instructions on working with automated UI tests, [go here](creating-ui-tests.md).

## Running SamplesApp

The SamplesApp from latest master branch for WebAssembly is available online: https://aka.platform.uno/wasm-samples-app

To run the SamplesApp locally:

1. Ensure [your environment is configured](xref:Uno.GetStarted.vs2022) for the platform you want to run on.
2. Open Uno.UI with the [correct target override and solution filter](building-uno-ui.md) for the platform you want to run on.
3. Select `SamplesApp.[Platform]` as the startup app. (Eg, `SamplesApp.iOS` if you're running on iOS.)
4. If you're testing on a mobile platform, use a tablet if possible, as the app is optimized for a tablet layout.
5. Run SamplesApp.

If everything builds successfully, the app will run. The app is a collection of samples, grouped into categories. You can navigate to a sample using the menu on the left.

![SamplesApp main view](assets/SamplesApp.png)

### Running-debugging the WebAssembly app on a mobile device

By default, SamplesApp starts in debugging mode on localhost, making it inaccessible from external devices, even if they are on the same network. To remedy this, you can utilize Visual Studio Dev Tunnels to establish an externally accessible URL for your application. For more details, refer to the [Microsoft Learn documentation](https://learn.microsoft.com/aspnet/core/test/dev-tunnels). If the option doesn't appear initially, consider running a rebuild of the `SamplesApp.Wasm` project.

## Sample organization

Samples are located in the [`UITests.Shared` project](https://github.com/unoplatform/uno/tree/master/src/SamplesApp/UITests.Shared). UI-related samples are generally grouped by control, or by functional area for samples that aren't specific to a particular control (eg `VisualStateTests`). Non-UI samples are generally grouped by namespace of the tested feature.

Note that there's no 'master list' of samples. Instead, individual samples are tagged with `SampleAttribute`, and the SamplesApp automatically picks up all samples using the attribute.

### SampleAttribute

`SampleAttribute` accepts one or more optional categories, as well as an optional `Name` and `Description`, and a `ViewModelType` property which can be used to set a `Type` which will be instantiated and used as the `DataContext` of the sample control. If a category and/or a name aren't explicitly set, then the sample name and category will be automatically determined from the class name and the last part of the namespace.

**Examples:**

In the first example, no parameters are supplied to the `Sample` attribute. The sample will be included under the name `ToolTip_Long_Text`, in the `ToolTip` category.

```csharp
namespace UITests.Windows_UI_Xaml_Controls.ToolTip
{
 [Sample]
 public sealed partial class ToolTip_Long_Text : UserControl
```

In the second example, the category and name are manually specified, and a view-model type is specified to use as the `DataContext` of the sample.

```csharp
namespace UITests.Windows_Devices.Haptics
{
 [Sample("Windows.Devices", Name = "Haptics.VibrationDevice", ViewModelType = typeof(VibrationDeviceTestsViewModel))]
 public sealed partial class VibrationDeviceTests : Page
```

## Adding a new sample

To add a new sample to the SamplesApp:

1. Locate the folder corresponding to the control or class you want to create a sample for in the `UITests.Shared` project. The folder structure is typically `Namespace_In_Snake_Case/ControlNameTests`.
2. Create a new `UserControl` from the Visual Studio templates, with a meaningful name.
3. Add your sample UI to the `UserControl`.
4. Add the `[Uno.UI.Samples.Controls.Sample]` attribute to the class in the code-behind partial file.
5. **CRITICAL: Register your XAML file in `UITests.Shared.projitems`**
   * Open `src/SamplesApp/UITests.Shared/UITests.Shared.projitems`
   * Add an entry for your XAML page and code-behind file:

     ```xml
     <Page Include="$(MSBuildThisFileDirectory)YourFolder\YourSample.xaml">
       <SubType>Designer</SubType>
       <Generator>MSBuild:Compile</Generator>
     </Page>
     <Compile Include="$(MSBuildThisFileDirectory)YourFolder\YourSample.xaml.cs">
       <DependentUpon>YourSample.xaml</DependentUpon>
     </Compile>
     ```

   * **Without this step, your sample will NOT be visible in SamplesApp**
6. Double-check that the category name matches other samples for the control.
7. Run the `SamplesApp` to check that your sample appears in the browser and works as expected.

## Adding a manual test sample

Some tests cannot be validated automatically, and need to be flagged with the `IsManualTest` property on `SampleAttribute`. These tests will be filtered in the Samples App to be validated by a human.

The content of those tests must describe a scenario to follow, what to expect, and which exceptional conditions may need to be validated. If the result is visual, an image or video resource file may be needed as well.

## Sample snapshots on the CI

Each CI build of Uno.UI records screenshots of each sample in the SamplesApp. A diff tool details screenshots that have changed from the previous master build, allowing unexpected changes in the visual output to be caught.

### Running the snapshot taker locally on WebAssembly

The WebAssembly head has the ability to be run through puppeteer, and displays all tests in sequence. Puppeteer runs a headless version of Chromium, suited for running tests in a CI environment.

To run the tests:

* Navigate to the `SamplesApp.Wasm.UITests` folder and run `npm i`. This will download Puppeteer and the Chrome driver.
* Build the `SamplesApp.Wasm.UITests.njsproj` project
* Press `F5`, node will start and run the tests sequentially
* The screen shots are placed in a folder named `out`

Note that the same operation is run during the CI, in a specific job running under Linux. The screen shots are located in the Unit Tests section under `Screenshots Compare Test Run` as well as in the build artifact.

## Validating the WebAssembly UI Tests results

In the CI build, an artifact named `wasm-uitests` is generated and contains an HTML file that shows all the differences
for screenshots taken for the past builds. Download this artifact and open the html file to determine if any screenshots
have changed.

### Troubleshooting the tests

It is possible to enable the chromium head using the configuration parameters in the [app.ts](https://github.com/unoplatform/uno/blob/master/src/SamplesApp/SamplesApp.Wasm.UITests/app.ts) file.

## Creating performance benchmarks with BenchmarkDotNet

Performance is measured using [BenchmarkDotNet](https://benchmarkdotnet.org/), in the suite located in the `SamplesApp.Benchmarks` shared project.

A few points to consider when adding benchmarks:

* Make a folder using the namespace separated by `_`
* Avoid putting a large number of benchmarks in a single class. Those tests are run synchronously under
WebAssembly, and this will allow for progress reporting to be visible.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/working-with-themes.md

---
uid: Uno.Features.Themes
---

# Supporting Dark and High Contrast themes

Uno Platform offers fine-grained customization of typography, corner radius, and styling of UI elements to convey a brand identity in your application. However, platforms like iOS, Android, and web browsers also offer a system-wide color mode that users can change. For instance, Windows uses **Light mode** by default, but many users prefer **Dark mode** which is intended to be easier on the eyes in low-light conditions. Many platforms also offer a **High Contrast mode** to make things easier to see.

These themes affect both the `Background` and `Foreground` colors to accommodate user preferences. All of the color modes mentioned above are available for use in your app. This guide will detail how to change the system theme setting, make your app receive change notifications for it, and react to those changes at runtime.

> [!Video https://www.youtube-nocookie.com/embed/FXHUiHjgAQ4]

## Enable dark mode

As in WinUI, the possible values `Light`, `Dark`, and `HighContrast` correspond to a value users can select in the settings of their respective platforms.

High Contrast mode is often available to enable separately, from a dedicated _Accessibility_ page. For the purpose of this documentation, we will assume the user wants to use Dark mode.

### [**Windows**](#tab/windows)

Windows PCs can enable Dark mode from Windows Settings. See [Change colors in Windows](https://support.microsoft.com/windows/change-colors-in-windows-d26ef4d6-819a-581c-1581-493cfcc005fe) for more information.

### [**iOS**](#tab/ios)

Devices running iOS or iPadOS can enable Dark mode from Control Center or Settings. See [Use Dark Mode on your iPhone and iPad](https://support.apple.com/HT210332) for more information.

### [**Android**](#tab/android)

Android devices can enable Dark mode from Settings. See [Change to dark or color mode on your Android device](https://support.google.com/android/answer/9730472) for more information.

### [**Browser**](#tab/browser)

The steps to enable Dark mode in a browser vary by browser. See the following guides for more information:

- [Browse in dark mode or Dark theme (Chrome)](https://support.google.com/chrome/answer/9275525)
- [Use the dark theme in Microsoft Edge](https://support.microsoft.com/microsoft-edge/use-the-dark-theme-in-microsoft-edge-9b74617b-f542-77ed-033b-1a5cfb17a2df)
- [Use themes to change the look of Firefox](http://mzl.la/1BAQGDX)

---

## React to OS theme changes

When you change the theme mode on your device, the system will send a notification to your app. The colors of UI elements in your app will automatically switch over as long as you do _not_ specify a theme in any of the following places:

- `App` constructor
- `App.xaml`
- The `RequestedTheme` property of a parent `FrameworkElement`

However, your app can still react manually to changes in the theme mode. To do so, you can use the [Uno.CommunityToolkit.WinUI.UI](https://www.nuget.org/packages/Uno.CommunityToolkit.WinUI.UI) NuGet package. This package is not required to change the app color theme, but it contains a `ThemeListener` class that can be used to listen for OS theme changes. To actually change the app color theme at runtime, you need to install the [Uno.Toolkit.WinUI](https://www.nuget.org/packages/Uno.Toolkit.WinUI) NuGet package which contains a `SystemThemeHelper` class.

Below is an example of how to use these classes to change the app theme at runtime based on a raised event:

```csharp
using CommunityToolkit.WinUI.UI.Helpers;
using Uno.Toolkit.UI;

namespace MyApp.UI.Views;

public class MainPage : Page
{
    public MainPage()
    {
        this.InitializeComponent();

        ThemeListener.Current.ThemeChanged += OnThemeChanged;
    }

    private void OnThemeChanged(ThemeListener sender)
    {
        var theme = SystemThemeHelper.IsRootInDarkMode(this.XamlRoot) ? ElementTheme.Light : ElementTheme.Dark;

        SystemThemeHelper.SetApplicationTheme(this.XamlRoot, theme);
    }
}
```

## Change the app theme at runtime

The [`SystemThemeHelper.SetApplicationTheme`](https://github.com/unoplatform/uno.toolkit.ui/blob/main/src/Uno.Toolkit.UI/Helpers/SystemThemeHelper.cs) method from `Uno.Toolkit.UI` can also be used to support an in-app toggle for dark mode. For example, you could add a toggle button to your app's settings page that allows the user to switch between light and dark modes. The following code snippet shows how to implement this:

```csharp
using Uno.Toolkit.UI;

namespace MyApp.UI.Views;

public class SettingsPage : Page
{
    public SettingsPage()
    {
        this.InitializeComponent();

        this.Loaded += OnLoaded;
    }

    private void OnLoaded(object sender, RoutedEventArgs e)
    {
        this.DarkModeToggle.IsOn = SystemThemeHelper.IsRootInDarkMode(this.XamlRoot);
    }

    private void OnDarkModeToggleToggled(object sender, RoutedEventArgs e)
    {
        var theme = DarkModeToggle.IsOn ? ElementTheme.Light : ElementTheme.Dark;

        SystemThemeHelper.SetApplicationTheme(this.XamlRoot, theme);
    }
}
```

## Change the app theme at startup

Another method to change the app theme is to adjust it immediately upon startup. The following must only be called in the `App` class constructor.

```csharp
public App()
{
    this.InitializeComponent();

#if HAS_UNO
    Uno.UI.ApplicationHelper.RequestedCustomTheme = nameof(ApplicationTheme.Dark);
#else
    this.RequestedTheme = ApplicationTheme.Dark;
#endif
}
```

## See also

- [Uno Toolkit](https://www.github.com/unoplatform/uno.toolkit.ui)
- [Theme Listener](https://learn.microsoft.com/windows/communitytoolkit/helpers/themelistener)
- [High Contrast Themes](https://learn.microsoft.com/windows/apps/design/accessibility/high-contrast-themes)

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/features/working-with-xaml-hot-reload.md

---
uid: Uno.Features.HotReload
---

# Hot Reload

The Uno Platform **Hot Reload** feature provides a way to modify the XAML and C# of your running application, in order to iterate faster on UI or code changes. This makes the inner developer loop faster.

**Hot Reload** is part of the **Uno Platform Studio**, a suite of tools designed to streamline your cross-platform app development and boost productivity.

[➜ Learn more about Uno Platform Studio](xref:Uno.Platform.Studio.Overview)

## Features

- Supported in **Visual Studio** (Windows), **VS Code** (Linux, macOS, Windows, and CodeSpaces), and **Rider** (Linux, macOS, Windows).
- XAML and [C# Markup](xref:Uno.Extensions.Markup.Overview) Hot Reload for **iOS, Android, WebAssembly, and Skia (X11, Windows, macOS and FrameBuffer)**.
- All **[C# of Hot Reload](https://learn.microsoft.com/visualstudio/debugger/hot-reload)** in both Visual Studio, VS Code and Rider. See [supported code changes](https://learn.microsoft.com/visualstudio/debugger/supported-code-changes-csharp).
- **Simulator and physical devices** support.
- **Hot Reload Indicator** visuals for an enhanced development experience on Uno Platform targets (not currently supported on WinAppSDK target).
- What can be Hot Reloaded:
  - **XAML files** in the **main project** and **referenced projects libraries**
  - **C# Markup controls**
  - **Bindings**
  - **x:Bind expressions**
  - **App.xaml** and **referenced resource dictionaries**
  - **DataTemplates**
  - **Styles**
  - Extensible [**State restoration**](xref:Uno.Contributing.Internals.HotReload)
  - Support for partial **tree hot reload**, where modifying a `UserControl` instantiated in multiple locations will reload it without reloading its parents.

Hot Reload features are now consistent across platforms and IDEs, but with some debugger-specific variations. You can check below the list of currently supported features.

For existing applications, take this opportunity to update to the [latest **Uno.Sdk** version](https://www.nuget.org/packages/Uno.Sdk/latest) to take advantage of all the latest improvements and support. Refer to our [migration guide](xref:Uno.Development.MigratingFromPreviousReleases) for upgrade steps.

> [!IMPORTANT]
> When upgrading to **Uno.Sdk 5.5 or higher**, the `EnableHotReload()` method in `App.xaml.cs` is deprecated and should be replaced with `UseStudio()`.

## How to use Hot Reload

### [**Visual Studio**](#tab/vswin)

- Setup your environment by following our [getting started guides](xref:Uno.GetStarted.vs2022).
- Start your application (with or without the debugger, depending on the supported features below).
- Make changes to your XAML or C# code, save your file then press the red flame button in the toolbar or use `Alt+F10`.
  
  ![Hot Reload button](../Assets/features/hotreload/hot-reload-button.png)
  
### [**Visual Studio Code**](#tab/vscode)

- Setup your environment by following our [getting started guide](xref:Uno.GetStarted.vscode).
- Start the application (with or without the debugger, depending on the supported features below).
- Wait a few seconds for the hot reload engine to become available (see our troubleshooting tips below).
- Make changes to your XAML or C# code, then save your file.

### [**Rider**](#tab/rider)

- Setup your environment by following our [getting started guide](xref:Uno.GetStarted.Rider).
- Start the application without the debugger.
- Wait a few seconds for the hot reload engine to become available (see our troubleshooting tips below).
- Make changes to your XAML or C# code, then save your file.

---

> [!IMPORTANT]
> Using [.NET 9](https://dotnet.microsoft.com/download/dotnet/9.0) or later (`net9.0` in the `TargetFrameworks` property) is required for Hot Reload to be available when your solution contains iOS, Android, or WebAssembly project heads. On Windows, [Visual Studio 17.12](https://visualstudio.microsoft.com/vs) or later is required.

## Supported features per OS

<!-- Styles applied specifically to the following tables -->
<style>
    /* Center all non-first-column content horizontally */
    table th:not(:first-child),
    table td:not(:first-child) {
        text-align: center !important;
    }

    /* Ensure ALL table cells are vertically centered */
    table th,
    table td {
        vertical-align: middle !important;
        display: table-cell !important;
    }

    /* Keep first column text left-aligned */
    table td:first-child {
        text-align: left;
    }

    /* Specifically center the '🐞 Debugger' text in the first column header */
    table th:first-child {
        text-align: center !important;
    }
</style>

### [**Windows**](#tab/windows)

<table>
    <thead>
        <tr>
            <th></th>
            <th colspan="2">Visual Studio</th>
            <th colspan="2">VS Code</th>
            <th colspan="2">Rider</th>
        </tr>
        <tr>
            <th>🐞 Debugger</th>
            <th>With</th>
            <th>Without</th>
            <th>With</th>
            <th>Without</th>
            <th>With</th>
            <th>Without</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Desktop<br /><small><code>net9.0-desktop</code></code></small></td>
            <td>✅</td><td>✅</td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>✅</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>✅</td>
        </tr>
        <tr>
            <td>Desktop - WSL<br /><small><code>net9.0-desktop</code></small></td>
            <td>⌛<sup><a href="#hr-footnotes">[1]</a></sup></td><td>⌛<sup><a href="#hr-footnotes">[1]</a></sup></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>✅</td>
            <td>❌<sup><a href="#hr-footnotes">[2]</a></sup><sup><a href="#hr-footnotes">[6]</a></sup></td><td>❌<sup><a href="#hr-footnotes">[2]</a></sup></td>
        </tr>
        <tr>
            <td>iOS<br /><small><code>net9.0-ios</code></small></td>
            <td>✅</a></sup></td><td>❌</td>
            <td>🛜</a></td><td>🛜</td>
            <td>❌</a></td><td>✅</td>
        </tr>
        <tr>
            <td>Android<br /><small><code>net9.0-android</code></small></td>
            <td>✅</td><td>❌</td>
            <td>✅</a></td><td>✅</td>
            <td>❌</a></td><td>✅</td>
        </tr>
        </tr>
        <tr>
            <td>WinAppSDK<br /><small><code>net9.0-windows10.x.x</code></small></td>
            <td>✅<sup><a href="#hr-footnotes">[3]</a></sup></td><td>✅<sup><a href="#hr-footnotes">[4]</a></sup></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>❌</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>❌</td>
        </tr>
        <tr>
            <td>WebAssembly<br /><small><code>net9.0-browserwasm</code></small></td>
            <td>✅</td><td>✅</td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>✅</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>✅</td>
        </tr>
    </tbody>
</table>

### [**macOS**](#tab/macOS)

<table>
    <thead>
        <tr>
            <th></th>
            <th colspan="2">VS Code</th>
            <th colspan="2">Rider</th>
        </tr>
        <tr>
            <th>🐞 Debugger</th>
            <th>With</th>
            <th>Without</th>
            <th>With</th>
            <th>Without</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Desktop<br /><small><code>net9.0-desktop</code></code></small></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>✅</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>✅</td>
        </tr>
        <tr>
            <td>Desktop - WSL<br /><small><code>net9.0-desktop</code></small></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>❌</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>❌</td>
        </tr>
        <tr>
            <td>iOS<br /><small><code>net9.0-ios</code></small></td>
            <td>✅</td><td>✅</td>
            <td>❌</td><td>✅</td>
        </tr>
        <tr>
            <td>Android<br /><small><code>net9.0-android</code></small></td>
            <td>✅</td><td>✅</td>
            <td>❌</td><td>✅</td>
        </tr>
        <tr>
            <td>WinAppSDK<br /><small><code>net9.0-windows10.x.x</code></small></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>❌</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>❌</td>
        </tr>
        <tr>
            <td>WebAssembly<br /><small><code>net9.0-browserwasm</code></small></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>✅</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>✅</td>
        </tr>
    </tbody>
</table>

### [**Linux**](#tab/linux)

<table>
    <thead>
        <tr>
            <th></th>
            <th colspan="2">VS Code</th>
            <th colspan="2">Rider</th>
        </tr>
        <tr>
            <th>🐞 Debugger</th>
            <th>With</th>
            <th>Without</th>
            <th>With</th>
            <th>Without</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Desktop<br /><small><code>net9.0-desktop</code></code></small></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>✅</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>✅</td>
        </tr>
        <tr>
            <td>Desktop - WSL<br /><small><code>net9.0-desktop</code></small></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>❌</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>❌</td>
        </tr>
        <tr>
            <td>iOS<br /><small><code>net9.0-ios</code></small></td>
            <td>🛜</td><td>🛜</td>
            <td>❌</td><td>❌</td>
        </tr>
        <tr>
            <td>Android<br /><small><code>net9.0-android</code></small></td>
            <td>✅</td><td>✅</td>
            <td>❌</td><td>✅</td>
        </tr>
        <tr>
            <td>WinAppSDK<br /><small><code>net9.0-windows10.x.x</code></small></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>❌</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>❌</td>
        </tr>
        <tr>
            <td>WebAssembly<br /><small><code>net9.0-browserwasm</code></small></td>
            <td>❌<sup><a href="#hr-footnotes">[5]</a></sup></td><td>✅</td>
            <td>❌<sup><a href="#hr-footnotes">[6]</a></sup></td><td>✅</td>
        </tr>
    </tbody>
</table>

---

Legend:

- ✅ Supported
- 🛜 Supported through [SSH to a Mac](xref:Uno.GettingStarted.CreateAnApp.VSCode#debug-the-app)
- ⌛ Upcoming support
- ❌ Currently not supported by the environment/IDE

### Notes

<a href="hr-footnotes"/>

- [1]: Support is [pending support](https://github.com/dotnet/sdk/pull/40725) in the .NET SDK.
- [2]: Support is [not available](https://youtrack.jetbrains.com/issue/RIDER-53302/launchSettings.json-WSL2-command-support).
- [3]: Unpackaged: C# & XAML / Packaged: XAML only
- [4]: Unpackaged: C# / Packaged: none
- [5]: VS Code Desktop and WASM [requested](https://developercommunity.visualstudio.com/t/Building-a-cross-targeted-project-with-m/651372)
- [6]: Rider Desktop and WASM [requested](https://youtrack.jetbrains.com/issue/RIDER-124189/MetadataUpdateHandlerAttribute-Not-Working-On-Hot-Reload)

## Supported features per Platform

### [**Desktop**](#tab/skia-desktop)

Skia-based targets provide support for full XAML Hot Reload and C# Hot Reload. There are some restrictions that are listed below:

- Visual Studio for Windows support is fully available, with and without running under the debugger
- As of VS 2022 17.9 XAML or C# Hot Reload under WSL is not supported
- VS Code
  - With the debugger: The C# Dev Kit is handling hot reload [when enabled](https://code.visualstudio.com/docs/csharp/debugging#_hot-reload). As of December 20th, 2023, C# Dev Kit hot reload does not handle class libraries. To experience the best hot reload, do not use the debugger.
  - Without the debugger: The VS Code Uno Platform extension is handling Hot Reload (C# and XAML).
  - Adding new C# or XAML files to a project is not yet supported.
- Rider
  - Hot Reload is only supported without the debugger.
  - Adding new C# or XAML files to a project is not yet supported.

### [**WebAssembly**](#tab/wasm)

WebAssembly is currently providing full Hot Reload support.

- In Visual Studio Code:
  - Both C# and XAML Hot Reload are fully supported.
  - Adding new C# or XAML files to the project is not yet supported.
  - Hot Reload is not supported when using the debugger.
- In Rider:
  - Both C# and XAML Hot Reload are fully supported.
  - Adding new C# or XAML files to the project is not yet supported.
  - Hot Reload is not supported when using the debugger.

### [**iOS, Android**](#tab/mobile)

Mobile targets now support both XAML and C# Hot Reload. Debugger-specific variations apply depending on the IDE.

- In Visual Studio:
  - The debugger **has** to be attached.
- In VS Code, and Rider:
  - Hot Reload is not supported when using the debugger.
- XAML `x:Bind` Hot Reload is limited to simple expressions and events.

### [**WinAppSDK**](#tab/winappsdk)

- Hot Reload is supported by Visual Studio for WinAppSDK and provides support in unpackaged deployment mode.
- Hot Reload is not supported in VS Code and Rider.

---

## Hot Reload Indicator

> [!NOTE]
> The **Hot Reload indicator** is currently not supported for the **WinAppSDK** target.

Hot Reload displays a visual indicator to help you further monitor changes while developing. It displays new information every time Hot Reload is triggered. The indicator is enabled by default within the `UseStudio()` method which is located in the root `App.xaml.cs` file. This displays an overlay that hosts the visual indicator. If you wish to disable it, you simply have to provide the following boolean: `UseStudio(showHotReloadIndicator: false)`, removing the overlay from the view.

To start using the **Hot Reload indicator** using the **latest stable 5.5 Uno.Sdk version or higher**, ensure you are signed in with your Uno Platform account. Follow [these instructions](xref:Uno.GetStarted.Licensing) to register and sign in.

<p align="center">
  <img src="~/articles/Assets/features/hotreload/indicator-not-connected-with-flyout.png" alt="The Hot Reload indicator is not connected. A flyout message states that Hot Reload is available only to registered users and prompts the user to sign in via the Uno Platform Studio button." />
</p>

For existing applications, take this opportunity to update to the [latest **Uno.Sdk** version](https://www.nuget.org/packages/Uno.Sdk/latest) to take advantage of all the latest improvements and support. Refer to our [migration guide](xref:Uno.Development.MigratingFromPreviousReleases) for upgrade steps.

> [!IMPORTANT]
> When upgrading to **Uno.Sdk 5.5 or higher**, the `EnableHotReload()` method in `App.xaml.cs` is deprecated and should be replaced with `UseStudio()`.

<p align="center">
  <img src="~/articles/Assets/features/hotreload/indicator.png" alt="A hot reload visual indicator" />
</p>

> [!TIP]
> The overlay can be moved by using the anchor on the left-hand side.

The indicator displays the current connection status. Clicking on it will open a flyout containing all events or changes that were applied by Hot Reload. These events display more details about Hot Reload changes, such as its status and impacted files.

<p align="center">
  <img src="~/articles/Assets/features/hotreload/indicator-flyout.png" alt="A window showing events from Hot Reload" />
</p>

### Statuses

Here's a summary of the Hot Reload connection statuses and their corresponding icons:

#### Connection

- ![The icon indicating that the user is not signed in](../Assets/features/hotreload/status-connection-not-signed-in.png) **Not Signed In**  
  _User needs to sign in to enable Hot Reload._

- ![The icon indicating an ongoing connection attempt](../Assets/features/hotreload/status-connection-connecting.png) **Connecting**  
  _Establishing a connection._

- ![The icon indicating a successful connection](../Assets/features/hotreload/status-connection-connected.png) **Connected**  
  _Connection established._

- ![The icon indicating a connection issue](../Assets/features/hotreload/status-connection-warning.png) **Warning**  
  _Usually indicates an issue that can be resolved by restarting your IDE._

- ![The icon indicating a failed connection](../Assets/features/hotreload/status-connection-failed.png) **Connection Failed**  
  _A connection error occurred. Refer to the [troubleshooting documentation](#troubleshooting) for possible solutions._

- ![The icon indicating the server is unreachable](../Assets/features/hotreload/status-connection-server-unreachable.png) **Server Unreachable**  
  _Hot Reload could not connect to the server. Check the [troubleshooting documentation](#troubleshooting) for guidance._

#### Operation

- ![The icon shown when Hot Reload succeeds](../Assets/features/hotreload/status-hr-success.png) **Success**  
  _The Hot Reload changes have been applied successfully._

- ![The icon shown when Hot Reload fails](../Assets/features/hotreload/status-hr-failed.png) **Failed**  
  _Hot Reload encountered an error and could not apply the changes._

- ![The icon shown when Hot Reload is in progress](../Assets/features/hotreload/status-hr-processing.png) **Processing**  
  _Hot Reload is applying changes or initializing._

## Troubleshooting

### [**Common issues**](#tab/common-issues)

- If the Hot Reload Indicator is red and shows a connection failure, ensure that you have the [latest stable version](https://www.nuget.org/packages/Uno.Sdk/latest) of [Uno.SDK](xref:Uno.Features.Uno.Sdk) and the latest version of your IDE’s extension ([Visual Studio](https://aka.platform.uno/vs-extension-marketplace), [Visual Studio Code](https://aka.platform.uno/vscode-extension-marketplace), or [Rider](https://aka.platform.uno/rider-extension-marketplace)). Additionally, [re-run Uno.Check](xref:UnoCheck.UsingUnoCheck) to update dependencies, then relaunch your IDE, [sign in with your Uno Platform account](xref:Uno.GetStarted.Licensing), and rebuild your application.

  For existing applications, refer to our [migration guide](xref:Uno.Development.MigratingFromPreviousReleases) for upgrade steps.
  > [!IMPORTANT]
  > When upgrading to **Uno.Sdk 5.5 or higher**, the `EnableHotReload()` method in `App.xaml.cs` is deprecated and should be replaced with `UseStudio()`.
- Observe the application logs, you should see diagnostics messages in the app when a XAML file is reloaded.
- WinAppSDK on Windows-specific issues
  - Grid Succinct syntax [is not supported](https://github.com/microsoft/microsoft-ui-xaml/issues/7043#issuecomment-1120061686)
- You can troubleshoot **Hot Reload** further by adjusting the **logging level** in your app.

  - **For Blank App Preset** (in `App.xaml.cs`, inside `InitializeLogging`):
  
    ```csharp
    // Adjust logging level
    builder.SetMinimumLevel(LogLevel.Debug); // or LogLevel.Trace

    // Uncomment and adjust logging level
    builder.AddFilter("Uno.UI.RemoteControl", LogLevel.Debug); // or LogLevel.Trace
    ```

  - **For Recommended App Preset** (in `App.xaml.cs`, inside `UseLogging`):

    ```csharp
    // Adjust logging level
    logBuilder.SetMinimumLevel(LogLevel.Debug); // or LogLevel.Trace

    // Uncomment and adjust logging level
    logBuilder.HotReloadCoreLogLevel(LogLevel.Debug); // or LogLevel.Trace
    ```

  The diagnostic messages will appear in the app's **Debug Output**.

  If you need to share logs when opening an issue on the GitHub [Uno Platform repository](https://github.com/unoplatform/uno), it is recommended to set `LogLevel` to **Trace** to provide the most detailed logs for investigation.

- If you're getting `ENC0003: Updating 'attribute' requires restarting the application`, add the following in the `Directory.Build.props` (or in each .csproj project head):

  ```xml
  <PropertyGroup>
    <!-- Required for Hot Reload (See https://github.com/unoplatform/uno.templates/issues/376) -->
    <GenerateAssemblyInfo Condition="'$(Configuration)'=='Debug'">false</GenerateAssemblyInfo>
  </PropertyGroup>
  ```
  
  Also [make sure](https://github.com/dotnet/sdk/issues/36666#issuecomment-2162173453) that you're not referencing `Microsoft.SourceLink.*` packages.

- If you're getting the `Unable to access Dispatcher/DispatcherQueue` error, you'll need to update your app to Uno.Sdk 5.6 or later, and update your `App.cs` file:

    ```csharp
    using Uno.UI;

    //... in the OnLaunched method

    #if DEBUG
            MainWindow.UseStudio();
    #endif
    ```

### [**Visual Studio**](#tab/vswints)

- Ensure that **C# Hot Reload** is enabled in Visual Studio by going to **Tools > Options**, searching for **.NET / C++ Hot Reload**, and making sure the following checkboxes are checked:
  - ✅ **Enable Hot Reload when debugging**
  - ✅ **Enable Hot Reload without debugging**
  - ✅ **Apply Hot Reload on File Save**
- The Output window in Visual Studio includes an output category named `Uno Platform` in its drop-down menu. Diagnostic messages from the Uno Platform VS extension appear there. To enable logging, you need to set **MSBuild project build output verbosity** to **at least "Normal"** (above "Minimal"). These changes should take effect immediately without requiring a Visual Studio restart. However, if you do not see additional logs, try restarting Visual Studio. For more details on build log verbosity, refer to the [official Visual Studio documentation](https://learn.microsoft.com/en-us/visualstudio/ide/how-to-view-save-and-configure-build-log-files?view=vs-2022#to-change-the-amount-of-information-included-in-the-build-log).  

    If you need to share logs when opening an issue on the GitHub [Uno Platform repository](https://github.com/unoplatform/uno), it is recommended to set verbosity to **Diagnostic** to provide the most detailed logs for investigation.

    **Steps to change MSBuild output verbosity:**  
    1. Open **Tools > Options > Projects and Solutions > Build and Run**, then set **MSBuild output verbosity** to **Diagnostic** or the required level.

       ![MSBuild output verbosity drop-down](../Assets/features/hotreload/vs-msbuild-output-verbosity.png)
    2. Restart Visual Studio, re-open your solution, and wait a few seconds.
    3. Go to **View > Output**.
    4. In the Output window, select `Uno Platform` from the drop-down.

       ![`Uno Platform` output drop-down](../Assets/features/hotreload/vs-uno-platform-logs.png)
- When a file is reloaded, XAML parsing errors will appear in the application's logs, on the device or in the browser.
- If there are multiple versions of the Uno.WinUI Package present in the solution, the newest will be used, regardless of the started application
- For `net9.0-windows10.xx`:
  - Ensure that the `net9.0-windows10.xxx` target framework **is selected in the top-left dropdown list of the XAML editor**. Selecting any other platform will break Hot Reload.
  - [A VS issue for WinUI may be hit](https://developercommunity.visualstudio.com/t/net80-windows10-needs-to-be-first-for-W/10643724). If XAML Hot Reload does not work, ensure that the `Uno Platform` output window exists, and that it mentions that the extension has successfully loaded. To do so, try closing and reopening the solution, and make sure that the [Visual Studio extension is installed](xref:Uno.GetStarted.vs2022).
  - [A known VS issue for WinUI](https://github.com/microsoft/microsoft-ui-xaml/issues/5944) breaks Hot Reload when using "simplified" `RowDefinitions`/`ColumnDefinitions`.

### [**Visual Studio Code**](#tab/vscodets)

- Hot Reload **is not supported** when using the debugger. Start your app using `Ctrl+F5`.
- The Output window in Visual Studio Code includes an output category named `Uno Platform - Hot Reload` in its drop-down menu. Diagnostic messages from the Uno Platform VS Code extension appear there.

    **Steps to see the `Uno Platform - Hot Reload` output:**  
    1. In the status bar at the bottom left of VS Code, ensure `NameOfYourProject.csproj` is selected (by default `NameOfYourProject.sln` is selected).

       ![.csproj selection in Visual Studio Code](../Assets/features/hotreload/vscode-csproj-selection.png)
    2. Wait a few seconds.
    3. Go to **View > Output**.
    4. In the Output window, select `Uno Platform - Hot Reload` from the drop-down.

       ![`Uno Platform` output drop-down](../Assets/features/hotreload/vs-code-uno-platform-hr-output.png)
- Depending on your machine's performance, the Hot Reload engine may take a few moments to initialize and take your project modifications into account.
- Make sure that the selected project in the status bar (or using the "Uno Platform: Select Active Project" in the command palette) is not the solution file, but rather the project file (i.e. ending by `.csproj`).
- Align the "Debug profile" (at the top of the "Run and Debug" pane) with the platform you chose to debug within the status bar (or using the "Uno Platform: Select the Target Platform Moniker (TFM)")
  - "Uno Platform Desktop Debug" profile for `net9.0-desktop`
  - "Uno Platform Mobile Debug" profile for `net9.0-ios` and `net9.0-android`
  - "Uno Platform WebAssembly Debug" profile for `net9.0-browserwasm`
- If Hot Reload does not function properly, you can try using the `Developer: Reload Window` command in the palette (using `Ctrl+Shift+P`)
- The TCP port number used by the app to connect back to the IDE is located in the `<UnoRemoteControlPort>` property of the `[ProjectName].csproj.user` file. If the port number does not match with the one found in the `Uno Platform - Hot Reload` output window, restart Code or use `Developer: Reload Window` in the command palette.

### [**Rider**](#tab/riderts)

- Hot Reload **is not supported** when using the debugger. Start your app without the debugger.
- The Output window in Rider includes an output category named `Uno Platform` in its sidebar. Diagnostic messages from the Uno Platform Rider plugin appear there.

    **Steps to see the `Hot Reload` output:**  
    1. In the sidebar at the bottom left of Rider, click on the Uno Platform logo.

       ![Uno Platform output logo](../Assets/features/hotreload/rider-uno-platform-output.png)
    2. In the Output window, select **LEVEL: Trace** from the drop-down.

       ![Level output drop-down](../Assets/features/hotreload/rider-output-level-trace.png)
- Depending on your machine's performance, the Hot Reload engine may take a few moments to initialize and take your project modifications into account.
- If Hot Reload does not function properly, you can try closing and reopening the solution.
- The TCP port number used by the app to connect back to the IDE is located in the `<UnoRemoteControlPort>` property of the `[ProjectName].csproj.user` file. If the port number does not match the one found in the **Uno Platform** output window, close and reopen the solution.

---

## Next Steps

Learn more about:

- [Uno Platform features and architecture](xref:Uno.GetStarted.Explore)
- [Uno Platform App solution structure](xref:Uno.Development.AppStructure)
- [Troubleshooting](xref:Uno.UI.CommonIssues)
- [List of views implemented in Uno](../implemented-views.md) for the set of available controls and their properties.
- You can head to [How-tos and tutorials](xref:Uno.Tutorials.Intro) on how to work on your Uno Platform app.

---

# Source: https://raw.githubusercontent.com/unoplatform/uno/refs/heads/master/doc/articles/wpf-migration.md

---
uid: Uno.Development.WPFMigration
---

# Migrating WPF Apps to Web

This article covers architecture and implementation considerations for migrating WPF applications to the Web using Uno Platform and WinUI.

![A WPF app migrated to the web with Uno platform](Assets/migrated-app.png)

## Introduction

While improvements will continue to be made by Microsoft at the framework level to ensure the compatibility and reliability of your WPF application, it may be desirable to expand its reach. In this hybrid work era, previous assumptions and development decisions which served your customers well become less valid. For instance, applications targeting the Windows platform alone miss out on mobility benefits of the Web.

Advancements such as [WebAssembly (WASM)](https://developer.mozilla.org/docs/WebAssembly), a low-level bytecode for the web, have already become a viable, performant way to deliver your modern .NET applications.

## Migrating the codebase

The Uno Platform not only allows you to maximize reuse of C#, XAML, and .NET investments, but also enables your team to naturally leverage their existing skill set. Alongside your existing investments, you may decide to further enhance your app, refreshing aspects to make use of new capabilities in the platform. Regardless, your goal is to consider what role your application will play several years or more into the future. Depending on your scenario, it may make sense to enhance the user interface layout for different form factors. In this article, the primary focus will be on rewriting as little as possible.

> [!TIP]
> Read the UWP/WinUI & Uno documentation first to better understand the capabilities of the platform.

## Limitations

The vast majority of your codebase will simply "move across". Existing XAML structure, business logic, and view models can simply be reused. You'll need to recompile old code, and won't have access to framework-only APIs. You may encounter APIs that aren't implemented or controls where a subset of the functionality is presently unsupported. Additionally, the following contain substantial enough differences from WPF to require extra research upfront:

* [Navigation](https://learn.microsoft.com/windows/apps/design/basics/navigate-between-two-pages)
* [Advanced binding functionality with x:Bind](https://learn.microsoft.com/windows/uwp/xaml-platform/x-bind-markup-extension)
* [Modern APIs are often async only](https://learn.microsoft.com/windows/uwp/threading-async/call-asynchronous-apis-in-csharp-or-visual-basic)
* [Uno has a streamlined set of XAML capabilities for performance reasons](https://learn.microsoft.com/windows/uwp/xaml-platform/xaml-overview)
* [Specific framework capabilities](https://github.com/robloo/PublicDocs/blob/master/UWPvsWPF.md)

## Understanding beforehand

Along the journey to bring your WPF app to the Web, you should become familiar with the Uno Platform documentation. Your team should thoroughly understand what is supported (and where) before you build a feature around it. Learn about:

* [Get started](xref:Uno.GetStarted)
* [How-tos and tutorials](xref:Uno.Tutorials.Intro)
* [Development deep-dives](xref:Uno.Development.Overview)
* [Reference](https://platform.uno/docs/articles/implemented-views.html)

## Architecture Considerations

### MVVM Libraries

Several of the popular MVVM libraries like MVVMLite, Prism, and the Windows Community Toolkit implementation have already been ported to Uno. If your existing app leverages something in-house, there's a chance it will just work.

### Navigation

Apps leveraging Page-based navigation are relatively straightforward to migrate. If your app has a different navigation stack, there may be additional implementation changes to consider.

### Custom Controls

One of the strengths of Uno is having access to the same, opinionated set of battle-tested controls that exist on Windows everywhere. For that reason, we recommend determining whether there is an included framework equivalent to your custom controls. Depending on your app's design goals, it may be desirable to switch to UX patterns more accommodative of your users' device categories.

There are also controls available from the [Windows Community Toolkit](uno-community-toolkit.md).

Either way, the ContentControls and DataTemplate pattern you make use of for variability in your WPF app's user interface are still supported.

### Data Access

If your WPF application currently connects directly to a database, you should consider whether this pattern makes sense on the web and look into making use of web services.

### Deprecated Technology

Full support for WCF and WCF Data Services are not included in modern .NET versions. Because these technologies lack a path forward, you should consider attempting to implement a service-oriented architecture with other frameworks like gRPC or REST services.

### Desktop Integration

If your app relies on heavy access to Windows-specific constructs such as the registry, you should rethink your approach to fit the Web's platform agnostic app model.