Microsoft.Maui.Platforms.Windows.WPF.Essentials 0.1.0-preview.12.26368.2

.NET MAUI Backend for WPF

Custom .NET MAUI backend targeting WPF (Windows Presentation Foundation) — an alternative to the official WinUI backend.

This backend uses the platform-agnostic MAUI NuGet packages (net10.0 fallback assemblies) and provides custom handler implementations that bridge MAUI's layout/rendering system to WPF controls. All core MAUI controls, pages, layouts, gestures, and navigation patterns are implemented.

Inspiration: This project follows the patterns established by mauiplatforms (macOS/tvOS backends) and Maui.Gtk.

Screenshots

Home	Controls	Layouts

Shapes	Graphics	CollectionView

FormattedText	Pickers	Transforms

FontAwesome	ControlTemplate

Quick Start — Setting Up a WPF MAUI App

Option 1: Use the template (recommended)

# Install the template
dotnet new install Microsoft.Maui.Platforms.Windows.WPF.Templates --prerelease

# Create a new WPF MAUI app
dotnet new maui-wpf -n MyApp.WPF
cd MyApp.WPF
dotnet run

Option 2: Add to an existing project manually

1. Create the project

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <TargetFramework>net10.0-windows</TargetFramework>
    <OutputType>WinExe</OutputType>
    <UseMaui>true</UseMaui>
    <UseWPF>true</UseWPF>
    <EnableDefaultXamlItems>false</EnableDefaultXamlItems>
  </PropertyGroup>

  <ItemGroup>
    <PackageReference Include="Microsoft.Maui.Controls" Version="10.0.31" />
    <PackageReference Include="Microsoft.Maui.Platforms.Windows.WPF" Version="*" />
    <PackageReference Include="Microsoft.Maui.Platforms.Windows.WPF.Essentials" Version="*" />
  </ItemGroup>
</Project>

2. App.xaml

<Microsoft.Maui.Platforms.Windows.WPF:MauiWPFApplication
    x:Class="MyApp.App"
    xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
    xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
    xmlns:Microsoft.Maui.Platforms.Windows.WPF="clr-namespace:Microsoft.Maui.Platform.WPF;assembly=Microsoft.Maui.Platforms.Windows.WPF">
</Microsoft.Maui.Platforms.Windows.WPF:MauiWPFApplication>

3. App.xaml.cs

using Microsoft.Maui.Platform.WPF;

namespace MyApp;

public partial class App : MauiWPFApplication
{
    protected override MauiApp CreateMauiApp() => MauiProgram.CreateMauiApp();
}

4. MauiProgram.cs

using Microsoft.Maui.Platform.WPF.Hosting;
using Microsoft.Maui.Essentials.WPF;

public static class MauiProgram
{
    public static MauiApp CreateMauiApp()
    {
        var builder = MauiApp.CreateBuilder();
        builder
            .UseMauiAppWPF<App>()
            .UseWPFEssentials()
            .ConfigureFonts(fonts =>
            {
                fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular");
            });

        return builder.Build();
    }
}

5. App class

public class App : Application
{
    protected override Window CreateWindow(IActivationState? activationState)
        => new Window(new MainPage());
}

Samples

See the samples/ directory for working examples:

• ControlGallery — Full control gallery exercising all implemented handlers (used by UI tests)
• Maui.Controls.Sample.Blazor — Blazor Hybrid WebView on WPF
• Maui.Sample — Multi-platform sample with WPF platform folder

Implementation Status

Controls

Collection Controls

Pages & Navigation

Layouts

All layouts work via the cross-platform MAUI layout engine + LayoutPanel:

VerticalStackLayout · HorizontalStackLayout · Grid · FlexLayout · AbsoluteLayout · StackLayout · ScrollView · ContentView · Border · Frame

Gestures

Shapes

All MAUI shapes render via WPF System.Windows.Shapes:

Rectangle · RoundRectangle · Ellipse · Line · Path · Polygon · Polyline — with Fill, Stroke, StrokeDashPattern support.

Infrastructure

Essentials

Project Structure

src/
  Microsoft.Maui.Platforms.Windows.WPF/              # WPF backend library (net10.0-windows)
  Microsoft.Maui.Platforms.Windows.WPF.Essentials/   # WPF Essentials library
samples/
  ControlGallery/                  # WPF Control Gallery (used by UI tests)
  Maui.Controls.Sample.Blazor/    # Blazor Hybrid sample
  Maui.Sample/                    # Multi-platform sample
tests/
  UITests/                         # 213 UI tests + WinUI comparison framework

Prerequisites

.NET 10 SDK

Install the latest .NET 10 SDK from dotnet.microsoft.com.

Workloads

dotnet workload install maui-windows
dotnet workload list   # verify

Building & Running

# Build libraries only (for NuGet packaging)
dotnet build build.slnf -property:Configuration=Release

# Build and run the Control Gallery sample
dotnet build samples\ControlGallery\ControlGallery.csproj
dotnet run --project samples\ControlGallery\ControlGallery.csproj

# Run UI tests (213 tests)
dotnet build tests\UITests\UITests.csproj
dotnet test tests\UITests\UITests.csproj --no-build

Note: Build projects individually or use build.slnf. The full solution includes samples that may have additional dependencies.

Testing

The project includes 213 UI tests covering all implemented controls, plus a WinUI comparison framework that captures side-by-side screenshots of the WPF and WinUI ControlGallery apps for visual parity validation.

# Run all UI tests
dotnet test tests\UITests\UITests.csproj --no-build

# Run comparison tests only (requires WinUI ControlGallery running)
dotnet test tests\UITests\UITests.csproj --no-build --filter "DisplayName~Compare"

Comparison screenshots are saved to tests/UITests/Comparisons/.

Key Technical Notes

• MAUI NuGet packages resolve to the net10.0 (platform-agnostic) assembly. ToPlatform() returns object — WPFViewHandler<TVirtualView, TPlatformView> provides the typed bridge.
• The platform-agnostic ViewHandler has no-op PlatformArrange and returns Size.Zero. WPFViewHandler overrides these to bridge MAUI layout to WPF Measure/Arrange.
• WPF System.Windows.Controls and MAUI Microsoft.Maui.Controls share many type names — every handler file uses using aliases to disambiguate (e.g., WButton = System.Windows.Controls.Button).
• The MauiWPFApplication base class in App.xaml bootstraps the MAUI runtime within a WPF Application.
• Dialogs use DispatchProxy + reflection to intercept AlertManager requests (the API is internal in MAUI). See dotnet/maui#34104.

Known Limitations

• Essentials stubs: FilePicker, Share, and sensor APIs are stubs — desktop doesn't have equivalent hardware.
• Span.CharacterSpacing: WPF has no direct CharacterSpacing API on TextBlock/Run — mapper is registered but no-op.
• SwipeView: Approximated via context menu rather than swipe gesture.
• BlazorWebView: DeveloperTools property is stubbed.

See BACKEND_IMPLEMENTATION_CHECKLIST.md for the complete implementation status with detailed notes.

License

MIT