Microsoft.Maui.Platforms.Windows.WPF
0.1.0-preview.14.26555.2
Prefix Reserved
dotnet add package Microsoft.Maui.Platforms.Windows.WPF --version 0.1.0-preview.14.26555.2
NuGet\Install-Package Microsoft.Maui.Platforms.Windows.WPF -Version 0.1.0-preview.14.26555.2
<PackageReference Include="Microsoft.Maui.Platforms.Windows.WPF" Version="0.1.0-preview.14.26555.2" />
<PackageVersion Include="Microsoft.Maui.Platforms.Windows.WPF" Version="0.1.0-preview.14.26555.2" />
<PackageReference Include="Microsoft.Maui.Platforms.Windows.WPF" />
paket add Microsoft.Maui.Platforms.Windows.WPF --version 0.1.0-preview.14.26555.2
#r "nuget: Microsoft.Maui.Platforms.Windows.WPF, 0.1.0-preview.14.26555.2"
#:package Microsoft.Maui.Platforms.Windows.WPF@0.1.0-preview.14.26555.2
#addin nuget:?package=Microsoft.Maui.Platforms.Windows.WPF&version=0.1.0-preview.14.26555.2&prerelease
#tool nuget:?package=Microsoft.Maui.Platforms.Windows.WPF&version=0.1.0-preview.14.26555.2&prerelease
.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.
Window and page titles
The native title bar belongs to Window.Title. Page titles are used by navigation
and Shell headers; creating, renaming, or returning to a page does not change any
window's title bar. Set or bind Window.Title explicitly to change it. An empty
window title stays empty rather than falling back to a page title.
Shell inspection with DevFlow
Shell creates only the selected page through its content controller. Template pages remain cached and attached to the MAUI tree, so DevFlow can inspect their labels and buttons without creating inactive pages.
To check this in the sample, open Shell Navigation, select Launch Shell App, then use the sample agent's port:
maui devflow --agent-port <port> ui tree --depth 20
maui devflow --agent-port <port> ui query --automationId ShellHomeTitle
maui devflow --agent-port <port> ui query --type Button
maui devflow --agent-port <port> ui tap --automationId ShellSettingsButton
The tree should include ShellHomePage beneath ShellContent, the title query
should find a MAUI Label, and tapping the button should navigate to Settings.
Entry focus and native scrolling
Entry.Focus() completes MAUI's focus request with the native WPF result, including
password entries. Disabled entries reject focus, including after switching password
mode. Native focus changes update Entry.IsFocused and its Focused/Unfocused
events. DevFlow delta scrolling resolves the target's own
ScrollViewer, then an internal descendant (such as CollectionView's list template),
then an ancestor, on the UI dispatcher. CollectionView's vertical list uses
device-independent pixel scroll offsets, not item counts, with CanContentScroll
and VirtualizingStackPanel virtualization retained.
Run the focused native regressions on Windows:
dotnet test platforms\Windows.WPF\tests\HandlerTests\HandlerTests.csproj -p:UseMaui=false --filter FullyQualifiedName~WpfUiActionTests
Native focus tests require exclusive foreground access.
Dynamic Shell items
Changes to Shell.Items, ShellItem.Items, and ShellSection.Items on the UI
thread refresh the native flyout, tabs, and selected page. Collection notifications
are coalesced on the dispatcher after Shell settles its current selection. Clearing
the hierarchy clears the displayed page; replacing flyout items with a TabBar
does not leave flyout entries behind. Inactive page templates remain lazy.
The tab strip contains only the current item's sections and preserves its selected
section when inactive items change.
Deferred collection refreshes use the Items property mapper, including
customizations registered with AppendToMapping(nameof(Shell.Items), ...).
Run the collection and lifecycle regressions on Windows:
dotnet test platforms\Windows.WPF\tests\HandlerTests\HandlerTests.csproj -p:UseMaui=false --filter FullyQualifiedName~ShellItemsHandlerTests
The runtime regression renders add, remove, replace, and reset transitions in an
offscreen, nonactivating WPF window. Set SHELL_ITEMS_EVIDENCE_DIRECTORY in the
test process environment to save PNGs of those transitions.
Shell section selection
Selecting a native tab navigates through Shell's cancellable section-selection
pipeline, with or without Shell.ItemTemplate. Cancelled or deferred navigation
keeps the native selection on the current section until Shell accepts the change.
Rebuilding the strip does not initiate navigation or create inactive pages.
The strip uses controller-visible sections, excluding hidden sections and sections
without visible content. Visibility changes refresh it automatically. Plain section
changes retain the native tab elements and synchronize selection without rebuilding,
preserving keyboard focus.
ShellSection.IsEnabled is projected onto native tabs and their UI Automation
enabled state, both initially and when it changes. Enabled-state changes update
only the matching current tab in place: they do not rebuild the strip, replay
property mappers, replace custom headers, or navigate away from a selected section.
Disabled sections remain visible; native UI Automation selection rejects them.
Section observers follow collection changes and handler rebind/disconnect.
The ShellTabNavigationTests handler regressions drive native UI Automation
selection in an offscreen WPF window and assert the route,
Navigated events, and rendered page. Set SHELL_TAB_RESULTS to a directory to
capture the templated and non-templated repro states as PNG and JSON.
Only the keyboard-focus cases activate their window; all other cases are
nonactivating. On a shared desktop, run the focus cases only with exclusive
foreground access. They assert actual keyboard focus, not just logical focus.
For section switching within one Shell item, select Launch Section Switching
Repro, or start the sample with --shell-section-repro. This uses two lazy
pages in one TabBar, without calling a handler refresh workaround. The
GoToAsync and Set CurrentItem buttons must both replace Page One with
Page Two (and back). Refresh state shows the route, current page, page
creation count, and Navigated count. Only one page should be created initially;
after visiting both pages, the creation count must remain two on repeat visits.
The focused Windows handler regression suite exercises real MAUI selection and WPF content hosting, including selection cleanup:
dotnet test platforms\Windows.WPF\tests\HandlerTests --filter FullyQualifiedName~ShellSectionSwitchingTests
Layout measurement
The WPF layout handler dispatches measurement and arrangement through
ICrossPlatformLayout, including during native panel creation and virtual-view
replacement. This preserves specialized implementations such as FlexLayout's
measure-mode handling. Fixed-width entries in a wrapping flex layout do not need
an explicit height or a preliminary manual measure.
Run the native layout regressions on Windows (the existing shared STA application host is reused; these tests do not show or activate windows):
dotnet test platforms\Windows.WPF\tests\HandlerTests\HandlerTests.csproj -p:UseMaui=false --filter FullyQualifiedName~LayoutHandlerTests
These tests cover first measurement, wrapping as constraints change, native child frames, delegate dispatch during creation and replacement, and ordinary Grid/Stack layout. The native panel preserves measurements already performed by MAUI, instead of remeasuring each child against the whole parent's size (which can inflate flex lines beyond their allocated frames). Children whose native measurement is still invalid, including explicitly sized views MAUI did not measure, are measured by the panel. Nested flex panels retain fallback measurement on constraint changes, because the shared flex engine bypasses their native measure. The existing minimum-height floor is retained.
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
Follow the getting-started guide
for package references and the code-only entry point. Use a MauiWPFApplication
host separate from your MAUI Application, with UseMauiAppWPF<App>() and
UseWPFEssentials().
The packed template selects backend and Essentials packages from its own release
and explicitly references the backend's MAUI Controls version. Use full release
versions when configuring references manually: 0.1.0-preview selects the oldest
matching preview, not the latest.
For template development, run eng\smoke-tests\wpf-template-smoke-test.ps1 on Windows.
It packs, generates, restores, builds, and launches the template using an isolated
template hive. See validation details.
Registered fonts
Include fonts as MauiFont items and register them using ConfigureFonts:
builder.ConfigureFonts(fonts => fonts.AddFont("OpenSans-Regular.ttf", "OpenSansRegular"));
The NuGet package imports font processing through its existing
Microsoft.Maui.Platforms.Windows.WPF.targets entry point; package consumers do
not need an additional import. A ProjectReference to the backend does not import
its packaged build targets into the consuming app. Source consumers must explicitly
import the font-only target, as the repository sample does:
<Import Project="..\..\src\Windows.WPF\build\Fonts\Microsoft.Maui.Platforms.Windows.WPF.Fonts.targets"
Condition="'$(_MicrosoftMauiPlatformsWindowsWPFFontsTargetsImported)' != 'true'" />
Adjust this path relative to your app project. Keep UseMaui enabled. This import
handles only MauiFont; it does not enable or fix source-consumer processing of
images, icons, splash screens, or raw assets.
The import guard prevents loading the font target twice when another import
already included the umbrella; it does not depend on test-scenario opt-in.
WPF copies MauiFont files into Resources\Fonts in both build and publish output.
This output layout uses leaf filenames, so font filenames must be unique even
when their source directories differ.
An explicitly included MauiFont must exist: build/publish now fails on a missing
file instead of silently skipping it. Use a conditional item include for optional fonts.
Aliases resolve relative to the application directory, not the process working
directory, using the family name declared inside the font file. Embedded fonts
registered with an assembly are extracted to a content-addressed temporary directory;
no system font installation is required.
Text controls and formatted label spans resolve aliases through the WPF font manager.
Native WPF composite families, such as Global User Interface, remain supported
for text. Font images require a physical typeface containing the requested glyphs;
composite families produce a warning and no image rather than an unverified fallback.
Clearing a control's MAUI font family restores its native style or inherited default.
Entry also applies its font when creating a native password control. GraphicsView
text drawing and measurement share the same registered-family and style resolution.
The default public IFontManager and native WPFFontManager share one singleton.
Replacing the portable IFontManager preserves its DefaultFontSize contract;
native family resolution still uses the app's registered fonts. A supplied
WPFFontManager override takes precedence for native resolution as well.
FontImageSource uses the same resolution for Image, ImageButton, Button, Shell
flyout icons, and NavigationPage toolbar icons. A missing or invalid font logs a warning and text uses the default UI
font. An unresolved icon font or a character absent from that font logs a warning
and produces no image rather than a fallback box.
Glyph bitmaps retain the font's advance width and line box, including its internal
padding, rather than cropping to the visible ink. This keeps icon scaling and
alignment consistent with the font's metrics.
Glyph sizes must be finite, positive, and no greater than 4096 device-independent
units. At 96 DPI, the rendered bitmap, including its one-pixel padding on each side,
is limited to 4096 pixels per side and 4,194,304 pixels total (16 MiB of pixel data).
Out-of-range sizes, unsupported bounds, and expected native rendering failures log
a warning and produce no image; invalid sizes are not replaced with a default size.
Register fonts before first use. Missing-font results are cached as failures, not as
successful fallback fonts; transient extraction I/O failures can be retried.
Packaged raw assets
Declare raw files as MauiAsset items with their package-relative names:
<MauiAsset Include="Resources\Raw\**\*" LogicalName="%(RecursiveDir)%(Filename)%(Extension)" />
For example, Resources\Raw\Data\sample.txt is copied to Data\sample.txt
under the app directory in both build and publish output. Open it with
IFileSystem.OpenAppPackageFileAsync("Data/sample.txt"); use
AppPackageFileExistsAsync with the same name. Resolve IFileSystem from the
services registered by UseWPFEssentials().
An explicit LogicalName takes precedence over Link. Without either metadata,
the path defaults to %(RecursiveDir)%(Filename)%(Extension) (a single explicitly
included file uses its filename). Nested folders are preserved, so files with
the same basename in different logical folders remain distinct. Do not prefix
the runtime name with Resources\Raw.
Run eng\smoke-tests\wpf-assets-smoke-test.ps1 -RuntimeIdentifier win-x64 on
Windows (choose the RID matching your selected dotnet host) to build and run the
existing Windows.WPF.Sample with -p:WpfTestScenarios=true, then publish it
without rebuilding and run it again. The opt-in --test-scenario packaged-assets
entrypoint uses the actual DI-registered WPF file system without opening a window
or starting DevFlow. Normal startup (no scenario argument) still opens the gallery.
Scenario code and fixtures live under the sample's TestScenarios directory;
additional runtime checks should use this shared host rather than new test apps.
Launch scenarios with dotnet Windows.WPF.Sample.dll --test-scenario <name> to
see console diagnostics; the normal Windows executable is a GUI application.
The same asset definitions and expected contents are reused by HandlerTests,
while the smoke verifies the real sample build/publish output through the shipping
backend MSBuild target. -TargetsFile can select a historical target file for
regression reproduction; it never changes the shipped target.
The same explicit RID is used for build and no-build publish so Razor's generated
manifests are read from the directory where the build wrote them.
Samples
Blazor Hybrid hosts need a Windows SDK-versioned target framework, such as
net10.0-windows10.0.17763.0, so WebView2 can load the Microsoft.Windows.SDK.NET
projection assembly. Copy wwwroot content to both build and publish output; without
wwwroot/index.html, the WebView can start but cannot load the Blazor host page.
The Windows.WPF.Sample project includes both settings.
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
| Control | WPF Native Control | Status |
|---|---|---|
| Label | TextBlock | ✅ Full (Text, FormattedText, Font, Color, Alignment, Decorations, LineHeight, MaxLines, Padding, CharacterSpacing) |
| Button | Button | ✅ Full (Text, Font, TextColor, Background, CornerRadius, Padding, Clicked/Pressed/Released) |
| Entry | TextBox / PasswordBox | ✅ Full (Text, Font, Color, Placeholder, MaxLength, IsReadOnly, IsPassword, Keyboard, CursorPosition, SelectionLength) |
| Editor | TextBox (multiline) | ✅ Full (Text, Font, Color, Placeholder, MaxLength, IsReadOnly) |
| Image | Image | ✅ Full (FileImageSource, UriImageSource, StreamImageSource, FontImageSource, Aspect) |
| ImageButton | Button + Image | ✅ (Source, Aspect, Padding, BorderWidth, BorderColor) |
| CheckBox | CheckBox | ✅ (IsChecked, Foreground via SolidPaint) |
| Switch | Custom ControlTemplate | ✅ (IsToggled, OnColor, animated thumb toggle) |
| Slider | Slider | ✅ (Value, Min, Max, MinimumTrackColor, MaximumTrackColor) |
| ProgressBar | ProgressBar | ✅ (Progress 0-1 mapped to 0-100) |
| ActivityIndicator | Custom rotating arc | ✅ (IsRunning, Color) |
| Stepper | Custom ▲/▼ panel | ✅ (Value, Min, Max, Interval) |
| RadioButton | RadioButton | ✅ (IsChecked, Content, TextColor, GroupName) |
| Picker | ComboBox | ✅ (Items, SelectedIndex, Title, TextColor, TitleColor) |
| DatePicker | DatePicker | ✅ (Date, MinimumDate, MaximumDate, Format) |
| TimePicker | ComboBox (time items) | ✅ (Time, Format) |
| SearchBar | TextBox + Button | ✅ (Text, Placeholder, TextColor, MaxLength) |
| Border | Border | ✅ (Stroke, StrokeThickness, CornerRadius, Background, Padding, StrokeDashPattern) |
| BoxView | ShapeViewHandler | ✅ (Color, CornerRadius) |
| ScrollView | ScrollViewer | ✅ (Content, Orientation) |
| ContentView | ContentControl | ✅ (Content) |
| WebView | WebView2 | ✅ (URL, HTML, JavaScript, Navigation, UserAgent) |
| GraphicsView | Custom WpfCanvas | ✅ (ICanvas drawing via DrawingContext) |
| BlazorWebView | WebView2 | ✅ (via AspNetCore.Components.WebView.Wpf) |
Collection Controls
| Control | Status | Notes |
|---|---|---|
| CollectionView | ✅ | WPF ListBox with DataTemplateSelector, SelectedItem, SelectionMode, EmptyView, and logical parenting of realized template views; observable flat and grouped sources update live |
| ListView | ✅ | WPF ListBox with MAUI template bridge |
| CarouselView | ✅ | Horizontal ListBox with arrow navigation buttons |
| IndicatorView | ✅ | Dot indicators as Ellipses |
| TableView | ✅ | Grouped sections with TextCell, SwitchCell, EntryCell |
| SwipeView | ✅ | Context menu approximation |
| RefreshView | ✅ | Progress bar indicator |
CollectionView's native list-item accessible names prefer the template root's
SemanticProperties.Description. Without a description, visible template labels
and buttons supply the name in visual-tree order; a described subtree replaces
its children's text. Native container AutomationProperties.Name and LabeledBy
remain authoritative. Names are read from the current template, including after
binding updates and container reuse. Empty templates and unrealized items do not
expose the data model's ToString(); items without a template use their displayed
fallback text. Group headers follow the same rules as items. Changes to template
text, semantic descriptions, visibility, or descendants invalidate the native
automation peers so UIA clients receive name-change notifications.
Referenced native LabeledBy text/content labels are observed as well, including
changes to their own accessible names and replacement of their content.
If template creation fails, the existing displayed fallback text remains the
accessible name; this does not suppress information that is already visible.
Pages & Navigation
| Page | Status | Notes |
|---|---|---|
| ContentPage | ✅ | Full support via PageHandler |
| NavigationPage | ✅ | Push/pop stack, back button, title bar, toolbar items, animated transitions |
| TabbedPage | ✅ | WPF TabControl with auto-generated TabItems |
| FlyoutPage | ✅ | Grid with flyout panel, GridSplitter, IsPresented two-way sync |
| Shell | ✅ | Flyout panel, tab control, URI-based routing, shell item navigation |
| Modal pages | ✅ | Animated overlay push/pop via ModalNavigationManager |
Layouts
All layouts work via the cross-platform MAUI layout engine + LayoutPanel:
VerticalStackLayout · HorizontalStackLayout · Grid · FlexLayout · AbsoluteLayout · StackLayout · ScrollView · ContentView · Border · Frame
Gestures
| Gesture | Status | Notes |
|---|---|---|
| TapGestureRecognizer | ✅ | MouseLeftButtonUp via GestureManager |
| PointerGestureRecognizer | ✅ | MouseEnter/Leave/Move |
| PanGestureRecognizer | ✅ | Mouse capture + delta tracking |
| SwipeGestureRecognizer | ✅ | Threshold-based direction detection |
| PinchGestureRecognizer | ✅ | Ctrl+MouseWheel zoom |
| DragGestureRecognizer | ✅ | WPF DragDrop.DoDragDrop |
| DropGestureRecognizer | ✅ | AllowDrop + DragOver/Drop events |
| LongPressGestureRecognizer | ✅ | DispatcherTimer 500ms hold |
Shapes
All MAUI shapes render via WPF System.Windows.Shapes:
Rectangle · RoundRectangle · Ellipse · Line · Path · Polygon · Polyline — with Fill, Stroke, StrokeDashPattern support.
Infrastructure
| Component | Status | Notes |
|---|---|---|
| Application | ✅ | MauiWPFApplication base class |
| Window | ✅ | Title, Size, Position, Min/Max, MenuBar, Multi-window |
| Dispatcher | ✅ | WPF Dispatcher + DispatcherProvider |
| Dialogs | ✅ | DisplayAlert, DisplayActionSheet, DisplayPromptAsync (native WPF windows with app-provided button labels) |
| Font Management | ✅ | IFontManager, IFontRegistrar, embedded font loading, FontImageSource glyph rendering |
| Dark/Light Mode | ✅ | ThemeManager detects via registry + SystemEvents, fires ThemeChanged |
| Animations | ✅ | WPFTicker at ~60fps, TranslateTo/FadeTo/ScaleTo/RotateTo all work |
| Transforms | ✅ | TranslationX/Y, Scale, Rotation → TransformGroup with RenderTransformOrigin |
| Shadow | ✅ | DropShadowEffect with radius, offset, opacity |
| Clip | ✅ | UIElement.Clip via Geometry.Parse |
| MenuBar | ✅ | WPF Menu with MenuItem hierarchy, keyboard accelerators |
| AutomationId | ✅ | AutomationProperties.AutomationId + Semantic properties |
| ToolTip | ✅ | FrameworkElement.ToolTip |
| ContextFlyout | ✅ | WPF ContextMenu with MenuItem hierarchy |
| VisualStateManager | ✅ | PointerOver, Pressed, Focused, Disabled state hooks |
Essentials
Call builder.UseWPFEssentials() before builder.Build() on the WPF UI thread.
When Build() returns, every registered Essentials facade (FileSystem.Current,
Preferences.Default, DeviceInfo.Current, and the other supported APIs) uses the
same instance as dependency injection, including application overrides registered
before or after UseWPFEssentials(). Static calls are supported after Build(),
not while configuring the builder. Unsupported desktop capabilities keep their
existing stub behavior.
Version tracking records a launch only when VersionTracking.Track() or a
tracking property is used, not merely when building the app.
The facades are process-wide: the most recently built app sets their instances. Do not use them after disposing that app.
FileSystem.AppDataDirectory uses local application data and CacheDirectory
uses the temporary directory, each with the application name appended. Both
getters create the directory before returning it, without changing existing
contents; filesystem errors propagate to the caller.
Run the registration and filesystem regressions on Windows:
dotnet test platforms\Windows.WPF\tests\Essentials.Tests\Windows.WPF.Essentials.Tests.csproj -p:UseMaui=false.
The filesystem tests use unique application identities and real file writes;
they remove only their own directories, never the user storage roots.
| API | Status | Notes |
|---|---|---|
| AppInfo | ✅ | Assembly-based name, version, package; RequestedTheme |
| DeviceInfo | ✅ | OS version, DeviceIdiom.Desktop |
| Connectivity | ✅ | NetworkInterface.GetIsNetworkAvailable() |
| DeviceDisplay | ✅ | SystemParameters with DPI |
| FileSystem | ✅ | Environment.SpecialFolder paths |
| Preferences | ✅ | IsolatedStorage / registry-based |
| SecureStorage | ✅ | DPAPI (ProtectedData) |
| Clipboard | ✅ | WPF System.Windows.Clipboard |
| Browser | ✅ | Process.Start URL |
| Launcher | ✅ | Process.Start |
| ✅ | mailto: protocol | |
| Map | ✅ | Bing Maps URL |
| Screenshot | ✅ | RenderTargetBitmap capture |
| VersionTracking | ✅ | Preferences-backed |
| TextToSpeech | ✅ | System.Speech.Synthesis via PowerShell |
| Battery | ✅ | Returns Full/AC for desktop |
| Share | ⚠️ | Stub — no native share dialog on Windows desktop |
| FilePicker | ⚠️ | Stub — needs WPF OpenFileDialog implementation |
| Sensors | ⚠️ | Stubs (Accelerometer, Gyroscope, Compass, Barometer — N/A for desktop) |
| Geolocation | ⚠️ | Stub (limited desktop relevance) |
| Haptics / Vibration | ⚠️ | Stubs (N/A for desktop) |
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 handler regression suite exercises real native container callbacks and selection, including CollectionView parenting, recycling, equal-valued items, runtime item/group template and grouping changes, group headers and footers, conversion failures, recursive handler disconnection, and DevFlow tree discovery. Template changes rebuild realized roots without requiring an ItemsSource change and preserve single/multiple selection of equal-valued grouped item occurrences. Single selection is restored from the saved native occurrence, independently of the virtual SelectedItem representation. Native selection exposes the underlying data through MAUI's SelectedItem without moving selection to the first equal-valued grouped row. Live-window cases select native rows through UI Automation and verify selection survives template changes and footer insertion/removal without extra selection events or taps. Retired template roots and their descendants disconnect on clear, reuse, template replacement, conversion failure, and handler teardown:
dotnet test tests\HandlerTests\HandlerTests.csproj -p:UseMaui=false
In the gallery, open Collection View and choose CollectionView in the
example picker. DevFlow can find realized contact labels by text or their name
as an automation id. Tapping Alice Johnson or Bob Smith updates the status
to Tapped: <name>, providing an observable check beyond a successful tap response.
The ci-wpf.yml compatibility matrix runs AlertManagerSubscriptionTests in the
existing HandlerTests project against MAUI 10.0.41, 10.0.60, 10.0.70 and 10.0.110
through the shared build workflow's targeted test mode. These are registration
contract tests, not native dialog interaction tests.
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()returnsobject—WPFViewHandler<TVirtualView, TPlatformView>provides the typed bridge. - The platform-agnostic
ViewHandlerhas no-opPlatformArrangeand returnsSize.Zero.WPFViewHandleroverrides these to bridge MAUI layout to WPFMeasure/Arrange. - WPF
System.Windows.Controlsand MAUIMicrosoft.Maui.Controlsshare many type names — every handler file usesusingaliases to disambiguate (e.g.,WButton = System.Windows.Controls.Button). - The
MauiWPFApplicationbase class inApp.xamlbootstraps the MAUI runtime within a WPFApplication. - Dialogs use
DispatchProxy+ reflection to interceptAlertManagerrequests (the API is internal in MAUI). Both the nested subscription interface in MAUI 10.0.41–10.0.60 and the top-level interface in 10.0.70+ are supported. An unrecognized contract fails during registration rather than leaving dialog tasks pending. 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
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net10.0-windows7.0 is compatible. |
-
net10.0-windows7.0
- Microsoft.AspNetCore.Components.WebView.Maui (>= 10.0.41)
- Microsoft.AspNetCore.Components.WebView.Wpf (>= 10.0.41)
- Microsoft.Maui.Controls (>= 10.0.41)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on Microsoft.Maui.Platforms.Windows.WPF:
| Package | Downloads |
|---|---|
|
Microsoft.Maui.Platforms.Windows.WPF.Essentials
MAUI Essentials implementations for the WPF backend — clipboard, preferences, device info, connectivity, and more using WPF and Windows APIs. |
|
|
Microsoft.Maui.DevFlow.Agent.WPF
WPF agent for Microsoft.Maui.DevFlow. Provides visual tree inspection, element interactions, and screenshots for MAUI WPF apps. |
GitHub repositories
This package is not used by any popular GitHub repositories.
| Version | Downloads | Last Updated |
|---|---|---|
| 0.1.0-preview.14.26555.2 | 75 | 11/6/2026 |
| 0.1.0-preview.14.26531.2 | 105 | 10/31/2026 |
| 0.1.0-preview.13.26526.5 | 84 | 10/26/2026 |
| 0.1.0-preview.13.26512.5 | 96 | 10/12/2026 |
| 0.1.0-preview.12.26421.1 | 172 | 8/21/2026 |
| 0.1.0-preview.12.26368.2 | 116 | 7/18/2026 |
| 0.1.0-preview.12.26358.3 | 118 | 7/8/2026 |
| 0.1.0-preview.11.26317.2 | 150 | 6/17/2026 |
| 0.1.0-preview.10.26274.3 | 105 | 5/24/2026 |
| 0.1.0-preview.9.26258.5 | 110 | 5/11/2026 |
| 0.1.0-preview.8.26256.5 | 106 | 5/6/2026 |










