WPF UI - Architecture Documentation

Property	Value
Project	WPF UI (wpfui)
Version	4.2.0
Type	Open-source WPF UI control library
License	MIT
Language	C# 14 / XAML
Platforms	.NET 10/9/8 + .NET Framework 4.6.2/4.7.2/4.8.1

Overview

WPF UI is an open-source library that implements the Microsoft Fluent Design System for Windows Presentation Foundation (WPF) applications. It provides 77+ custom controls, a full theming system with light/dark/high-contrast modes, Win32 interop for modern window chrome effects (Mica, Acrylic, Tabbed backdrops), navigation services, and icon support through the Fluent System Icons font family.

The library enables thousands of developers to modernize legacy WPF applications with contemporary Windows 11 visual styles without migrating to WinUI 3 or MAUI.

Architecture Views

Document	Description
C4 Context (Level 1)	System context diagram showing WPF UI in its environment -- consumer applications, Windows OS, distribution channels
Logical Architecture	Module dependencies, layer diagram, core library internal component structure, detected patterns

Software Design Documents (SDD)

Document	Description
CONSTITUTION.md	Project constitution -- coding conventions, boundary system (ALWAYS DO / ASK FIRST / NEVER DO), rules files summary
IMPLEMENTATION-GUIDE.md	Step-by-step guides for common tasks -- adding controls, services, gallery pages, Win32 interop, theming, testing
TESTING-SPEC.md	Testing specification -- frameworks, templates, naming conventions, run commands
MODULE-INTERFACES.md	Module interface contracts -- public vs internal API surface per module, dependency rules

Cross-Cutting Concerns

Document	Description
Testing	Test strategy, frameworks, naming conventions, coverage gaps
Theming and Appearance	Theme system architecture, accent colors, backdrop effects, theme change flow
Win32 Interop	Three-layer interop architecture, key APIs, handle validation, WndProc patterns
Navigation	Navigation system lifecycle, page caching strategy, DI integration, transition animations

Architecture Decision Records (ADRs)

ADR	Decision
ADR-001	Multi-target framework strategy (net10.0 through net462)
ADR-002	WPF control library architecture with Fluent Design
ADR-003	Win32 interop via CsWin32 source generator
ADR-004	Static singleton managers for theming (implicit)
ADR-005	Feature-folder organization for controls (implicit)

Other

Document	Description
RECOMMENDATIONS.md	Prioritized architectural improvement recommendations
UNCERTAINTIES.md	Areas needing further investigation
Diagrams Index	Index of all architecture diagrams
LikeC4 Diagrams	Interactive C4 diagrams in LikeC4 DSL format

Quick Architecture Summary

WPF UI is organized as a set of layered NuGet packages built from a single solution:

Wpf.Ui.Abstractions -- Zero-dependency contract interfaces (INavigationViewPageProvider, INavigationAware, INavigableView<T>). Targets .NET and .NET Standard 2.0/2.1 for maximum portability.
Wpf.Ui -- Core library with 77+ controls, the theming engine, Win32 interop, services, converters, animations, and icon support. This is the primary NuGet package (WPF-UI).
Wpf.Ui.DependencyInjection -- Microsoft.Extensions.DependencyInjection integration for type-based page resolution.
Wpf.Ui.Tray -- System tray icon support via Shell32 P/Invoke.
Wpf.Ui.SyntaxHighlight -- Syntax-highlighted code display control.
Wpf.Ui.ToastNotifications -- Toast notification support (stub, not yet implemented).
Wpf.Ui.FlaUI -- FlaUI automation element wrappers for integration testing.
Wpf.Ui.FontMapper -- Build-time tool that generates SymbolRegular/SymbolFilled enums from Fluent System Icons font data.
Wpf.Ui.Gallery -- Comprehensive demo application showcasing all controls.
Wpf.Ui.Extension -- Visual Studio 2022 extension with project templates.

Key Architectural Concerns

