Migrating WPF ResourceDictionary and MergedDictionaries to Uno Platform

A WPF ResourceDictionary migration is rarely a find-and-replace job. The same XAML concepts carry over to Uno Platform, but the URI syntax, the lookup order inside MergedDictionaries, and the way theme switching resolves at runtime all change. This guide walks through the four concrete shifts before porting a large theme graph.

The Four Things That Change

WPF and WinUI share a core model: a ResourceDictionary is a keyed bag of shareable objects, MergedDictionaries composes external files into the primary dictionary, and resource lookup walks up the visual tree to Application.Resources. What changes is everything at the edges:

pack:// URIs Are WPF-Only: Use ms-appx:///

In WPF, a merged dictionary typically used a pack URI to point at a compiled resource inside the local assembly or a referenced assembly:

<ResourceDictionary.MergedDictionaries>
  <ResourceDictionary Source="pack://application:,,,/MyApp.Themes;component/Colors.xaml"/>
</ResourceDictionary.MergedDictionaries>

WinUI (and therefore Uno Platform on all heads) does not use the pack scheme. The ResourceDictionary.Source property accepts a URI that references a XAML resource within the app package:

<Application.Resources>
  <ResourceDictionary>
    <ResourceDictionary.MergedDictionaries>
      <XamlControlsResources xmlns="using:Microsoft.UI.Xaml.Controls" />
      <ResourceDictionary Source="ms-appx:///Themes/Generic.xaml" />
    </ResourceDictionary.MergedDictionaries>
  </ResourceDictionary>
</Application.Resources>

MergedDictionaries Lookup Order

This is where WPF muscle memory betrays you.

WPF: The resource that's returned comes from the last dictionary found sequentially in the MergedDictionaries collection. The primary (outer) dictionary still wins over any merged entry with the same key.

WinUI: If multiple merged dictionaries exist, they are checked in the inverse of the order in which they are declared in the MergedDictionaries property. If both Dictionary2.xaml and Dictionary1.xaml declare the same key, the key from Dictionary2.xaml is used first because it is last in the collection.

In practical terms, both frameworks converge on the same outcome for collisions (the later-declared merged file wins), but they describe the algorithm differently and the WinUI rule is explicitly "reverse of declared order." If you relied on WPF's forward-iteration mental model, revisit any code that stitches together a base theme and a per-feature override.

DynamicResource vs. ThemeResource Semantics

WPF's {DynamicResource} defers lookup until the value is actually needed and will re-resolve if the underlying resource is updated. WinUI and Uno Platform do not have a DynamicResource markup extension. The closest equivalent is {ThemeResource}:

<TextBlock Text="hello world"
           Foreground="{ThemeResource FocusVisualWhiteStrokeThemeBrush}"
           VerticalAlignment="Center"/>

ThemeDictionaries: The Theme Graph, Properly Expressed

In WPF, a theme graph was often assembled by merging different brush files at app startup. In WinUI, the idiomatic pattern is ResourceDictionary.ThemeDictionaries, where each inner ResourceDictionary is keyed with a theme name: Light, Dark, HighContrast, or Default as the fallback.

<ResourceDictionary>
  <ResourceDictionary.ThemeDictionaries>
    <ResourceDictionary x:Key="Light">
      <!-- light-theme brushes -->
    </ResourceDictionary>
    <ResourceDictionary x:Key="Dark">
      <!-- dark-theme brushes -->
    </ResourceDictionary>
    <ResourceDictionary x:Key="HighContrast">
      <!-- high-contrast brushes -->
    </ResourceDictionary>
  </ResourceDictionary.ThemeDictionaries>
</ResourceDictionary>

Reference the keys with {ThemeResource} from your control templates and styles. Do not use {ThemeResource} inside the theme dictionary itself; use {StaticResource} there, with an exception for theme-agnostic system values like SystemAccentColor.

Lightweight Styling in Uno Platform

WPF teams accustomed to overriding a brush by redeclaring it in App.xaml will find the same mechanism in Uno Platform, with a Uno-specific idiom called lightweight styling. Keys defined later in the lookup chain (Application.Resources or page-level resources) shadow keys from merged control libraries. Uno ships a matched set of theme-resource keys across its Material, Fluent, and Toolkit packages so the overrides compose cleanly.

Migration Checklist

FAQ

Will my pack:// URIs compile in Uno Platform?

No. The pack scheme is a WPF URI scheme. Uno Platform / WinUI ResourceDictionary.Source expects ms-appx:/// or a relative path. Expect to rewrite these.

How do I theme-switch at runtime across platforms?

Put the varying brushes under ResourceDictionary.ThemeDictionaries keyed by Light, Dark, and HighContrast, and reference the keys with {ThemeResource}. The platform re-evaluates the lookup when the active theme changes.

What happens to DynamicResource in a templated control?

{DynamicResource} is WPF-only. The Microsoft WPF-to-WinUI 3 pattern guide maps it to {ThemeResource}. Theme-driven re-evaluation works; arbitrary runtime dictionary swaps require redesign.

Do WebAssembly heads load resources differently?

The ms-appx:/// URI scheme is supported by Uno Platform for app-packaged content across all heads. Test your specific theme graph on each target, as head-by-head loading semantics are not explicitly documented in a single reference page.