I-Synergy.Framework.UI.WinUI 2026.11114.12249

I-Synergy Framework UI WinUI

Modern Windows UI framework for building next-generation Windows applications with WinUI 3. This package provides a complete WinUI implementation of the I-Synergy Framework UI services, controls, and patterns for Windows 10+ and Windows 11.

Features

• WinUI 3 support for Windows 10 (26100+) and Windows 11
• Modern Fluent Design with Mica, Acrylic, and Material effects
• Dialog service with ContentDialog and MessageDialog support
• Navigation service with Frame-based navigation
• Theme service with dynamic accent colors and Fluent theming
• File service with modern file pickers
• Clipboard service for Windows clipboard operations
• Camera service for camera and photo capture
• Update service for application updates
• Custom controls (BladeView, Console, ImageBrowser, Menu, Tiles, ErrorPresenter, SplashScreen)
• Behaviors using CommunityToolkit.WinUI.Behaviors
• 40+ dynamic theme palettes with modern Fluent Design styles
• Native Windows 11 integration with title bar customization

Installation

Install the package via NuGet:

dotnet add package I-Synergy.Framework.UI.WinUI

Quick Start

1. Configure Application

Setup your WinUI 3 application with I-Synergy Framework:

using ISynergy.Framework.UI;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using Microsoft.UI.Xaml;

public partial class App : Application
{
    private IHost _host;
    private Microsoft.UI.Xaml.Window _window;

    public App()
    {
        InitializeComponent();
    }

    protected override async void OnLaunched(LaunchActivatedEventArgs args)
    {
        _host = Host.CreateDefaultBuilder()
            .ConfigureServices((context, services) =>
            {
                // Core services
                services.AddSingleton<ILanguageService, LanguageService>();
                services.AddSingleton<IMessengerService, MessengerService>();
                services.AddSingleton<IBusyService, BusyService>();

                // WinUI services
                services.AddSingleton<IDialogService, DialogService>();
                services.AddSingleton<INavigationService, NavigationService>();
                services.AddSingleton<IThemeService, ThemeService>();
                services.AddSingleton<IFileService<FileResult>, FileService>();
                services.AddSingleton<IClipboardService, ClipboardService>();
                services.AddSingleton<ICameraService, CameraService>();
                services.AddSingleton<IUpdateService, UpdateService>();

                // ViewModels
                services.AddTransient<MainViewModel>();
                services.AddTransient<ShellViewModel>();
            })
            .Build();

        await _host.StartAsync();

        // Apply theme
        var themeService = _host.Services.GetRequiredService<IThemeService>();
        themeService.ApplyTheme();

        // Create and activate window
        _window = _host.Services.GetRequiredService<MainWindow>();
        _window.Activate();
    }
}

2. Create XAML Windows with ViewModels

<Window x:Class="MyApp.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"
        mc:Ignorable="d">

    <Grid>
        <Grid.RowDefinitions>
            <RowDefinition Height="Auto"/>
            <RowDefinition Height="*"/>
            <RowDefinition Height="Auto"/>
        </Grid.RowDefinitions>

        
        <Grid Grid.Row="0" Background="{ThemeResource SystemControlAcrylicElementBrush}">
            <CommandBar>
                <AppBarButton Icon="Add" Label="New" Command="{Binding NewCommand}"/>
                <AppBarButton Icon="OpenFile" Label="Open" Command="{Binding OpenCommand}"/>
                <AppBarButton Icon="Save" Label="Save" Command="{Binding SaveCommand}"/>
                <AppBarSeparator/>
                <AppBarButton Icon="Setting" Label="Settings" Command="{Binding SettingsCommand}"/>
            </CommandBar>
        </Grid>

        
        <Frame Grid.Row="1"
               x:Name="MainFrame"/>

        
        <Grid Grid.Row="2" Background="{ThemeResource SystemControlAcrylicElementBrush}">
            <Grid.ColumnDefinitions>
                <ColumnDefinition Width="*"/>
                <ColumnDefinition Width="Auto"/>
            </Grid.ColumnDefinitions>

            <TextBlock Grid.Column="0"
                       Text="{Binding StatusMessage}"
                       Margin="12,8"
                       VerticalAlignment="Center"/>

            <ProgressRing Grid.Column="1"
                          Width="20" Height="20"
                          Margin="12,8"
                          IsActive="{Binding BusyService.IsBusy}"/>
        </Grid>
    </Grid>
