WPF to WinUI XAML Equivalents Reference

This reference provides a comprehensive mapping of WPF namespaces, controls, XAML syntax, events, and patterns to their WinUI 3 / Uno Platform equivalents. Use it as a lookup when migrating WPF applications.

[!TIP] For architectural migration guidance (MVVM, navigation, data access), see Migrating WPF Apps to Web.

Namespace Mapping

XAML Declaration Syntax

Control Mappings

Controls That Transfer Directly

These controls exist in both WPF and WinUI and typically require only a namespace change:

Button, TextBox, TextBlock, CheckBox, RadioButton, ComboBox, ListBox, ListView, Grid, StackPanel, Border, ScrollViewer, Canvas, Image, Slider, ProgressBar, ToolTip/ToolTipService, Expander, TreeView.

WinUI-Only Additions You May Want to Adopt

The following controls do not have direct equivalents in WPF but are often valuable to introduce when modernizing your UI with WinUI / Uno Platform:

NavigationView, NumberBox, InfoBar, ProgressRing, ToggleSwitch, HyperlinkButton, GridView.

Controls Requiring Replacement

Package guidance for Community Toolkit controls in this table: in WinUI 3 (Windows App SDK), use CommunityToolkit.WinUI.UI.Controls; for Uno Platform non-Windows targets, install the matching Uno package for the control you use, such as Uno.CommunityToolkit.WinUI.UI.Controls for controls like DockPanel and GridSplitter, or Uno.CommunityToolkit.WinUI.UI.Controls.DataGrid for DataGrid. See Uno Community Toolkit packages for the authoritative package list and version guidance.

Useful NuGet Packages

Property and Value Mappings

Event Mappings

Pointer Events (Replacing Mouse Events)

[!NOTE] WinUI does not provide WPF-style PreviewMouse* tunneling events for pointer/mouse input. If you need to listen for a bubbling event even after a child marks it handled, use AddHandler with handledEventsToo: true. This does not reproduce WPF-style preview ordering (parent before child).

Keyboard Events

[!NOTE] Standard WinUI 3 does not expose WPF-style preview keyboard events. On Uno, PreviewKeyDown and PreviewKeyUp are available only on some targets (for example, WASM/SKIA), so treat them as platform-specific rather than general WinUI equivalents. When you need a cross-target or WinUI 3-compatible alternative, use KeyDown and KeyUp, and validate event ordering on your target platforms when the distinction matters.

Mouse Capture

XAML Syntax Translations

Resource and Binding Markup

Binding Technology Comparison

[!IMPORTANT] {x:Bind} defaults to OneTime, not OneWay. Always specify Mode=OneWay for properties that should update.

Patterns Without Direct WinUI Equivalents

Style.Triggers and DataTriggers

WinUI does not support Style.Triggers, DataTrigger, EventTrigger, or MultiDataTrigger. Replace with VisualStateManager:

WPF:

<Style TargetType="Border">
  <Style.Triggers>
    <DataTrigger Binding="{Binding IsActive}" Value="True">
      <Setter Property="Background" Value="Green" />
    </DataTrigger>
  </Style.Triggers>
</Style>

WinUI equivalent:

<Border x:Name="MyBorder">
  <VisualStateManager.VisualStateGroups>
    <VisualStateGroup>
      <VisualState x:Name="Active">
        <VisualState.StateTriggers>
          <StateTrigger IsActive="{x:Bind ViewModel.IsActive, Mode=OneWay}" />
        </VisualState.StateTriggers>
        <VisualState.Setters>
          <Setter Target="MyBorder.Background" Value="Green" />
        </VisualState.Setters>
      </VisualState>
    </VisualStateGroup>
  </VisualStateManager.VisualStateGroups>
</Border>

MultiBinding

WinUI does not support MultiBinding. Use x:Bind with function binding:

<TextBlock Text="{x:Bind local:Converters.FormatFullName(ViewModel.FirstName, ViewModel.LastName), Mode=OneWay}" />

public static class Converters
{
    public static string FormatFullName(string first, string last)
        => $"{first} {last}";
}

RoutedUICommand

Replace RoutedUICommand and CommandBinding with ICommand implementations. Using CommunityToolkit.Mvvm:

[RelayCommand(CanExecute = nameof(CanSave))]
private void Save() { /* save logic */ }

private bool CanSave() => IsDirty;

WinUI 3 also offers StandardUICommand and XamlUICommand for predefined operations (Cut, Copy, Paste) with built-in icons and keyboard accelerators.

Adorners

WinUI does not have an Adorner layer. Use these alternatives:

Resource Dictionaries

<Application.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
      <!-- Required: default Fluent styles -->
      <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
      <!-- Your custom resources -->
      <ResourceDictionary Source="ms-appx:///Styles/Colors.xaml" />
    </ResourceDictionary.MergedDictionaries>
  </ResourceDictionary>
</Application.Resources>

Key differences from WPF:

• XamlControlsResources must be the first merged dictionary to provide default styles. Omitting it leaves controls with no visual appearance.
• Resource paths use ms-appx:/// protocol instead of relative paths.
• Window.Resources does not exist in WinUI. Place window-level resources on root layout containers or Page.

Implicit Styles and BasedOn

