AGIBuild/dotnet-uno-platform

dotnet-uno-platform

Uno Platform core development: Extensions ecosystem (Navigation, DI, Configuration, Serialization, Localization, Logging, HTTP, Authentication), MVUX reactive pattern, Toolkit controls, Theme resources (Material/Cupertino/Fluent), Hot Reload, and single-project structure. Covers Uno Platform 5.x+ on .NET 8.0+ baseline.

Scope boundary: This skill owns Uno Platform project structure, Extensions ecosystem configuration, MVUX patterns, Toolkit controls, theming, and Hot Reload. Per-target deployment (WASM, iOS, Android, Desktop, Embedded) is owned by [skill:dotnet-uno-targets]. MCP server integration for live documentation is owned by [skill:dotnet-uno-mcp].

Out of scope: Uno Platform testing (Playwright for WASM, platform-specific tests) -- see [skill:dotnet-uno-testing]. General serialization patterns -- see [skill:dotnet-serialization]. AOT/trimming for WASM -- see [skill:dotnet-aot-wasm]. UI framework selection decision tree -- see [skill:dotnet-ui-chooser].

Cross-references: [skill:dotnet-uno-targets] for per-target deployment, [skill:dotnet-uno-mcp] for MCP integration, [skill:dotnet-uno-testing] for testing patterns, [skill:dotnet-serialization] for serialization depth, [skill:dotnet-aot-wasm] for WASM AOT, [skill:dotnet-ui-chooser] for framework selection, [skill:dotnet-accessibility] for accessibility patterns (AutomationProperties, ARIA mapping on WASM).

---

Single-Project Structure

Uno Platform 5.x uses a single-project structure with conditional TFMs for multi-targeting. One .csproj targets all platforms via multi-targeting.

<!-- MyApp.csproj -->
<Project Sdk="Uno.Sdk">
  <PropertyGroup>
    <TargetFrameworks>
      net8.0-browserwasm;
      net8.0-ios;
      net8.0-android;
      net8.0-maccatalyst;
      net8.0-windows10.0.19041;
      net8.0-desktop
    </TargetFrameworks>
    <OutputType>Exe</OutputType>
    <UnoFeatures>
      Extensions;
      Toolkit;
      Material;
      MVUX;
      Navigation;
      Configuration;
      Hosting;
      Http;
      Localization;
      Logging;
      LoggingSerilog;
      Serialization;
      Authentication;
      AuthenticationOidc
    </UnoFeatures>
  </PropertyGroup>
</Project>

The UnoFeatures MSBuild property controls which Uno Extensions and theming packages are included. The Uno SDK resolves these features to the correct NuGet packages automatically.

Project Layout

MyApp/
  MyApp/
    App.xaml / App.xaml.cs        # Application entry, resource dictionaries
    MainPage.xaml / .xaml.cs      # Initial page
    Presentation/                 # ViewModels or MVUX Models
    Views/                        # XAML pages
    Services/                     # Service interfaces and implementations
    Strings/                      # Localization resources (.resw)
      en/Resources.resw
    Assets/                       # Images, fonts, icons
    appsettings.json              # Configuration (Extensions.Configuration)
    Platforms/                    # Platform-specific code (conditional compilation)
      Android/
      iOS/
      Wasm/
      Desktop/
  MyApp.Tests/                   # Unit tests (shared logic)

---

Uno Extensions

Uno Extensions provide opinionated infrastructure on top of the platform. All modules are registered through the host builder pattern.

Host Builder Setup

// App.xaml.cs
public App()
{
    this.InitializeComponent();

    Host = UnoHost
        .CreateDefaultBuilder()
        .UseConfiguration(configure: configBuilder =>
            configBuilder.EmbeddedSource<App>()
                         .Section<AppConfig>())
        .UseLocalization()
        .UseNavigation(RegisterRoutes)
        .UseSerilog(loggerConfiguration: config =>
            config.WriteTo.Debug())
        .ConfigureServices((context, services) =>
        {
            services.AddSingleton<IProductService, ProductService>();
        })
        .Build();
}