</Window>

using Microsoft.UI.Xaml;

public sealed partial class MainWindow : Window
{
    public MainWindow(MainViewModel viewModel)
    {
        InitializeComponent();
        ExtendsContentIntoTitleBar = true;
        SetTitleBar(AppTitleBar);
        DataContext = viewModel;
    }
}

3. Use Dialog Service

using ISynergy.Framework.Mvvm.ViewModels;
using ISynergy.Framework.Mvvm.Commands;

public class ProductViewModel : ViewModel
{
    private readonly IProductService _productService;

    public AsyncRelayCommand SaveCommand { get; }
    public AsyncRelayCommand DeleteCommand { get; }

    public ProductViewModel(
        ICommonServices commonServices,
        IProductService productService,
        ILogger<ProductViewModel> logger)
        : base(commonServices, logger)
    {
        _productService = productService;

        SaveCommand = new AsyncRelayCommand(SaveAsync, CanSave);
        DeleteCommand = new AsyncRelayCommand(DeleteAsync);
    }

    private bool CanSave() => !string.IsNullOrEmpty(Name) && IsValid;

    private async Task SaveAsync()
    {
        try
        {
            CommonServices.BusyService.StartBusy("Saving product...");

            await _productService.SaveAsync(Product);

            await CommonServices.DialogService.ShowInformationAsync(
                "Product saved successfully",
                "Success");
        }
        catch (Exception ex)
        {
            await CommonServices.DialogService.ShowErrorAsync(ex, "Error");
        }
        finally
        {
            CommonServices.BusyService.StopBusy();
        }
    }

    private async Task DeleteAsync()
    {
        var result = await CommonServices.DialogService.ShowMessageAsync(
            "Are you sure you want to delete this product?",
            "Confirm Delete",
            MessageBoxButtons.YesNo);

        if (result == MessageBoxResult.Yes)
        {
            await _productService.DeleteAsync(Product.Id);
            await CommonServices.NavigationService.GoBackAsync();
        }
    }

    // Show custom ContentDialog
    private async Task EditSettingsAsync()
    {
        await CommonServices.DialogService
            .ShowDialogAsync<SettingsDialog, SettingsViewModel, Settings>();
    }
}

4. Camera Service

using ISynergy.Framework.Mvvm.Abstractions.Services;

public class ProfileViewModel : ViewModel
{
    private readonly ICameraService _cameraService;

    public AsyncRelayCommand TakePhotoCommand { get; }
    public AsyncRelayCommand PickPhotoCommand { get; }

    public BitmapImage ProfileImage
    {
        get => GetValue<BitmapImage>();
        set => SetValue(value);
    }

    public ProfileViewModel(
        ICommonServices commonServices,
        ICameraService cameraService,
        ILogger<ProfileViewModel> logger)
        : base(commonServices, logger)
    {
        _cameraService = cameraService;

        TakePhotoCommand = new AsyncRelayCommand(TakePhotoAsync);
        PickPhotoCommand = new AsyncRelayCommand(PickPhotoAsync);
    }

    private async Task TakePhotoAsync()
    {
        var photo = await _cameraService.TakePhotoAsync();

        if (photo is not null)
        {
            var bitmapImage = new BitmapImage();
            using (var stream = await photo.OpenReadAsync())
            {
                await bitmapImage.SetSourceAsync(stream.AsRandomAccessStream());
            }
            ProfileImage = bitmapImage;
        }
    }

