Migrate WPF Screen-by-Screen with Uno Islands

Why Incremental Beats Big-Bang

The most common reason WPF migrations stall is scope. A team commits to a 6 to 12 month rewrite, the new platform takes longer than expected, leadership loses patience around month 7, the project is paused, and the team is left maintaining two codebases.

Incremental migration breaks the dependency between "framework decision" and "ship to users":

What Uno Islands Is

Uno Islands is a hosting mechanism that lets you place Uno Platform XAML pages inside a WPF (or WinForms) host control. The Uno Platform page renders inside the WPF window, communicates with the surrounding WPF app via standard .NET interop, and is built once for cross-platform reuse on macOS, Linux, iOS, Android, and the browser.

+---------------------------------------------+
|  Existing WPF Application                   |
|  +---------------------------------------+  |
|  |  WPF Window                           |  |
|  |  +---------------+  +---------------+ |  |
|  |  | Legacy WPF    |  | Uno Island:   | |  |
|  |  | UserControl   |  | Uno Page      | |  |
|  |  | (existing)    |  | (cross-plat)  | |  |
|  |  +---------------+  +---------------+ |  |
|  +---------------------------------------+  |
+---------------------------------------------+

The migrated Uno Platform page is independently runnable on every Uno target platform. The WPF host is just one of those targets: the one that lets the existing app keep shipping.

When Uno Islands Fits

Use Uno Islands when:

• The WPF app is in active production and you cannot pause shipping for a rewrite
• The team wants to validate Uno Platform on real screens before committing the full migration
• The migration will happen over multiple quarters or longer
• Some screens are too risky or complex to migrate first; you want to start with the simple ones
• Different teams own different screens and can migrate at their own pace

Skip Uno Islands when:

• The app is small enough to rewrite end-to-end in a few weeks
• The platform-specific code is the long pole, in which case the WPF host is helping you avoid the work you actually need to do
• The goal is to ship to a non-Windows platform tomorrow, not over a quarter

Embedding the First Uno Platform Page

Refer to the Uno Islands documentation for the exact NuGet packages, project file changes, and host control configuration in your current Uno Platform version.

Create a new Uno Platform class library in your existing WPF solution. The library holds cross-platform pages reused by the WPF host and (eventually) by macOS, Linux, WASM, and mobile heads.

dotnet new unoapp -n MyApp.UnoPages

Add the Uno Platform Islands host package to the WPF project. Place the host control where the migrated page should appear:

<Window x:Class="LegacyApp.MainWindow"
        xmlns:islands="clr-namespace:Uno.Islands;assembly=Uno.Islands">
  <DockPanel>
    <Menu DockPanel.Dock="Top"> ... </Menu>
    <islands:UnoIslandHost x:Name="SettingsHost" />
  </DockPanel>
</Window>

public MainWindow()
{
    InitializeComponent();
    SettingsHost.Source = typeof(MyApp.UnoPages.SettingsPage);
}

Element and namespace names may differ in the current Uno Platform release; verify against the Uno Islands documentation for your version.

Start with a low-risk screen that exercises common patterns: a settings page, an about screen, a simple form. Validate the page renders correctly inside the WPF host.

The Uno Platform page can be backed by ViewModels that the WPF host injects. Standard .NET DI works across the boundary:

The migrated Uno page ships inside the WPF MSI/MSIX like any other update. Users see one new page; they do not see "you migrated us." The risk is bounded to that one page.

Each subsequent screen follows the same pattern. The WPF Windows that wrap migrated pages become thinner over time. When most user-facing screens have moved, the final step is replacing the WPF shell with an Uno Platform shell, at which point the app is fully cross-platform.

What You Do Not Get from Islands

Uno Islands is a host pattern, not a magic bridge. Things that still need real work:

How This Differs from Other Incremental Patterns

Some commercial WPF-API-compatible cross-platform forks ship a similar mixing capability. The two approaches differ on:

Pick by what your team wants to invest skills in long-term: WPF-API compatibility through a commercial fork, or the Microsoft.UI.Xaml surface through Uno Platform.