Navigation

Package: Uno.Extensions.Navigation

Region-based navigation with route maps, deep linking, and type-safe parameter passing. Navigation is driven declaratively from XAML or imperatively from code.

// Route registration
private static void RegisterRoutes(IViewRegistry views, IRouteRegistry routes)
{
    views.Register(
        new ViewMap(ViewModel: typeof(ShellModel)),
        new ViewMap<MainPage, MainModel>(),
        new ViewMap<ProductDetailPage, ProductDetailModel>(),
        new DataViewMap<ProductDetailPage, ProductDetailModel, ProductEntity>()
    );

    routes.Register(
        new RouteMap("", View: views.FindByViewModel<ShellModel>(),
            Nested: new RouteMap[]
            {
                new("Main", View: views.FindByViewModel<MainModel>()),
                new("ProductDetail", View: views.FindByViewModel<ProductDetailModel>())
            })
    );
}

<!-- XAML-based navigation using attached properties -->
<Button Content="View Product"
        uen:Navigation.Request="ProductDetail"
        uen:Navigation.Data="{Binding SelectedProduct}" />

Key concepts: Region-based navigation attaches navigation behavior to visual regions (Frame, NavigationView, TabBar). Route maps define the navigation graph. Deep linking maps URLs to routes for WASM.

Dependency Injection

Package: Uno.Extensions.Hosting

Uses Microsoft.Extensions.Hosting under the hood. Host builder pattern with service registration, keyed services, and scoped lifetimes.

.ConfigureServices((context, services) =>
{
    // Standard DI registration
    services.AddSingleton<IAuthService, AuthService>();
    services.AddTransient<IOrderService, OrderService>();

    // Keyed services (.NET 8+)
    services.AddKeyedSingleton<ICache>("memory", new MemoryCache());
    services.AddKeyedSingleton<ICache>("distributed", new RedisCache());
})

Configuration

Package: Uno.Extensions.Configuration

Loads configuration from appsettings.json (embedded resource), environment-specific overrides, and runtime writeable options.

// appsettings.json
{
  "AppConfig": {
    "ApiBaseUrl": "https://api.example.com",
    "MaxRetries": 3
  }
}

// Binding to strongly-typed options
.UseConfiguration(configure: configBuilder =>
    configBuilder
        .EmbeddedSource<App>()
        .Section<AppConfig>())

// AppConfig.cs
public record AppConfig
{
    public string ApiBaseUrl { get; init; } = "";
    public int MaxRetries { get; init; } = 3;
}

Serialization

Package: Uno.Extensions.Serialization

Integrates System.Text.Json with source generators for AOT compatibility. Configures JSON serialization across the Extensions ecosystem.

.UseSerialization(configure: serializerBuilder =>
    serializerBuilder
        .AddJsonTypeInfo(AppJsonContext.Default.ProductDto)
        .AddJsonTypeInfo(AppJsonContext.Default.OrderDto))

For general serialization patterns and AOT source-gen depth, see [skill:dotnet-serialization].

Localization

Package: Uno.Extensions.Localization

Resource-based localization using .resw files with runtime culture switching.

.UseLocalization()

<!-- Strings/en/Resources.resw -->
<!-- name: MainPage_Title.Text, value: Welcome -->
<!-- name: MainPage_LoginButton.Content, value: Log In -->

<!-- XAML: use x:Uid for automatic resource binding -->
<TextBlock x:Uid="MainPage_Title" />
<Button x:Uid="MainPage_LoginButton" />

Culture switching at runtime:

// Switch culture programmatically
var localizationService = serviceProvider.GetRequiredService<ILocalizationService>();
await localizationService.SetCurrentCultureAsync(new CultureInfo("fr-FR"));

Logging

Package: Uno.Extensions.Logging

Integrates with Microsoft.Extensions.Logging. Serilog integration for platform-specific sinks.

.UseSerilog(loggerConfiguration: config =>
    config
        .MinimumLevel.Information()
        .WriteTo.Debug()
        .WriteTo.Console())

