Considerations When Porting a WPF App to .NET MAUI

See how WPF and .NET MAUI compare and what to be aware of if you’re going to migrate to .NET MAUI.

When starting a new application, a development team needs to carefully consider which framework is best suited to the project’s overall requirements.

While they share some similarities, frameworks differ significantly in terms of architecture, platform support, UI development paradigms, etc. As an example, Microsoft’s .NET Framework offers WPF targeted to Windows Desktop development or a more flexible option in .NET MAUI that enables developing a single project targeting a wide range of mobile and desktop devices with the added benefit of sharing code with web apps and services.

This matter must be well addressed and investigated before proceeding with implementation.

For a deeper review of how to make a better decision based on the business perspective and the background and learning curve in mind, see our blog post on WPF or .NET MAUI—How to Choose.

The Why: True Cross-Platform App | macOS Support

.NET MAUI, the multi-platform app UI for .NET, builds on top of the cross-platform layer for you, and in addition it provides cross-platform access to APIs directly in those native platforms. It allows the developer to use the architectural pattern of preference (MVU, MVVM or none) and this can simplify the UI development process.

Once you’ve made the decision on how to proceed, there are certain things to preface before you get started with actual migrating.

First, you should analyze your existing WPF project and look at all the dependencies. That includes class libraries and third-party control libraries that you are using. If those libraries are from Progress Telerik, then you surely are familiar with our way of distribution.

Topics to consider when modernizing an app from WPF to .NET MAUI include:

Starting Out: Create Fresh .NET MAUI App Project | Move Assets Over

To make sure you have a running .NET MAUI application, follow the step-by-step guidance on building your first cross-platform app on Windows. Further details on the system requirements and available settings are listed in the Microsoft .NET MAUI documentation.

Then, to proceed with using our third-party libraries, make sure to check the different Telerik UI for .NET MAUI Installation Approaches and explore the Available Product Files and Assemblies as well. Installing Telerik UI for .NET MAUI with NuGet would work both for Windows and macOS machines. Alternatively, you could download an .msi installer for Windows or a .pkg for macOS.

Benefiting from the Telerik .NET MAUI App and Telerik .NET MAUI Blank App project templates, you can quickly create an application that is pre-configured to use Telerik UI for .NET MAUI.

Understand Differences: Layouts | Multi-windows | .NET APIs | Deployments

While WPF is designed for dynamic, visual appealing desktop applications targeting Windows, the base layouts in .NET MAUI are slightly different from WPF, but most perform the same functions you are already familiar with in WPF.

In both cases the layouts are built using XAML and custom controls or layouts can be developed using C#.

For example, instead of a StackPanel in WPF, you use a StackLayout in .NET MAUI. I would suggest you take a look at the .NET MAUI documentation before porting the code directly: Layouts - .NET MAUI | Microsoft Learn.

.NET MAUI is excellent for building cross-platform applications that run on almost any platform as the MAUI layouts also use XAML and C#, but they are more optimized for multi-device compatibility, automatically adapting to various screen sizes and orientations.

While WPF natively supports managing multiple windows as a straightforward task, .NET MAUI allows creating multiple windows only on platforms that support it, and the concept of multi-windows is limited on mobile platforms that might be constrained by platform-specific behaviors.

.NET MAUI has a good integration with the .NET ecosystem. It includes platform-specific APIs through dependency injection and handlers, allowing developers to access native APIs for the various platforms within a shared codebase. Further, handlers can be customized to amplify the appearance and behavior of a cross-platform control beyond the customization that’s possible through the control’s API. Since WPF covers Windows-only, it can take full advantage of all the Windows OS-specific APIs without worrying about cross-platform limitations—those can be still adjusted.

As it comes to deployment, WPF apps rely on Windows-specific technologies that can’t run on other platforms without virtual environments. The apps are typically distributed as .exe files.

.NET MAUI apps can be deployed using app stores or via direct installers, or as unpacked exe. Blazor Hybrid apps are also supported, allowing a combination of web-based and native UI technologies.

XAML Differences: Namespaces | UI Differences

Why XAML? To separate user interface definition from code and allow you to port UI to different environments (Windows desktop, Windows store, iOS, etc.).

Both frameworks use XAML for defining the user interface and styling which allows the creation of rich, declarative UI.

On top of that, .NET MAUI supports more unified XAML syntax across platforms and offers a native look and feel with Windows 11 styling by default. Plus, to support a concise and platform-agnostic way to create UI components, .NET MAUI introduces a fluent API “MAUI markup.”

More on XAML in .NET MAUI vs. XAML in WPF/WinUI:

