Edit

Migrate from UWP to the Windows App SDK

This section covers moving a C# or C++/WinRT Universal Windows Platform (UWP) app to the Windows App SDK and WinUI 3. The guidance includes migration strategy, feature comparisons, and step-by-step feature-area guides.

The amount of work depends on the app's UI, app-model dependencies, packaging, background activity, windowing, and use of UWP-only features. Some XAML and platform code can transfer with namespace or API changes, but other areas require redesign or have no direct WinUI 3 equivalent. Assess support and test representative features before you estimate the migration.

Note

Your existing UWP app will continue to function as expected. However, to take advantage of modern features in WinUI 3 and the Windows App SDK we recommend migrating your app.

Here are the high-level steps for migrating manually:

  1. Create a new WinUI packaged desktop project (see Create and run a WinUI 3 project). That could go into your project's existing solution.
  2. Move a representative UI workflow and update its XAML namespaces, controls, resources, and app-model assumptions.
  3. Move the related app logic and replace or adapt APIs that behave differently in a desktop app, such as popups, pickers, windowing, and secondary tiles.

The topics in the table below describe and demonstrate how to manually migrate your UWP application to the Windows App SDK.

Important

Before you begin, read What's supported when migrating from UWP to WinUI. This topic lists features that aren't yet supported in WinUI 3 and the Windows App SDK. If your app depends on any of those features, consider postponing migration until support is available.

Note

If your UWP app's source code is written in C++/CX, then also see Move to C++/WinRT from C++/CX.

Legacy .NET Upgrade Assistant guidance

Important

.NET Upgrade Assistant is deprecated. Don't use it to start a new migration. GitHub Copilot upgrade doesn't currently document UWP-to-WinUI 3 as a supported upgrade path.

If you're maintaining a C# UWP migration that already uses .NET Upgrade Assistant, see the legacy .NET Upgrade Assistant guidance. For a new migration, use the manual guidance on this page. An AI assistant can optionally support the bounded review tasks described below.

Use an AI assistant as an optional review aid

An AI coding assistant can help you inventory namespace usage, locate APIs that need desktop interop, draft a mapping for a bounded feature, or propose edits for one migration step. Treat those results as suggestions, not verified substitutions.

Review every proposed API and project change against the feature mapping, API mapping, and current API reference. Build and test each bounded change, including packaging, activation, window ownership, threading, accessibility, and failure paths. An assistant can't determine whether a missing WinUI 3 feature is acceptable for your product or guarantee that generated code preserves behavior.

Containerization benefits

When transitioning to the Windows App SDK, UWP applications might lose the inherent containerization benefits of their original platform. However, those benefits can be restored by using Win32 App Isolation—a new security feature that enhances protection by isolating applications within a sandbox environment. This approach offers additional security against potential threats with minimal changes to your existing code. For more info, and to begin using Win32 App Isolation, see Win32 app isolation overview.

Topics in this section

Topic Description
UWP migration strategy Considerations and strategies for approaching the migration process, and how to set up your development environment for migrating.
Mapping UWP features to the Windows App SDK This topic compares major feature areas in the different forms in which they appear in UWP and in the Windows App SDK.
What's supported Learn what features are currently available in WinUI Desktop to evaluate whether you should attempt migrating your UWP app today.
Mapping UWP APIs and libraries to Windows App SDK This topic provides a mapping of UWP APIs and libraries to their Windows App SDK equivalents.
Feature area guides A collection of migration guidance topics, each focusing on a specific feature area.
Case study 1—PhotoLab (C#) This topic is a case study of taking the C# UWP PhotoLab sample app, and migrating it to the Windows App SDK.
Case study 2—Photo Editor (C++/WinRT) This topic is a case study of taking the C++/WinRT UWP Photo Editor sample app, and migrating it to the Windows App SDK.
Additional migration guidance This topic contains additional migration guidance not categorized into a feature area in the feature area guides.
Legacy .NET Upgrade Assistant guidance for UWP Reference information for maintaining an existing C# UWP migration that used the deprecated .NET Upgrade Assistant.

See also

UWP migration strategy

  • Last updated on