Always use BasedOn when overriding default control styles. Without it, your style replaces the entire default style rather than extending it:

<Style TargetType="Button" BasedOn="{StaticResource DefaultButtonStyle}">
  <Setter Property="Background" Value="Red" />
</Style>

Common API Replacements

For awaitable dispatch, wrap DispatcherQueue.TryEnqueue(...) with a TaskCompletionSource:

var tcs = new TaskCompletionSource<bool>(TaskCreationOptions.RunContinuationsAsynchronously);

if (!App.MainWindow.DispatcherQueue.TryEnqueue(() =>
{
    try
    {
        /* work */
        tcs.TrySetResult(true);
    }
    catch (Exception ex)
    {
        tcs.TrySetException(ex);
    }
}))
{
    tcs.TrySetException(new InvalidOperationException("Failed to enqueue work on the DispatcherQueue."));
}

await tcs.Task;

Find-and-Replace Quick Reference

XAML Attribute Replacements

Code-Behind Replacements

AI Prompt Template

Use this prompt with an AI coding assistant to automate the mechanical translation of WPF XAML files:

You are a WPF-to-WinUI XAML migration assistant. Translate the following WPF XAML
file to WinUI 3 XAML compatible with Uno Platform.

Apply ALL of the following rules:

NAMESPACE RULES:
- Keep the default xmlns as-is
- Replace clr-namespace references with "using:" syntax
- Replace System.Windows.* with Microsoft.UI.Xaml.*

RESOURCE RULES:
- Replace {DynamicResource X} with {ThemeResource X}
- Replace {x:Static X} with {x:Bind X}
- Keep {StaticResource X} as-is

CONTROL REPLACEMENTS:
- Menu/MenuItem -> MenuBar/MenuBarItem/MenuFlyoutItem

- ContextMenu -> ContextFlyout with MenuFlyout
- ToolBar -> CommandBar with AppBarButton
- StatusBar -> Grid at bottom of layout
- TabControl -> TabView or NavigationView (Top mode)
- DataGrid -> CommunityToolkit DataGrid
- Label -> TextBlock
- MediaElement -> MediaPlayerElement

PROPERTY REPLACEMENTS:
- Visibility="Hidden" -> WinUI has no direct `Hidden` state; when layout must be preserved, use `Opacity="0"` with `Visibility="Visible"` and also set `IsHitTestVisible="False"`; for focusable controls also set `IsTabStop="False"` and `AllowFocusOnInteraction="False"` so the element is not invisible-but-interactive; use `Visibility="Collapsed"` only when removing the element from layout is acceptable
- TextWrapping="WrapWithOverflow" -> TextWrapping="Wrap"
- Focusable -> IsTabStop

EVENT REPLACEMENTS:
- Mouse* events -> Pointer* equivalents
- Remove Preview* tunneling events

TRIGGER REPLACEMENTS:
- Remove Style.Triggers, DataTrigger, EventTrigger
- Create VisualStateManager.VisualStateGroups with StateTrigger

BINDING UPGRADES:
- Convert {Binding Path=X} to {x:Bind ViewModel.X, Mode=OneWay}
- Replace MultiBinding with x:Bind function binding

OUTPUT: Complete translated XAML with a list of manual follow-up items.

WPF XAML to translate:
```xml
<!-- Paste WPF XAML here -->
<PASTE WPF XAML HERE>
```

FAQ

Do I need to rewrite all my XAML from scratch?

No. The majority of WPF XAML transfers with namespace changes and minor property fixes. The heavy lifting is in triggers, MultiBinding, and controls that don't exist in WinUI.

Can I keep using {Binding} or must I switch to {x:Bind}?

{Binding} still works and is not mandatory to replace. However, {x:Bind} provides compile-time validation, better performance, and function binding (which replaces MultiBinding). For new or migrated code, {x:Bind} is recommended.

What replaces Visibility.Hidden?

WinUI only has Visible and Collapsed. For invisible-but-layout-occupying behavior, set Opacity="0" while keeping Visibility="Visible", and also set IsHitTestVisible="False". If the control can receive focus, also set IsTabStop="False" and AllowFocusOnInteraction="False" so it does not remain invisible but interactive.

How do I handle preview/tunneling events?

WinUI 3 does not generally provide WPF-style preview/tunneling events. In Uno Platform, some preview keyboard events such as PreviewKeyDown and PreviewKeyUp are available on specific targets only, so they should not be treated as a general WinUI 3 migration equivalent. For cross-target and WinUI 3-compatible code, use KeyDown/KeyUp instead. WPF-style preview mouse/pointer events such as PreviewMouseDown do not generally have direct equivalents; use the corresponding bubbling event (for example, PointerPressed) and, if you need to observe events that were already marked handled, register with AddHandler(..., handledEventsToo: true).

How do I migrate the Dispatcher pattern?

Replace Application.Current.Dispatcher.Invoke(...) with App.MainWindow.DispatcherQueue.TryEnqueue(...). The DispatcherQueue API is asynchronous by default and has no synchronous Invoke method.

Does Uno Platform add controls beyond WinUI?

Yes. The Uno Toolkit includes NavigationBar, TabBar, DrawerControl, SafeArea, and more. The Community Toolkit controls (DataGrid, WrapPanel, DockPanel) also work across all Uno Platform targets.