• Some control names are different while the same types of controls exist.
• Some property names are different while used to set the same action.
• XAML works well with the Model-View-ViewModel (MVVM) pattern.
• Markup extensions are supported enhancing the flexibility.
• Mimics with greater visual clarity the parent-child hierarchy.

While XAML isn’t mandatory for a .NET MAUI app, it’s the preferred method for UI development due to its conciseness and robust tooling support. Additionally, Telerik UI for .NET MAUI suggests theming support and other features are upcoming, as listed on the official roadmap.

.NET MAUI pages would have a similar structure to WPF windows or user controls. For example, this is how a sample view with the respective XAML namespaces would look like for a .NET MAUI project:

_<ContentView xmlns="http://schemas.microsoft.com/dotnet/2021/maui"_
  _xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"_
  _xmlns:telerik=_[_http://schemas.telerik.com/2022/xaml/maui_](http://schemas.telerik.com/2022/xaml/maui)  _…./>_

The third namespace above defines the Telerik toolkit. This is how a similar code would look like in a WPF project:

<Window xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
  xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
  xmlns:telerik=[http://schemas.telerik.com/2008/xaml/presentation](http://schemas.telerik.com/2008/xaml/presentation) … />

Interactivity: Mouse Pointers | Event Handling I Commands

WPF provides deep integration with the mouse as the primary input device, providing rich support for capturing and manipulating mouse input that empowers flexible event handling.

In .NET MAUI, this ability is more generalized, as touch and gesture handling take precedence on mobile platforms.

.NET MAUI must abstract away the differences between platforms where event handling would be more straightforward but less flexible.

As a result, WPF offers advanced and specialized system for handling mouse events, whereas .NET MAUI abstracts input handling to work across multiple platforms, with less focus on mouse input and more focus on general input methods like touch and gestures. For instance, in .NET MAUI mouse events (MouseEnter, MouseLeave) are mostly relevant to desktop platforms, whereas touch events (Tapped, Swiped) are more relevant to mobile.

Both WPF and .NET MAUI follow a similar model for basic event handling, but there are differences in syntax and available events due to platform-specific considerations.

Let’s see a simple example with a Button in WPF:

<Button Content="Click Me" Click="Button_Click"/>
private void Button_Click(object sender, RoutedEventArgs e)
{
  MessageBox.Show("Button Clicked!");
}

The same code in .NET MAUI would look like:

<Button Text="Click Me" Clicked="Button_Clicked"/>
private void Button_Clicked(object sender, EventArgs e)
{
  DisplayAlert("Alert", "Button Clicked!", "OK");
}

It is worth mentioning that WPF uses the RoutedEventArgs class, which supports WPF’s routed events, while .NET MAUI generally uses the standard EventArgs class for basic events that are handled directly at the source but provides platform-specific event arguments for more advanced scenarios.

In .NET MAUI, commanding is also available, and it’s very similar to WPF. For example, you can use ICommand with a binding in XAML.

public ICommand MyCommand { get; }
public MyViewModel()
{
  MyCommand = new Command(ExecuteMyCommand);
}

Further, the framework supports all the modern .NET features such as hot reload, data binding and MVU (Model-View-Update) architecture, which allows for better code reuse across platforms.

Reuse Resources: Shared Images | XAML Styles + Templates

Reusing resources between WPF and .NET MAUI involves sharing common components or other resources while maintaining flexibility for platform-specific details. To share those efficiently, you can create a common XAML resource dictionary that both can reference (for styles, brushes, colors, templates, converters and other visual resources).

Even though WPF and .NET MAUI use different mechanisms to handle assets and images, you can organize shared images to be referenced when needed.

Naturally, the controls on .NET MAUI are automatically reacting with the accessibility settings changed by the end user to assure dynamic font sizes. Further, you can also use ControlTemplates and DataTemplates to retain the same UI flexibility as WPF.

For more information about using images, check out the topic on Add images to a .NET MAUI app project.

For advanced scenarios, you can explore the Telerik ImageEditor control for MAUI and the respective Telerik ImageEditor for WPF.

Reuse Business Logic: Isolate C# Code as Libraries | Dependencies

Reusing code from a WPF app can be a good strategy when migrating and it largely depends on how well-separated your business logic is from the UI. It would be easier if you’ve followed a clean separation of concerns (the MVVM pattern).

For example, you may use interfaces to decouple platform specific implementation. We could consider the code into the following main categories:

• Business Logic: Domain logic that handles operations based on your app’s rules.
• Data Access: Code that interacts with the database or file system.
• Services: APIs, third-party integrations, etc.
• Models: Data transfer objects (DTOs) or view models.

Then, so that the class library is compatible with both WPF and .NET MAUI, you have to move your core logic to a new class library and make sure to remove or abstract any dependencies on UI components.

If you need to target an older .NET Framework version of WPF, then you can consider refactoring the business logic into .NET Standard; otherwise, use .NET 6/7/8/9 so your code will run on both WPF and .NET MAUI. The goal would be to structure your code to separate the domain logic from the UI so that it can be shared across different platforms. This means to also refactor any code that directly interacts with WPF-specific namespaces (e.g., System.Windows.Controls, System.Windows.Media, etc.).

For a reference, the following topic describes all controls dependencies for Telerik UI for WPF.

For a detailed explanation of using the MVVM pattern in .NET MAUI, refer to Model-View-ViewModel (MVVM) in Enterprise Application Patterns using .NET MAUI.

Updated Ecosystem: Windows vs .NET MAUI Toolkits | Cross-Platform NuGets

While the Windows toolkit extends the Windows ecosystem with additional controls, helpers and extensions, the .NET MAUI Community Toolkit is specifically designed for cross-platform applications and provides a set of utilities, extensions and UI components intended to work seamlessly across all platforms supported with minimal platform-specific adjustments.

To start using .NET MAUI, you should install Microsoft.Maui.Controls (corresponding to Systems.Windows.Controls for WPF). There are various other packages available, for example CommunityToolkit.Mvvm provides support for MVVM pattern and simplifies the command implementation with attributes, the Microsoft.Maui.Graphics package contains a collection of graphics and drawing APIs.

In case you are migrating from Xamarin.Forms, you should check the Microsoft.Maui.Controls.Compatibility package that contains a collection of APIs and views.

Once you’ve set up the base, the Telerik UI for .NET MAUI Toolbox extension can facilitate adding our third-party controls to your .NET MAUI application.

Updated Telerik UI: WPF vs .NET MAUI | Differences in Namespaces

As a vendor of components, we do follow the naming standards set by Microsoft. Although WPF and .NET MAUI development has a lot in common, there are differences in the namespaces because WPF is a Windows-specific framework introduced years ago, whereas MAUI is newly designed to best serve cross-platform development.

Starting with the core UI namespaces, System.Windows in WPF would correspond to Microsoft.Maui. For a full list, you can refer to the .NET MAUI API reference version 8.

To look at specific namespaces of the Telerik library, Telerik.Windows.Controls in WPF corresponds to Telerik.Maui.Controls. Following the pattern, you can extend it to Telerik.Windows.Controls.Data - Telerik UI for WPF that maps to Telerik.Maui.Controls.Data - Telerik UI for .NET MAUI.

As it follows naturally, Telerik.Windows.Data in WPF would correspond to Telerik.Maui.Data. You can explore the entire API reference section that contains a list and descriptions of all publicly available classes, methods and properties of the Telerik UI for .NET MAUI.

There may be some naming differences—for example Class NotifyPropertyChangedBase - Telerik UI for .NET MAUI corresponds to Class ViewModelBase - Telerik UI for WPF.

You can use Telerik UI for .NET MAUI on Windows and macOS. Depending on the operation system you are using and on the preferred way to work with the product, the suite can be installed in the following ways:

• (Windows) MSI file installation
• (macOS) PKG file installation
• (Windows & macOS) NuGet installation

Installing Telerik UI for .NET MAUI with NuGet would work for both Windows and MacOS machines.

The Telerik.UI.for.Maui NuGet package supports the latest .NET, and automatically restores the required packages depending on the .NET version you are using in your project.

Although there is not a one-to-one API mapping from Telerik UI for WPF to Telerik UI for .NET MAUI, the controls share similar APIs with slight changes because of the differences between the frameworks.

Summary

Both WPF and .NET MAUI frameworks offer a lot of possibilities to achieve a good-looking UI that can be easily customized to meet business expectations.

You can find further examples on how to reuse code in the Styling and Customization section in the blog on WPF or .NET MAUI—How to Choose.

A great workshop to check out is the one on Modernization Through Migration. Plus, Progress Telerik UI for .NET MAUI offers a comprehensive getting started video curriculum available to both active trial users and active license holders in Virtual Classroom.

Make sure to also go through other practical details on how to Transform a WPF App to Cross-Platform with .NET MAUI.

Don’t forget you can try both UI for WPF and UI for .NET MAUI in the Telerik DevCraft suite. It comes with a free 30-day trial.

Try Now