    private async Task PickPhotoAsync()
    {
        var photo = await _cameraService.PickPhotoAsync();

        if (photo is not null)
        {
            var bitmapImage = new BitmapImage();
            using (var stream = await photo.OpenReadAsync())
            {
                await bitmapImage.SetSourceAsync(stream.AsRandomAccessStream());
            }
            ProfileImage = bitmapImage;
        }
    }
}

Custom Controls

BladeView

<controls:BladeView ItemsSource="{x:Bind ViewModel.Blades, Mode=OneWay}"
                    Anchor="Auto"
                    BladeSpacing="10" />

BladeView renders a backdrop plus a horizontal ListBox of blade cards and keeps only the newest blade interactive; every earlier card is dimmed to DisabledOpacity.

• ItemsSource — the blade views to host, in opening order.
• Anchor — BladeViewAnchor, default Auto: the logical edge the pane is anchored to (Auto resolves to End, i.e. the right edge in a left-to-right culture).
• BladeAlignment — read-only, resolved physical HorizontalAlignment published by the control. It is already mirrored for right-to-left, is consumed by the control template, and must never be hardcoded in XAML.
• HorizontalBladeAlignment — the left-to-right intent (Right by default). It is only used as the base value that BladeAlignment mirrors when Anchor is Auto; prefer Anchor for new call sites.
• DisabledOpacity (0.75), BladeSpacing (10), InnerPadding (8), BladeHeight, AutoCollapseThreshold, Orientation.

Blades are opened through IBladeService.OpenBladeAsync<TBladeViewModel, TEntity>(owner, ...); the owner view model implements IViewModelBladeView (Blades, IsPaneVisible). Here the shell itself is the owner (BaseShellViewModel : ViewModelBladeView<NavigationItem>), so its BladeView hosts every shell-level blade — the sample opens Settings exactly that way.

ImageBrowser

<controls:ImageBrowser Images="{x:Bind ViewModel.ProductImages, Mode=OneWay}"
                       SelectedImage="{x:Bind ViewModel.SelectedImage, Mode=TwoWay}"
                       AllowAdd="True"
                       AllowRemove="True" />

SplashScreen

<controls:SplashScreen x:Class="MyApp.CustomSplashScreen"
                       Logo="/Assets/logo.png"
                       Message="Loading application..."
                       ShowProgress="True" />

5. Live Localization with Indexer Binding

Bind to LocalizedStrings.Default indexer for automatic language switching at runtime:

// In code-behind or ViewModel
public sealed partial class MainWindow : Window
{
    public LocalizedStrings Strings => LocalizedStrings.Default;

    public MainWindow()
    {
        InitializeComponent();
        DataContext = this;
    }
}

<TextBlock Text="{x:Bind Strings[WelcomeMessage], Mode=OneWay}" />
<TextBlock Text="{x:Bind Strings[GreetingText], Mode=OneWay}" />

When language changes:

var newCulture = new CultureInfo("es-ES");
newCulture.ApplyCulture();  // Triggers PropertyChanged("Item[]") on LocalizedStrings.Default

All bound controls automatically update with new translations.

Note: WinUI 3 does not support x:Static markup extension (a XAML 2009 feature). Use the property-binding workaround shown above, or store LocalizedStrings.Default in a public property.

Right-to-left

The app content is mirrored through XAML FlowDirection, not through the native window style:

• The window root receives FlowDirection in Application.OnLaunched from LocalSettings.Language, so every page inherits it.
• NavigationService.SetWindowContent re-applies it from CultureInfo.CurrentUICulture for window-level pages, because a page assigned as the window content is a new root and does not inherit.
• The native WS_EX_LAYOUTRTL window style is still applied, but only for the non-client area (caption buttons and native title text); the XAML content is composed outside GDI and is mirrored by FlowDirection.
• FrameworkElementExtensions.ApplyFlowDirection accepts a nullable culture name; null or whitespace means left-to-right.

