You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: hub/apps/windows-app-sdk/migrate-to-windows-app-sdk/wpf-patterns-winui3.md
+14-14Lines changed: 14 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -22,33 +22,33 @@ Most WPF controls have direct equivalents in WinUI 3. The following table covers
22
22
23
23
| WPF control | WinUI 3 equivalent | Notes |
24
24
|---|---|---|
25
-
|`DataGrid`| No first-party equivalent | WinUI 3 does not include a built-in DataGrid. The community-maintained [WinUI.TableView](https://github.com/w-ahmad/WinUI.TableView) is one option. Evaluate community projects based on your support and maintenance requirements. |
26
-
|`Ribbon`|`CommandBar` / Community Toolkit Labs | 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. A [Ribbon control](https://github.com/CommunityToolkit/Labs-Windows/tree/main/components/Ribbon) is also available in Community Toolkit Labs (experimental). |
27
-
|`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. |
28
-
|`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. |
29
-
|`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. |
30
-
|`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. |
25
+
|[`DataGrid`](/dotnet/api/system.windows.controls.datagrid)| No first-party equivalent | WinUI 3 does not include a built-in DataGrid. The community-maintained [WinUI.TableView](https://github.com/w-ahmad/WinUI.TableView) is one option. Evaluate community projects based on your support and maintenance requirements. |
26
+
|[`Ribbon`](/dotnet/api/system.windows.controls.ribbon.ribbon)|`CommandBar` / Community Toolkit Labs | 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. A [Ribbon control](https://github.com/CommunityToolkit/Labs-Windows/tree/main/components/Ribbon) is also available in Community Toolkit Labs (experimental). |
27
+
|[`StatusBar`](/dotnet/api/system.windows.controls.primitives.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. |
28
+
|[`FlowDocumentReader`](/dotnet/api/system.windows.controls.flowdocumentreader) / [`FlowDocumentScrollViewer`](/dotnet/api/system.windows.controls.flowdocumentscrollviewer)|[`RichTextBlock`](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.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. |
29
+
|[`PasswordBox`](/dotnet/api/system.windows.controls.passwordbox) with `SecureString`|[`PasswordBox`](/windows/windows-app-sdk/api/winrt/microsoft.ui.xaml.controls.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. |
30
+
|[`WebBrowser`](/dotnet/api/system.windows.controls.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. |
31
31
32
32
## XAML features
33
33
34
34
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.
35
35
36
36
| WPF feature | WinUI 3 approach | Notes |
37
37
|---|---|---|
38
-
|`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. |
39
-
|`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. |
40
-
|`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`. |
38
+
|[`DataTrigger`](/dotnet/api/system.windows.datatrigger) / [`MultiTrigger`](/dotnet/api/system.windows.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. |
39
+
|[`DynamicResource`](/dotnet/desktop/wpf/advanced/dynamicresource-markup-extension)|[`ThemeResource`](/windows/uwp/xaml-platform/themeresource-markup-extension)|`ThemeResource` provides runtime resource lookup and responds automatically to theme changes (light, dark, high contrast). Use `StaticResource` for values that never change at runtime. |
40
+
|[`MultiBinding`](/dotnet/api/system.windows.data.multibinding) / [`PriorityBinding`](/dotnet/api/system.windows.data.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`. |
41
41
|`Style` with `BasedOn`| ✅ Supported | Style inheritance with `BasedOn` works in WinUI 3. |
42
42
| Implicit styles | ✅ Supported | Resource dictionary implicit styles (styles without `x:Key`) work as expected. |
43
-
|`AdornerLayer`| Custom overlay approach |For validation visuals, use the built-in built-in input validation support in text controls (input validation is supported on text controls in WinUI 3). 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. |
43
+
|[`AdornerLayer`](/dotnet/api/system.windows.documents.adornerlayer)| Custom overlay approach |WinUI 3 has no adorner layer equivalent. Use a `Canvas` or `Grid` overlay in your layout to achieve similar visual decoration effects — this approach is more explicit and easier to reason about. |
44
44
45
45
## Threading and dispatch
46
46
47
47
| WPF pattern | WinUI 3 equivalent | Notes |
48
48
|---|---|---|
49
-
|`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. |
50
-
|`Application.Current.Dispatcher`|`DispatcherQueue.GetForCurrentThread()`| Capture the `DispatcherQueue` at construction time on the UI thread and store it for later use on background threads. |
51
-
|`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`. |
49
+
|[`Dispatcher.Invoke`](/dotnet/api/system.windows.threading.dispatcher.invoke) / `BeginInvoke`|[`DispatcherQueue.TryEnqueue`](/windows/windows-app-sdk/api/winrt/microsoft.ui.dispatching.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. |
50
+
|[`Application.Current.Dispatcher`](/dotnet/api/system.windows.application.current)|[`DispatcherQueue.GetForCurrentThread()`](/windows/windows-app-sdk/api/winrt/microsoft.ui.dispatching.dispatcherqueue.getforcurrentthread)| Capture the `DispatcherQueue` at construction time on the UI thread and store it for later use on background threads. |
51
+
|[`BackgroundWorker`](/dotnet/api/system.componentmodel.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`. |
52
52
53
53
## App model and lifecycle
54
54
@@ -72,7 +72,7 @@ WinUI 3 XAML is closely related to UWP XAML, and shares the same core engine. So
72
72
73
73
| WPF feature | WinUI 3 status | Notes |
74
74
|---|---|---|
75
-
|`PrintDialog` / `PrintDocument`|[PrintManager](/uwp/api/windows.graphics.printing.printmanager)| Full printing support is available via `PrintManager`. See [Print from your app](/windows/apps/develop/devices-sensors/print-from-your-app). |
75
+
|[`PrintDialog`](/dotnet/api/system.windows.controls.printdialog) / [`PrintDocument`](/dotnet/api/system.drawing.printing.printdocument)|[PrintManager](/uwp/api/windows.graphics.printing.printmanager)| Full printing support is available via `PrintManager`. See [Print from your app](/windows/apps/develop/devices-sensors/print-from-your-app). |
0 commit comments