WinUI 3 Compatibility Layer (WinUI3Compat)

English | 简体中文

WinUI 3 (Windows App SDK) is Microsoft's modern native UI platform for Windows, bringing Fluent Design, WinRT, and advanced composition to desktop apps. However, by default, WinUI 3 strictly requires Windows 10 (version 1809) or newer. Running a standard WinUI 3 application on Windows 7 results in immediate process termination due to missing APIs (DirectComposition, modern Direct2D, UCRT, WinRT core components, etc.).

WinUI3Compat solves this problem entirely. It provides a robust, seamless, and performant compatibility layer that allows unmodified WinUI 3 applications to run on Windows 7 with 100% Fluent 2 visual parity and full feature availability.

Crucially, WinUI3Compat achieves this under ZERO system patches. It requires:

• No KB2670838 (Windows 7 Platform Update)
• No KB2999226 (Universal C Runtime in Windows)
• Works flawlessly even with DWM disabled (Windows 7 Basic / Classic theme)

Through advanced PE interception, custom rendering fallbacks, and comprehensive API polyfills, your application can target the latest WinUI 3 ecosystem while effortlessly reaching legacy enterprise clients.

WinUI3Compat adapts its operation mode dynamically based on the host OS environment:

WinUI3Compat operates invisibly beneath the application, seamlessly intercepting and translating modern API calls to legacy equivalents or custom implementations.

flowchart TD
    App["WinUI 3 Application"] --> |"API Calls"| Hook["WinUI3Compat Hooking Engine"]
    Hook --> |"Modern OS"| Native["Native Windows 10/11 APIs"]
    Hook --> |"Legacy OS"| Router["Compatibility Router"]
    
    Router --> |"Graphics"| GFX["Dual-Engine Graphics Pipeline"]
    Router --> |"Windowing"| WND["DWM-Free Modern Window Frame"]
    Router --> |"Core/WinRT"| Poly["API Polyfills & Emulation"]
    
    GFX --> D2D11["D2D 1.1 / DComp via Platform Update"]
    GFX --> D2D10["D2D 1.0 / DXGI 1.1 Fallback"]
    
    WND --> CustomNC["WM_NCCALCSIZE & Custom Hit-Test"]
    WND --> Shadow["32-bit ARGB Layered Drop Shadow"]
    
    Poly --> WinRT["WinRT HSTRING & Activation"]
    Poly --> Sys["PathCch, WaitOnAddress, etc."]

• IAT & Delay-Load Interception: At startup, atomically rewrites Import Address Tables and Delay-Load hooks for target modules (e.g., Microsoft.ui.xaml.dll, dcomp.dll).
• Zydis Boundary Disassembler: Uses Zydis to perform accurate instruction length decoding and prologue validation before patching.
• MinHook Integration: Employs MinHook for robust trampoline relocation and detouring of dynamically resolved function pointers.

• Modern Path (D2D 1.1 / DComp): When the Windows 7 Platform Update is present, seamlessly bridges modern DirectComposition APIs to Windows 7 D2D 1.1.
• Legacy Fallback (D2D 1.0 / DXGI 1.1): When no updates are present, translates complex DComp visual trees and modern Direct2D commands into an explicit CreateLayer / PushLayer D2D 1.0 rendering loop.

• Border Stripping: Intercepts WM_NCCALCSIZE to completely remove native legacy borders.
• Hit Testing: Processes WM_NCHITTEST to provide accurate caption dragging and border resizing on custom drawn windows.
• Smooth Corners: Utilizes CreateRoundRectRgn (16px) for modern rounded corners, even on Classic themes.
• Drop Shadow Follower: Synchronizes a secondary, invisible 32-bit ARGB GDI layered window (WS_EX_LAYERED) behind the main window to render smooth, alpha-blended drop shadows when the Desktop Window Manager (DWM) is disabled.

• WinRT Core: Fast-pass implementations for HSTRING allocation/reference, RoGetActivationFactory, and PropertySet.
• System APIs: Provides functional equivalents for GetSystemTimePreciseAsFileTime, WaitOnAddress, and PathCch.
• Input & UI: Translates WM_TOUCH into modern multi-touch pointer events.
• Typography & Styling: Mounts the Segoe Fluent Icons font privately via DirectWrite to ensure iconography renders without installing fonts system-wide.
• Visual Emulation: Provides a software-based MicaSimulator and an emulated stacked Toast notification system.

WinUI3Compat is designed to be frictionless. Choose the mode that fits your project.

No user code changes required. The NuGet package automatically injects a [ModuleInitializer] and copies the necessary App-Local DLLs.

1. Install the NuGet package:

   dotnet add package WinUI3Compat