Control Architecture -- Folder-per-control pattern with paired .cs + .xaml files. Controls extend standard WPF base classes and implement capability interfaces (IAppearanceControl, IIconControl).
Theming System -- Runtime resource dictionary swapping managed by ApplicationThemeManager. Accent colors derived from system settings via WinRT UISettings or DWM registry.
Win32 Interop -- Three-layer architecture: CsWin32 source-generated P/Invoke, managed wrappers (UnsafeNativeMethods), and high-level utilities. Enables DWM backdrop effects, custom window chrome, and system theme detection.

Technology Stack

mindmap
  root((WPF UI 4.2.0))
    Languages
      C# 14 (LangVersion preview)
      XAML
    Target Frameworks
      .NET 10.0-windows
      .NET 9.0-windows
      .NET 8.0-windows
      .NET Framework 4.8.1
      .NET Framework 4.7.2
      .NET Framework 4.6.2
      .NET Standard 2.0/2.1
        Abstractions only
    Build & Tooling
      MSBuild / dotnet CLI
      Central Package Management
        Directory.Packages.props
      CSharpier formatter
        110 char width
      Source generators
        CsWin32 P/Invoke
        PolySharp polyfills
        CommunityToolkit.Mvvm
      Analyzers
        WpfAnalyzers
        StyleCop
        AsyncFixer
        IDisposableAnalyzers
      Strong-name signing
        lepo.snk
      SourceLink
        Microsoft.SourceLink.GitHub
    Win32 / Native
      DWM APIs
        Mica / Acrylic / Tabbed backdrops
        Window corner preference
        Dark mode attribute
      User32
        SetWindowLong / GetWindowLong
        Window message handling
      Shell32
        System tray icons
        Taskbar progress
      COM ITaskbarList4
    Testing
      XUnit v2 / v3
      NSubstitute mocking
      AwesomeAssertions
      FlaUI UI automation
      Coverlet coverage
    CI/CD
      GitHub Actions
        PR validator
        NuGet publish
        VS Extension build
        DocFX documentation
      NuGet.org distribution
      GitHub Pages docs
    Design System
      Microsoft Fluent Design
      Fluent System Icons
        Regular + Filled TTF fonts
      Theme system
        Light / Dark / High Contrast
      Accent color system
        WinRT UISettings integration

Repository Structure

wpfui/
  src/
    Wpf.Ui/                          Core library (NuGet: WPF-UI)
      Controls/                       77 control subdirectories
      Appearance/                     Theme management system
      Animations/                     Transition animations
      Converters/                     XAML value converters
      Extensions/                     Extension methods
      Hardware/                       DPI and rendering detection
      Input/                          IRelayCommand pattern
      Interop/                        Win32 managed wrappers
      Markup/                         XAML markup extensions
      Resources/                      Theme dictionaries, fonts
      Taskbar/                        Taskbar progress COM
      Win32/                          OS version utilities
    Wpf.Ui.Abstractions/             Contracts (multi-target)
    Wpf.Ui.DependencyInjection/      MS DI integration
    Wpf.Ui.Tray/                     System tray support
    Wpf.Ui.SyntaxHighlight/          Code display control
    Wpf.Ui.ToastNotifications/       Toast notifications (stub)
    Wpf.Ui.FlaUI/                    FlaUI automation helpers
    Wpf.Ui.FontMapper/               Icon enum code generator
    Wpf.Ui.Gallery/                  Demo/showcase application
    Wpf.Ui.Extension/                VS 2022 extension
  samples/
    Wpf.Ui.Demo.Simple/              Minimal no-DI sample
    Wpf.Ui.Demo.Mvvm/                Full MVVM + DI sample
    Wpf.Ui.Demo.Console/             .NET Framework 4.7.2 console sample
    Wpf.Ui.Demo.Dialogs/             ContentDialog sample
    Wpf.Ui.Demo.SetResources.Simple/ Manual resource management sample
  tests/
    Wpf.Ui.UnitTests/                XUnit unit tests
    Wpf.Ui.Gallery.IntegrationTests/ FlaUI integration tests
  docs/                              DocFX documentation site
  .github/                           CI/CD workflows, templates

8.9 KiB Raw Blame History