Platform-specific sinks: Debug output for desktop, browser console for WASM, platform logcat for Android, NSLog for iOS.

HTTP

Package: Uno.Extensions.Http

HTTP client integration with endpoint configuration. Supports Refit for typed API clients and Kiota for OpenAPI-generated clients.

.UseHttp(configure: (context, services) =>
    services
        .AddRefitClient<IProductApi>(context,
            configure: builder => builder
                .ConfigureHttpClient(client =>
                    client.BaseAddress = new Uri("https://api.example.com"))))

// Refit interface
public interface IProductApi
{
    [Get("/products")]
    Task<List<ProductDto>> GetProductsAsync(CancellationToken ct = default);

    [Get("/products/{id}")]
    Task<ProductDto> GetProductByIdAsync(int id, CancellationToken ct = default);
}

Authentication

Package: Uno.Extensions.Authentication

OIDC, custom auth providers, and token management. Integrates with navigation for login/logout flows.

.UseAuthentication(auth =>
    auth.AddOidc(oidc =>
    {
        oidc.Authority = "https://login.example.com";
        oidc.ClientId = "my-app";
        oidc.Scope = "openid profile email";
    }))

Token management is automatic: tokens are stored securely per platform (Keychain on iOS/macOS, KeyStore on Android, Credential Manager on Windows, browser storage on WASM) and refreshed transparently.

---

MVUX (Model-View-Update-eXtended)

MVUX is Uno's recommended reactive pattern, distinct from MVVM. It uses immutable records, Feeds, and States to model data flow declaratively. Source generators produce bindable proxies from plain model classes.

Core Concepts

| Concept | Purpose | MVVM Equivalent | |---------|---------|-----------------| | Model | Immutable record defining UI state | ViewModel | | Feed | Async data source (loading/data/error states) | ObservableCollection + loading flag | | State | Mutable reactive state with change tracking | INotifyPropertyChanged property | | ListFeed | Feed specialized for collections | ObservableCollection | | Command | Auto-generated from public async methods | ICommand |

Model Example

// ProductModel.cs -- MVUX model (source generators produce the bindable proxy)
public partial record ProductModel(IProductService ProductService)
{
    // Feed: async data source with loading/error/data states
    public IFeed<IImmutableList<ProductDto>> Products => Feed
        .Async(async ct => await ProductService.GetProductsAsync(ct));

    // State: mutable reactive value
    public IState<string> SearchTerm => State<string>.Value(this, () => "");

    // ListFeed with selection support
    public IListFeed<ProductDto> FilteredProducts => SearchTerm
        .SelectAsync(async (term, ct) =>
            await ProductService.SearchProductsAsync(term, ct))
        .AsListFeed();

    // Command: auto-generated from async method signature
    public async ValueTask AddProduct(CancellationToken ct)
    {
        var term = await SearchTerm;
        await ProductService.AddProductAsync(term, ct);
    }
}

<!-- ProductPage.xaml -- binds to generated proxy -->
<Page x:Class="MyApp.Views.ProductPage"
      xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
      xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">

    <StackPanel>
        <TextBox Text="{Binding SearchTerm, Mode=TwoWay}" />

        <FeedView Source="{Binding FilteredProducts}">
            <FeedView.ValueTemplate>
                <DataTemplate>
                    <ListView ItemsSource="{Binding Data}">
                        <ListView.ItemTemplate>
                            <DataTemplate>
                                <TextBlock Text="{Binding Name}" />
                            </DataTemplate>
                        </ListView.ItemTemplate>
                    </ListView>
                </DataTemplate>
            </FeedView.ValueTemplate>
            <FeedView.ProgressTemplate>
                <DataTemplate>
                    <ProgressRing IsActive="True" />
                </DataTemplate>
            </FeedView.ProgressTemplate>
            <FeedView.ErrorTemplate>
                <DataTemplate>
                    <TextBlock Text="Error loading products" Foreground="Red" />
                </DataTemplate>
            </FeedView.ErrorTemplate>
        </FeedView>

        <Button Content="Add Product" Command="{Binding AddProduct}" />
    </StackPanel>
</Page>