2. Rebuild your project. MSBuild targets will automatically deploy the App-Local UCRT and WinUI3Compat.dll.
3. The initialization runs automatically via AutoInitializer.cs before WinUI 3 boots.

For C++ applications that prefer a shared DLL approach.

1. Link against WinUI3Compat.lib and ensure WinUI3Compat.dll is in your application directory.
2. Initialize early in main or wWinMain:

#include <WinUI3Compat.h>

int APIENTRY wWinMain(HINSTANCE hInstance, HINSTANCE, PWSTR pCmdLine, int nCmdShow) {
    // Initialize before any WinRT or WinUI 3 APIs are called
    WinUI3Compat_Initialize();
    
    // ... Initialize WinUI 3 Application ...
    
    WinUI3Compat_Shutdown();
    return 0;
}

For C++ applications requiring a single monolithic executable.

1. Link against WinUI3Compat_static.lib (built with /MT).
2. Initialization is fully automatic. The library uses the TLS .CRT$XLB segment to bootstrap the hooking engine before main or WinMain executes.
3. No manual initialization calls are required, and no external DLLs need to be shipped.

• Visual Studio 2022 (MSVC v143+)
• CMake 3.20+
• Windows SDK (10.0.22000.0 or later recommended)

To build the static and dynamic libraries for both x64 and x86 architectures:

# Clone the repository
git clone https://github.com/laststudio/winui3compat.git
cd winui3compat/winui3_compat_layer

# Configure CMake (x64 Release with /MT)
cmake -B build_x64 -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release -DUSE_STATIC_CRT=ON

# Build x64
cmake --build build_x64 --config Release

# Configure CMake (x86 Release with /MT)
cmake -B build_x86 -G "Visual Studio 17 2022" -A Win32 -DCMAKE_BUILD_TYPE=Release -DUSE_STATIC_CRT=ON

# Build x86
cmake --build build_x86 --config Release

WinUI3Compat includes a comprehensive test suite covering API hooking, polyfills, and rendering logic.

cd build_x64
ctest -C Release

(Expected output: 11/11 tests passed)

You can fine-tune the compatibility layer by configuring it before or during initialization:

WinUI3Compat_Config config = {0};
config.ForceD2D10Fallback = false; // Set to true to test D2D 1.0 path on modern OS
config.EnableMicaEmulation = true;
config.DisableDropShadow = false;
WinUI3Compat_SetConfig(&config);

WinUI3Compat maintains an in-memory Ring Logger. In the event of an unhandled exception or failed hook, the SEH (Structured Exception Handling) crash dump handler automatically flushes this log to disk alongside a minidump to aid in debugging.

• Log Location: %LOCALAPPDATA%\YourAppName\Logs\WinUI3Compat.log
• Crash Dumps: %LOCALAPPDATA%\YourAppName\CrashDumps\

winui3_compat_layer/
├── src/
│   ├── core/             # Lifecycle bootstrap, capability router, module tracker, TLS
│   ├── diagnostics/      # In-memory ring logger, SEH crash dump handler
│   ├── hook/             # PE IAT/Delay-Load patcher, Zydis disassembler, MinHook
│   ├── polyfills/        # WinRT, kernel32, user32, DComp graphics engine, fonts, toasts, media
│   └── bindings/         # C# drop-in wrapper, AutoInitializer, NuGet props/targets
├── include/              # Public C/C++ API headers (WinUI3Compat.h)
├── tests/                # CTest unit test suite (11 unit tests)
├── 3rdparty/             # MinHook, Zydis, Zycore submodules
└── CMakeLists.txt        # Root CMake build script

Q: My application still crashes on launch on Windows 7. A: Ensure that you are deploying the App-Local UCRT (ucrtbase.dll, api-ms-win-core-*.dll) alongside your executable. The NuGet package handles this automatically, but manual C++ deployments require explicitly copying these files.

Q: Why does the UI look slightly different on Windows 7 Basic theme? A: When DWM is disabled (Basic/Classic theme), hardware-accelerated composition is unavailable. WinUI3Compat falls back to a software-composed CreateLayer stack. While visual parity is 100%, performance may be slightly lower for complex animations.

Q: Does this support Webview2 in WinUI 3? A: Yes, Webview2 functions normally. The compatibility layer ensures that the required window handles and message loops behave as Webview2 expects, even on legacy systems.

Q: Can I use this for non-WinUI 3 apps (e.g., Raw DComp apps)? A: While primarily tailored for WinUI 3 (Microsoft.UI.Xaml), the DComp and D2D hooking engines are generic enough to intercept and translate many native DirectComposition applications. Mileage may vary.

WinUI3Compat is an independent project and is not affiliated with or endorsed by Microsoft Corporation. Windows and WinUI are trademarks of Microsoft Corporation.