Skip to content

Commit 7a7b29f

Browse files
GrantMeStrengthCopilot
GrantMeStrength
and
Copilot
committed
Add WPF patterns and WinUI 3 equivalents article
New concept article mapping common WPF patterns to their WinUI 3 equivalents. Covers controls, XAML features, threading, app model, resources/localization, printing, and developer tooling. Framed as a patterns mapping guide rather than a gaps list, to help developers plan migration with confidence and understand the modern WinUI 3 approach for each scenario. Co-authored-by: Copilot <[email protected]>
1 parent 15308a1 commit 7a7b29f

1 file changed

Lines changed: 91 additions & 0 deletions

File tree

‎hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/wpf-patterns-winui3.md‎

Lines changed: 91 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,91 @@
1+
---
2+
title: WPF patterns and their WinUI 3 equivalents
3+
description: WinUI 3 was designed for modern Windows from the ground up. This topic maps familiar WPF patterns to their WinUI 3 equivalents, and describes the modern approach for cases where the pattern has evolved.
4+
ms.topic: concept-article
5+
ms.date: 04/07/2026
6+
keywords: windows, app, sdk, wpf, winui, winui3, migration, patterns, equivalents
7+
ms.localizationpriority: medium
8+
---
9+
10+
# WPF patterns and their WinUI 3 equivalents
11+
12+
WPF is a mature framework built over two decades, and WinUI 3 is a modern UI platform designed for Windows 10 and Windows 11 from the ground up. Most WPF concepts have direct equivalents in WinUI 3. In some areas, WinUI 3 introduces a better approach that replaces an older pattern. And in a few cases, features are still being actively developed.
13+
14+
This topic maps common WPF patterns to their WinUI 3 equivalents so you can plan your migration with confidence.
15+
16+
> [!TIP]
17+
> For UWP-to-WinUI 3 migration guidance, see [What's supported when migrating from UWP to WinUI 3](what-is-supported.md). For general WPF + Windows App SDK guidance, see [Use the Windows App SDK in a WPF app](wpf-plus-winappsdk.md).
18+
19+
## Controls
20+
21+
Most WPF controls have direct equivalents in WinUI 3. The following table covers controls where the mapping is not one-to-one.
22+
23+
| WPF control | WinUI 3 equivalent | Notes |
24+
|---|---|---|
25+
| `DataGrid` | [DataGrid (Community Toolkit)](/dotnet/communitytoolkit/maui/views/datagrid) | The WinUI 3 Community Toolkit provides a DataGrid control. Most common WPF DataGrid features are supported; see the toolkit docs for specifics. |
26+
| `InkCanvas` / `InkToolbar` | Under active development | Ink support in WinUI 3 is being actively developed. Follow [microsoft-ui-xaml #1000](https://github.com/microsoft/microsoft-ui-xaml/issues/1000) for updates. In the meantime, you can host the WPF `InkCanvas` via [XAML Islands](../../desktop/modernize/xaml-islands/xaml-islands.md). |
27+
| `Ribbon` | `CommandBar` / `CommandBarFlyout` | Consider [CommandBar](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.commandbar) and [CommandBarFlyout](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.commandbarflyout) for toolbar-style scenarios. For a full ribbon surface, the [Fluent UI React](https://developer.microsoft.com/fluentui) component via WebView2 is an option for hybrid apps. |
28+
| `StatusBar` | `InfoBar` + custom layout | Use [InfoBar](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.infobar) for status messaging, or add a dedicated footer area to your layout. |
29+
| `FlowDocumentReader` / `FlowDocumentScrollViewer` | `RichTextBlock` | Use [RichTextBlock](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.richtextblock) for read-only rich text display. WinUI 3 takes a different approach to document content that is better suited to modern app scenarios. |
30+
| `PasswordBox` with `SecureString` | `PasswordBox` | WinUI 3's [PasswordBox](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.passwordbox) provides password masking. `SecureString` is deprecated in .NET 5+; the recommended approach is to minimize how long credentials are held in memory using `ReadOnlySpan<char>` patterns. |
31+
| `WebBrowser` | [WebView2](/microsoft-edge/webview2/) | `WebView2` uses the modern Microsoft Edge (Chromium) engine and is the recommended approach for embedding web content across all desktop app types. |
32+
33+
## XAML features
34+
35+
WinUI 3 XAML is closely related to UWP XAML, and shares the same core engine. Some WPF-specific XAML features have evolved into more composable, testable alternatives.
36+
37+
| WPF feature | WinUI 3 approach | Notes |
38+
|---|---|---|
39+
| `DataTrigger` / `MultiTrigger` | [Behaviors (Community Toolkit)](https://aka.ms/toolkit/behaviors) | WinUI 3 uses attached behaviors rather than inline triggers. The XAML Behaviors package supports `DataTriggerBehavior`, `EventTriggerBehavior`, and more. Behaviors are more composable and unit-testable than WPF triggers. |
40+
| `DynamicResource` | `ThemeResource` | `ThemeResource` provides runtime resource lookup and responds automatically to theme changes (light, dark, high contrast). Use `StaticResource` for values that never change at runtime. |
41+
| `MultiBinding` / `PriorityBinding` | Converters or `x:Bind` | Use a multi-value converter with individual bindings, or use `x:Bind` with a computed property on your view model. `x:Bind` is compiled and type-safe, which makes it more performant than `Binding`. |
42+
| `Style` with `BasedOn` | ✅ Supported | Style inheritance with `BasedOn` works in WinUI 3. |
43+
| Implicit styles | ✅ Supported | Resource dictionary implicit styles (styles without `x:Key`) work as expected. |
44+
| `AdornerLayer` | Custom overlay approach | For validation visuals, use the built-in [InputValidation](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.textbox.inputvalidationkind) support in text controls. For custom overlays, use a `Canvas` or `Grid` overlay layer in your layout — this is more explicit and easier to reason about than WPF's adorner layer. |
45+
46+
## Threading and dispatch
47+
48+
| WPF pattern | WinUI 3 equivalent | Notes |
49+
|---|---|---|
50+
| `Dispatcher.Invoke` / `BeginInvoke` | `DispatcherQueue.TryEnqueue` | WinUI 3 uses [DispatcherQueue](/windows/windows-app-sdk/api/winrt/microsoft.ui.dispatching.dispatcherqueue). The async pattern is `await DispatcherQueue.EnqueueAsync(...)` using the Community Toolkit extension. |
51+
| `Application.Current.Dispatcher` | `DispatcherQueue.GetForCurrentThread()` | Capture the `DispatcherQueue` at construction time on the UI thread and store it for later use on background threads. |
52+
| `BackgroundWorker` | `Task` / `async`-`await` | Modern .NET async patterns are the right approach in WinUI 3. `Task`, `CancellationToken`, and `IProgress<T>` cover all `BackgroundWorker` scenarios and integrate naturally with `x:Bind`. |
53+
54+
## App model and lifecycle
55+
56+
| WPF concept | WinUI 3 equivalent | Notes |
57+
|---|---|---|
58+
| `Application.Startup` / `Exit` events | `App.OnLaunched` / `Window.Closed` | WinUI 3 uses `OnLaunched` in `App.xaml.cs` as the entry point. Per-window teardown is handled in `Window.Closed`. |
59+
| `Application.Current.MainWindow` | Your `Window` instance | Hold a reference to your window instance in `App.xaml.cs` and expose it as a property. |
60+
| `Window` subclassing | [AppWindow](/windows/windows-app-sdk/api/winrt/microsoft.ui.windowing.appwindow) customization | WinUI 3 windows are customized through `AppWindow` (title bar, presenter, overlapped/fullscreen/compact overlay modes) rather than subclassing. See [Manage app windows](../../develop/ui/windowing/manage-app-windows.md). |
61+
| `SystemParameters` | `DisplayArea` / `UISettings` | System display properties are available through [DisplayArea](/windows/windows-app-sdk/api/winrt/microsoft.ui.windowing.displayarea) and [UISettings](/uwp/api/windows.ui.viewmanagement.uisettings). |
62+
63+
## Resources and localization
64+
65+
| WPF pattern | WinUI 3 equivalent | Notes |
66+
|---|---|---|
67+
| `.resx` resource files | `.resw` + `ResourceLoader` | WinUI 3 uses `.resw` files and the [ResourceLoader](/windows/windows-app-sdk/api/winrt/microsoft.windows.applicationmodel.resources.resourceloader) API. The .NET Upgrade Assistant can automate much of this conversion. |
68+
| `x:Static` markup extension | `x:Bind` to a static property | Use `x:Bind` with a static property or a singleton accessor. `x:Bind` is compiled and produces clearer error messages than `x:Static`. |
69+
| Merged resource dictionaries | ✅ Supported | `ResourceDictionary.MergedDictionaries` works in WinUI 3. |
70+
| Theme-specific resource dictionaries | ✅ Supported | `ResourceDictionary.ThemeDictionaries` is the WinUI 3 mechanism for per-theme resources, and integrates with automatic dark/light mode switching. |
71+
72+
## Printing
73+
74+
| WPF feature | WinUI 3 status | Notes |
75+
|---|---|---|
76+
| `PrintDialog` / `PrintDocument` | [PrintManager](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.printing.printmanager) | Full printing support is available via `PrintManager`. See [Print from your app](/windows/apps/develop/print-and-capture/printing-and-scanning). |
77+
78+
## Developer tooling
79+
80+
| WPF tooling | WinUI 3 status | Notes |
81+
|---|---|---|
82+
| XAML Designer (Design tab) | Not yet supported | The Visual Studio XAML Designer doesn't currently support WinUI 3 projects. [XAML Hot Reload](/visualstudio/xaml-tools/xaml-hot-reload) is supported and is the recommended way to iterate on layout and styles without stopping the debugger. |
83+
| Blend for Visual Studio | Limited support | Blend can open WinUI 3 projects but Design view is not available. |
84+
85+
## See also
86+
87+
- [Use the Windows App SDK in a WPF app](wpf-plus-winappsdk.md)
88+
- [What's supported when migrating from UWP to WinUI 3](what-is-supported.md)
89+
- [Overall migration strategy](overall-migration-strategy.md)
90+
- [Windows Community Toolkit](/dotnet/communitytoolkit/introduction)
91+
- [XAML Behaviors (Community Toolkit)](https://aka.ms/toolkit/behaviors)

0 commit comments

Comments
 (0)