Blading follows the logical anchor: Anchor is Start/End/Auto, BladeView resolves the physical edge with BladePlacement, forces its ListBox to LeftToRight so the alignment is physical, and mirrors each card's content through FlowDirection.

Fluent Design Integration

WinUI 3 provides modern Fluent Design features:

<Grid Background="{ThemeResource ApplicationPageBackgroundThemeBrush}">
    
</Grid>


<Grid Background="{ThemeResource SystemControlAcrylicWindowBrush}">
    
</Grid>


<Button Style="{StaticResource AccentButtonStyle}"
        Content="Click Me">
    
</Button>


<Border CornerRadius="8"
        Shadow="{StaticResource SharedShadow}">
    <Image Source="/Assets/image.png"/>
</Border>

Theme Support

The WinUI framework includes 40+ built-in theme palettes with modern Fluent Design:

using ISynergy.Framework.Mvvm.Abstractions.Services;

// Theme is automatically applied on startup
// Accent color is synchronized with Windows system accent

// Light/dark switching is built into the shell: ThemeCommand toggles through IThemeService.
// Language, theme and accent color are selected in your own settings blade/page.

Title Bar Customization

Customize the Windows 11 title bar:

public sealed partial class MainWindow : Window
{
    public MainWindow()
    {
        InitializeComponent();

        // Extend content into title bar
        ExtendsContentIntoTitleBar = true;
        SetTitleBar(AppTitleBar);

        // Customize title bar colors
        if (AppWindowTitleBar.IsCustomizationSupported())
        {
            var titleBar = AppWindow.TitleBar;
            titleBar.BackgroundColor = Colors.Transparent;
            titleBar.ButtonBackgroundColor = Colors.Transparent;
            titleBar.ButtonHoverBackgroundColor = Color.FromArgb(25, 255, 255, 255);
        }
    }
}

Behaviors

Using CommunityToolkit.WinUI.Behaviors:

<Page xmlns:interactivity="using:Microsoft.Xaml.Interactivity"
      xmlns:behaviors="using:CommunityToolkit.WinUI.Behaviors">

    <TextBox>
        <interactivity:Interaction.Behaviors>
            <behaviors:FocusBehavior />
        </interactivity:Interaction.Behaviors>
    </TextBox>

    <ListView ItemsSource="{x:Bind Items}">
        <interactivity:Interaction.Behaviors>
            <behaviors:SelectAllBehavior />
        </interactivity:Interaction.Behaviors>
    </ListView>
</Page>

Best Practices

Performance

• Use x:Bind for compiled bindings
• Implement virtualization for large lists
• Use Mica/Acrylic sparingly for performance
• Dispose resources properly
• Leverage hardware acceleration

Windows 11 Features

• Use Mica material for window backgrounds
• Customize title bar with Windows 11 styles
• Implement snap layouts support
• Use rounded corners for modern look
• Leverage system accent color

Dependencies

• I-Synergy.Framework.UI - Base UI abstractions
• Microsoft.WindowsAppSDK - Windows App SDK
• CommunityToolkit.WinUI.Behaviors - WinUI behaviors
• Microsoft.Extensions.Configuration.Json - Configuration
• Microsoft.Extensions.Hosting - Application hosting

Platform Requirements

• Target Framework: net10.0-windows10.0.26100.0
• Minimum Version: Windows 10.0.26100.0 (Version 2004)
• Recommended: Windows 11 for best experience
• Architecture: x86, x64, ARM64

Documentation

• Framework Documentation
• WinUI 3 Documentation
• Windows App SDK
• Sample Applications

Related Packages

• I-Synergy.Framework.UI - Base UI abstractions
• I-Synergy.Framework.Core - Core framework
• I-Synergy.Framework.Mvvm - MVVM framework
• I-Synergy.Framework.UI.WPF - WPF implementation
• I-Synergy.Framework.UI.Maui - MAUI implementation

Support

For issues, questions, or contributions, please visit the GitHub repository.