MVUX vs MVVM

| Concern | MVUX | MVVM | |---------|------|------| | Model definition | Immutable record types | Mutable classes with INotifyPropertyChanged | | Data loading | IFeed<T> with built-in loading/error states | Manual loading flags and try/catch | | Collections | IListFeed<T> with immutable snapshots | ObservableCollection<T> with mutation | | Commands | Auto-generated from async methods | ICommand implementations (RelayCommand) | | State changes | IState<T> with explicit update semantics | Property setters firing PropertyChanged | | Boilerplate | Minimal (source generators) | Significant (base classes, attributes) |

When to use MVUX: New Uno Platform projects, especially those with async data sources and complex loading states. MVUX eliminates most boilerplate and handles loading/error states declaratively.

When to use MVVM: Projects migrating from existing WPF/UWP/WinUI codebases, teams familiar with MVVM patterns, or projects using CommunityToolkit.Mvvm.

---

Uno Toolkit Controls

The Uno Toolkit provides cross-platform controls and helpers beyond stock WinUI controls. Enabled via UnoFeatures with Toolkit.

Key Controls

| Control | Purpose | |---------|---------| | AutoLayout | Flexbox-like layout with spacing, padding, and alignment | | Card / CardContentControl | Material-style card surfaces with elevation | | Chip / ChipGroup | Filter chips, action chips, selection chips | | Divider | Horizontal/vertical separator lines | | DrawerControl | Side drawer (hamburger menu) | | LoadingView | Loading state wrapper with skeleton/shimmer | | NavigationBar | Cross-platform navigation bar | | ResponsiveView | Adaptive layout based on screen width breakpoints | | SafeArea | Insets for notches, status bars, navigation bars | | ShadowContainer | Cross-platform drop shadows via ThemeShadow | | TabBar | Bottom or top tab navigation | | ZoomContentControl | Pinch-to-zoom container |

Toolkit Helpers

| Helper | Purpose | |--------|---------| | CommandExtensions | Attach commands to any control (not just Button) | | ItemsRepeaterExtensions | Selection and command support for ItemsRepeater | | InputExtensions | Auto-focus, return key command, input scope | | ResponsiveMarkupExtensions | Responsive values in XAML markup (e.g., Responsive.Narrow) | | StatusBarExtensions | Control status bar appearance per-platform | | AncestorBinding | Bind to ancestor DataContext in templates |

AutoLayout Example

<!-- Vertical stack with spacing, padding, and alignment -->
<utu:AutoLayout Spacing="16" Padding="24"
                PrimaryAxisAlignment="Start"
                CounterAxisAlignment="Stretch">

    <TextBlock Text="Product List"
               Style="{StaticResource HeadlineMedium}" />

    <utu:AutoLayout Spacing="8" Orientation="Horizontal">
        <TextBox PlaceholderText="Search..."
                 utu:AutoLayout.PrimaryLength="*" />
        <Button Content="Search"
                utu:AutoLayout.CounterAlignment="Center" />
    </utu:AutoLayout>

    <ListView ItemsSource="{Binding Products}"
              utu:AutoLayout.PrimaryLength="*" />
</utu:AutoLayout>

---

Theme Resources

Uno supports Material, Cupertino, and Fluent design systems as theme packages. Themes provide consistent colors, typography, elevation, and control styles across all platforms.

Theme Configuration

<!-- UnoFeatures in .csproj -->
<UnoFeatures>Material</UnoFeatures>   <!-- or Cupertino, or both -->

<!-- App.xaml -- theme resource dictionaries -->
<Application.Resources>
    <ResourceDictionary>
        <ResourceDictionary.MergedDictionaries>
            <!-- Material theme resources -->
            <MaterialTheme />

            <!-- Optional: color palette override -->
            <ResourceDictionary Source="ms-appx:///Themes/ColorPaletteOverride.xaml" />
        </ResourceDictionary.MergedDictionaries>
    </ResourceDictionary>
</Application.Resources>

Color Customization

Override Material theme colors through ColorPaletteOverride.xaml:

<!-- Themes/ColorPaletteOverride.xaml -->
<ResourceDictionary xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
                    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml">
    <Color x:Key="PrimaryColor">#6750A4</Color>
    <Color x:Key="SecondaryColor">#625B71</Color>
    <Color x:Key="TertiaryColor">#7D5260</Color>
    <Color x:Key="ErrorColor">#B3261E</Color>
</ResourceDictionary>

Typography

Use existing TextBlock styles from the theme system. Never set explicit font sizes -- use the Material type scale:

<TextBlock Text="Headline" Style="{StaticResource HeadlineMedium}" />
<TextBlock Text="Body text" Style="{StaticResource BodyLarge}" />
<TextBlock Text="Caption" Style="{StaticResource LabelSmall}" />

| Style | Typical Use | |-------|------------| | DisplayLarge/Medium/Small | Hero text, splash screens | | HeadlineLarge/Medium/Small | Page titles, section headers | | TitleLarge/Medium/Small | Card titles, dialog titles | | BodyLarge/Medium/Small | Paragraph text, descriptions | | LabelLarge/Medium/Small | Button labels, captions, metadata |

ThemeService

Switch between light and dark themes programmatically:

var themeService = serviceProvider.GetRequiredService<IThemeService>();
await themeService.SetThemeAsync(AppTheme.Dark);
var currentTheme = themeService.Theme;

---

Hot Reload

Uno Platform provides Hot Reload across all targets via its custom implementation. Changes to XAML and C# code-behind are reflected without restarting the app.

Supported Changes

| Change Type | Hot Reload Support | |-------------|-------------------| | XAML layout/styling | Full reload, instant | | C# code-behind (method bodies) | Supported via MetadataUpdateHandler | | New properties/methods | Requires rebuild | | Resource dictionary changes | Full reload | | Navigation route changes | Requires rebuild |

Enabling Hot Reload

# Set environment variable before dotnet run
export DOTNET_MODIFIABLE_ASSEMBLIES=debug

# Run with Hot Reload
dotnet run -f net8.0-desktop --project MyApp/MyApp.csproj

Hot Reload is automatically configured by Visual Studio and VS Code (with Uno extension). For CLI usage, set DOTNET_MODIFIABLE_ASSEMBLIES=debug before running.

Gotcha: Hot Reload does not support adding new types, changing inheritance hierarchies, or modifying UnoFeatures. These require a full rebuild.

---

Agent Gotchas

1. Do not confuse MVUX with MVVM. MVUX uses immutable records, Feeds, and States -- not INotifyPropertyChanged. Do not add ObservableProperty attributes to MVUX models.
2. Do not hardcode NuGet package versions for Uno Extensions. The UnoFeatures MSBuild property resolves packages automatically via the Uno SDK. Adding explicit PackageReference items for Extensions can cause version conflicts.
3. Do not use {Binding StringFormat=...} in Uno XAML. It is a WPF-only feature. Use converters or multiple <Run> elements for formatted text.
4. Do not use x:Static or {x:Reference} in bindings. These are WPF-only markup extensions not available in WinUI/Uno.
5. Do not set explicit font sizes or weights. Use the theme's TextBlock styles (e.g., HeadlineMedium, BodyLarge) to maintain design system consistency.
6. Do not use hardcoded hex colors. Always reference theme resources (PrimaryColor, SecondaryColor) or semantic brushes to maintain theme compatibility.
7. Do not use AppBarButton outside a CommandBar. Use regular Button with icon content for standalone icon buttons.
8. Do not forget x:Uid for localization. Every user-visible string should use x:Uid referencing .resw resources, not hardcoded text.

---

Prerequisites

• .NET 8.0+ (Uno Platform 5.x baseline)
• Uno SDK (Uno.Sdk project SDK)
• Platform workloads as needed: dotnet workload install ios android maccatalyst wasm-tools
• Visual Studio 2022+ or VS Code with Uno Platform extension

---

References

• Uno Platform Documentation
• Uno Extensions Overview
• MVUX Pattern
• Uno Toolkit
• Uno Themes
• Uno SDK Features