dotnet-wpf-migration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

dotnet-wpf-migration

.NET桌面应用迁移指南

Context-dependent migration guidance for Windows desktop applications. Covers WPF .NET Framework to .NET 8+, WPF to WinUI 3 (Windows-only modernization), WPF to Uno Platform (cross-platform), WinForms .NET Framework to .NET 8+, UWP to WinUI 3, UWP to Uno Platform (cross-ref), and a decision matrix for choosing the right migration target based on project constraints.

Version assumptions: .NET 8.0+ baseline (current LTS).

dotnet-upgrade-assistant

for automated migration. .NET 9 features explicitly marked where applicable.

针对Windows桌面应用的场景化迁移指南，涵盖以下内容：WPF .NET Framework迁移至.NET 8+、WPF迁移至WinUI 3（仅限Windows平台的现代化改造）、WPF迁移至Uno Platform（跨平台）、WinForms .NET Framework迁移至.NET 8+、UWP迁移至WinUI 3、UWP迁移至Uno Platform（交叉参考），以及根据项目约束选择合适迁移目标的决策矩阵。

版本假设：以.NET 8.0+（当前长期支持版本）为基准，使用

dotnet-upgrade-assistant

进行自动化迁移。涉及.NET 9的功能会明确标注。

Scope

适用范围

Migration decision matrix (current framework to target framework)
WPF .NET Framework to .NET 8+ migration
WPF to WinUI 3 (Windows-only modernization)
WPF to Uno Platform (cross-platform)
WinForms .NET Framework to .NET 8+
UWP to WinUI 3 and UWP to Uno Platform

迁移决策矩阵（当前框架到目标框架）
WPF .NET Framework迁移至.NET 8+
WPF迁移至WinUI 3（仅限Windows平台的现代化改造）
WPF迁移至Uno Platform（跨平台）
WinForms .NET Framework迁移至.NET 8+
UWP迁移至WinUI 3及UWP迁移至Uno Platform

Out of scope

不适用范围

WPF .NET 8+ development patterns -- see [skill:dotnet-wpf-modern]
WinUI 3 development patterns -- see [skill:dotnet-winui]
WinForms .NET 8+ development patterns -- see [skill:dotnet-winforms-basics]
Uno Platform development patterns -- see [skill:dotnet-uno-platform]
Framework selection decision tree -- see [skill:dotnet-ui-chooser]
Desktop testing -- see [skill:dotnet-ui-testing-core]

Cross-references: [skill:dotnet-wpf-modern] for WPF .NET 8+ patterns, [skill:dotnet-winui] for WinUI 3 patterns, [skill:dotnet-winforms-basics] for WinForms .NET 8+ patterns, [skill:dotnet-uno-platform] for Uno Platform patterns, [skill:dotnet-ui-chooser] for framework selection, [skill:dotnet-ui-testing-core] for desktop testing.

WPF .NET 8+开发模式——详见[skill:dotnet-wpf-modern]
WinUI 3开发模式——详见[skill:dotnet-winui]
WinForms .NET 8+开发模式——详见[skill:dotnet-winforms-basics]
Uno Platform开发模式——详见[skill:dotnet-uno-platform]
框架选择决策树——详见[skill:dotnet-ui-chooser]
桌面应用测试——详见[skill:dotnet-ui-testing-core]

交叉参考：[skill:dotnet-wpf-modern]（WPF .NET 8+模式）、[skill:dotnet-winui]（WinUI 3模式）、[skill:dotnet-winforms-basics]（WinForms .NET 8+模式）、[skill:dotnet-uno-platform]（Uno Platform模式）、[skill:dotnet-ui-chooser]（框架选择）、[skill:dotnet-ui-testing-core]（桌面应用测试）。

Migration Path Overview

迁移路径总览

Choose a migration path based on your current framework and target goals. Each path has different trade-offs in effort, risk, and capability gain.

Current	Target	Effort	Risk	When to Choose
WPF .NET Framework	WPF .NET 8+	Low-Medium	Low	Modernize runtime, keep existing UI
WPF .NET Framework	WinUI 3	High	Medium	Modern Windows UI, touch/pen, Fluent
WPF .NET Framework	Uno Platform	High	Medium-High	Cross-platform needed
WinForms .NET Framework	WinForms .NET 8+	Low	Low	Modernize runtime, keep existing UI
UWP	WinUI 3	Medium	Medium	Stay Windows-only, modern runtime
UWP	Uno Platform	Medium-High	Medium	Cross-platform needed from UWP

根据当前使用的框架和目标需求选择迁移路径，不同路径在工作量、风险和能力提升方面各有取舍。

当前框架	目标框架	工作量	风险	适用场景
WPF .NET Framework	WPF .NET 8+	低-中	低	现代化运行时，保留现有UI
WPF .NET Framework	WinUI 3	高	中	打造现代化Windows UI，支持触控/手写笔，采用Fluent设计
WPF .NET Framework	Uno Platform	高	中-高	需要跨平台支持
WinForms .NET Framework	WinForms .NET 8+	低	低	现代化运行时，保留现有UI
UWP	WinUI 3	中	中	仅限Windows平台，采用现代化运行时
UWP	Uno Platform	中-高	中	从UWP扩展至跨平台

WPF .NET Framework to .NET 8+

WPF .NET Framework迁移至.NET 8+

The lowest-risk migration path. Keeps your existing XAML and code-behind intact while moving to modern .NET with better performance, DI support, and side-by-side deployment.

这是风险最低的迁移路径，可在保留现有XAML和代码隐藏文件的同时，迁移至性能更优、支持依赖注入（DI）且支持并行部署的现代.NET环境。

Using dotnet-upgrade-assistant

使用dotnet-upgrade-assistant

The .NET Upgrade Assistant automates the bulk of the migration:

bash

undefined

.NET升级助手可自动化完成大部分迁移工作：

bash

undefined

Install the upgrade assistant

安装升级助手

dotnet tool install -g upgrade-assistant

Analyze the project first (non-destructive)

先分析项目（无破坏性操作）

upgrade-assistant analyze MyWpfApp.sln

Upgrade the project

执行升级

upgrade-assistant upgrade MyWpfApp.sln


**What the upgrade assistant handles:**
- `.csproj` conversion from legacy format to SDK-style
- `packages.config` to `PackageReference` migration
- TFM change to `net8.0-windows`
- `AssemblyInfo.cs` properties moved to `.csproj`
- Common API replacements and namespace updates

**What requires manual work:**
- `App.config` settings migration to `appsettings.json` or Host builder configuration
- `Settings.settings` / `My.Settings` (VB.NET) migration
- Third-party control library updates (check vendor .NET 8 compatibility)
- WCF client references (use `CoreWCF` or migrate to gRPC/REST)
- COM interop adjustments (syntax differences in `System.Runtime.InteropServices`)
- Custom MSBuild targets and build scripts

upgrade-assistant upgrade MyWpfApp.sln


**升级助手处理的内容**：
- 将`.csproj`从旧格式转换为SDK风格格式
- 将`packages.config`迁移至`PackageReference`
- 将目标框架（TFM）更改为`net8.0-windows`
- 将`AssemblyInfo.cs`中的属性迁移至`.csproj`
- 常见API替换和命名空间更新

**需要手动处理的内容**：
- 将`App.config`设置迁移至`appsettings.json`或Host构建器配置
- 迁移`Settings.settings` / `My.Settings`（VB.NET）
- 更新第三方控件库（需确认供应商是否支持.NET 8）
- WCF客户端引用（改用`CoreWCF`或迁移至gRPC/REST）
- COM互操作调整（`System.Runtime.InteropServices`中的语法差异）
- 自定义MSBuild目标和构建脚本

API Compatibility

API兼容性

Most WPF APIs are identical between .NET Framework and .NET 8+. Key differences:

Area	.NET Framework	.NET 8+	Action
Clipboard	`Clipboard.SetText()`	Same API	No change
Printing	`PrintDialog` , `PrintVisual`	Same API	No change
BitmapEffect	Deprecated (software-rendered)	Removed	Use `Effect` / `ShaderEffect`
`DrawingContext.PushEffect`	Available	Removed	Use `ShaderEffect`
XPS documents	`System.Windows.Xps`	Requires NuGet package	Add `System.Windows.Xps` PackageReference
Speech synthesis	`System.Speech`	Requires NuGet package	Add `System.Speech` PackageReference

WPF的大多数API在.NET Framework和.NET 8+中保持一致，主要差异如下：

领域	.NET Framework	.NET 8+	操作建议
剪贴板	`Clipboard.SetText()`	相同API	无需修改
打印	`PrintDialog` 、 `PrintVisual`	相同API	无需修改
BitmapEffect	已弃用（软件渲染）	已移除	使用 `Effect` / `ShaderEffect` 替代
`DrawingContext.PushEffect`	可用	已移除	使用 `ShaderEffect` 替代
XPS文档	`System.Windows.Xps`	需要NuGet包	添加 `System.Windows.Xps` PackageReference
语音合成	`System.Speech`	需要NuGet包	添加 `System.Speech` PackageReference

NuGet Package Updates

NuGet包更新

After migration, update NuGet packages to .NET 8-compatible versions:

bash

undefined

迁移完成后，需将NuGet包更新至兼容.NET 8的版本：

bash

undefined

List outdated packages

列出过时的包

dotnet list package --outdated

Update packages (one at a time for safer migration)

逐个更新包（更安全的迁移方式）

dotnet add package Newtonsoft.Json --version 13.* dotnet add package MaterialDesignThemes --version 5.*


**Common package replacements:**
- `Unity` container -> `Microsoft.Extensions.DependencyInjection` (built-in)
- `Autofac` -> update to latest (supports .NET 8)
- `log4net` / `NLog` -> consider `Microsoft.Extensions.Logging` with Serilog or NLog provider
- `EntityFramework` (EF6) -> `Microsoft.EntityFrameworkCore` 8.x

dotnet add package Newtonsoft.Json --version 13.* dotnet add package MaterialDesignThemes --version 5.*


**常见包替换方案**：
- `Unity`容器 -> `Microsoft.Extensions.DependencyInjection`（内置）
- `Autofac` -> 更新至最新版本（支持.NET 8）
- `log4net` / `NLog` -> 考虑使用`Microsoft.Extensions.Logging`搭配Serilog或NLog提供程序
- `EntityFramework`（EF6） -> `Microsoft.EntityFrameworkCore` 8.x

Breaking Changes Checklist

破坏性变更检查清单

Default high-DPI behavior changed. .NET 8 WPF enables
```
PerMonitorV2
```
DPI awareness by default (not
```
SystemAware
```
like .NET Framework).
Nullable reference types. New projects enable NRT. Existing code may produce warnings. Suppress with
```
<Nullable>disable</Nullable>
```
initially, then fix incrementally.
Implicit usings. New SDK-style projects enable implicit usings. May conflict with existing
```
using
```
statements. Disable with
```
<ImplicitUsings>disable</ImplicitUsings>
```
if needed.
Assembly loading.
```
AssemblyLoadContext
```
replaces
```
AppDomain
```
for assembly isolation. Plugin architectures using
```
AppDomain.CreateDomain
```
need rework.
Runtime behavior. .NET 8 GC is more aggressive with Gen0/Gen1 collections. Finalizer-dependent code may behave differently.

For post-migration WPF patterns (Host builder, MVVM Toolkit, modern C#), see [skill:dotnet-wpf-modern].

默认高DPI行为已更改：.NET 8 WPF默认启用
```
PerMonitorV2
```
DPI感知（而非.NET Framework中的
```
SystemAware
```
）。
可为空引用类型：新项目默认启用NRT，现有代码可能产生警告。可先通过
```
<Nullable>disable</Nullable>
```
禁用，再逐步修复。
隐式using：新SDK风格项目默认启用隐式using，可能与现有
```
using
```
语句冲突。如有需要，可通过
```
<ImplicitUsings>disable</ImplicitUsings>
```
禁用。
程序集加载：
```
AssemblyLoadContext
```
替代
```
AppDomain
```
用于程序集隔离，使用
```
AppDomain.CreateDomain
```
的插件架构需要重构。
运行时行为：.NET 8 GC对Gen0/Gen1集合的回收更积极，依赖终结器的代码行为可能有所不同。

关于迁移后的WPF模式（Host构建器、MVVM Toolkit、现代C#），详见[skill:dotnet-wpf-modern]。

WPF to WinUI 3

WPF迁移至WinUI 3

Migrate when you need modern Windows-native UI: Fluent Design, touch/pen input, Windows 11 integration (widgets, Mica), or UWP-style APIs on modern .NET. This is a partial rewrite -- XAML concepts transfer but APIs and namespaces differ.

当你需要现代化的Windows原生UI时选择此迁移路径：Fluent设计、触控/手写笔输入、Windows 11集成（小组件、云母效果），或在现代.NET上使用UWP风格API。这是部分重写——XAML概念可迁移，但API和命名空间有所不同。

When This Path Makes Sense

适用场景

Application is Windows-only and will stay Windows-only
Need modern Fluent Design controls, touch/pen support, or Windows 11 features
Team is willing to invest in XAML rewrite effort
Application is actively developed with ongoing feature work (justifies the investment)

应用仅限Windows平台且将保持Windows-only
需要现代化的Fluent设计控件、触控/手写笔支持或Windows 11功能
团队愿意投入XAML重写工作量
应用处于活跃开发阶段且有持续的功能迭代（值得投入）

When to Consider Alternatives

替代方案考量

If cross-platform is needed -> migrate to Uno Platform instead (WinUI XAML surface)
If application is in maintenance mode -> migrate to WPF .NET 8+ instead (lower effort)
If WPF Fluent theme (.NET 9+) is sufficient -> stay on WPF .NET 8+ with
```
ThemeMode = ThemeMode.System
```

如果需要跨平台支持 -> 迁移至Uno Platform（基于WinUI XAML界面）
如果应用处于维护阶段 -> 迁移至WPF .NET 8+（工作量最低）
如果WPF Fluent主题（.NET 9+）已满足需求 -> 继续使用WPF .NET 8+并设置
```
ThemeMode = ThemeMode.System
```

XAML Differences

XAML差异

WPF XAML	WinUI 3 XAML	Notes
`xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"`	Same URI (but resolves to `Microsoft.UI.Xaml` types, not `System.Windows` )	No xmlns change, but runtime types differ
`{Binding Path=Name}`	`{x:Bind Name, Mode=OneWay}`	Prefer `x:Bind` (compiled, type-safe)
`DataContext` binding	Code-behind property + `x:Bind`	`x:Bind` resolves against code-behind
`Window` inherits from `System.Windows.Window`	`Window` inherits from `Microsoft.UI.Xaml.Window`	Different base class and API
`UserControl`	`UserControl` (Microsoft.UI.Xaml namespace)	Same concept, different namespace
`Style` with `TargetType`	Same	Works the same way
`DataTemplate`	Needs `x:DataType` for `x:Bind`	Required for compiled bindings
`ContextMenu`	`MenuFlyout`	Different control type
`StatusBar`	No built-in equivalent	Use custom `CommandBar` or `InfoBar`
`RibbonControl`	No built-in equivalent	Use `NavigationView` + `CommandBar`

WPF XAML	WinUI 3 XAML	说明
`xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"`	相同URI（但解析为 `Microsoft.UI.Xaml` 类型，而非 `System.Windows` ）	无需更改xmlns，但运行时类型不同
`{Binding Path=Name}`	`{x:Bind Name, Mode=OneWay}`	优先使用 `x:Bind` （编译时类型安全）
`DataContext` 绑定	代码隐藏属性 + `x:Bind`	`x:Bind` 解析自代码隐藏
`Window` 继承自 `System.Windows.Window`	`Window` 继承自 `Microsoft.UI.Xaml.Window`	基类和API不同
`UserControl`	`UserControl` （Microsoft.UI.Xaml命名空间）	概念相同，命名空间不同
`Style` 搭配 `TargetType`	相同	使用方式一致
`DataTemplate`	需为 `x:Bind` 添加 `x:DataType`	编译绑定的必填项
`ContextMenu`	`MenuFlyout`	控件类型不同
`StatusBar`	无内置等效控件	使用自定义 `CommandBar` 或 `InfoBar` 替代
`RibbonControl`	无内置等效控件	使用 `NavigationView` + `CommandBar` 替代

Migration Strategy

迁移策略

Create a new WinUI 3 project alongside the existing WPF project
Migrate shared logic first -- Models, Services, ViewModels (if using MVVM Toolkit, they work in both)
Migrate views incrementally -- start with simpler pages, then complex ones
Replace WPF-specific controls with WinUI equivalents (see table above)
Update data binding from
```
{Binding}
```
to
```
{x:Bind}
```
for compile-time safety
Test Windows integration features (notifications, lifecycle, file associations)
Choose deployment model -- MSIX (app identity) or unpackaged (xcopy)

For WinUI 3 patterns and project setup, see [skill:dotnet-winui].

在现有WPF项目旁创建新的WinUI 3项目
先迁移共享逻辑——模型、服务、视图模型（如果使用MVVM Toolkit，可在两者中通用）
逐步迁移视图——从简单页面开始，再处理复杂页面
将WPF特定控件替换为WinUI等效控件（见上表）
更新数据绑定——从
```
{Binding}
```
改为
```
{x:Bind}
```
以获得编译时安全保障
测试Windows集成功能（通知、生命周期、文件关联）
选择部署模式——MSIX（应用标识）或非打包（xcopy）

关于WinUI 3模式和项目设置，详见[skill:dotnet-winui]。

WPF to Uno Platform

WPF迁移至Uno Platform

Migrate when you need cross-platform reach from a WPF codebase. Uno Platform uses the WinUI XAML API surface, so WPF XAML skills transfer partially, but the migration involves adapting to WinUI XAML patterns.

当你需要从WPF代码库扩展至跨平台时选择此迁移路径。Uno Platform使用WinUI XAML API界面，WPF XAML技能可部分迁移，但迁移过程中需要适配WinUI XAML模式。

When This Path Makes Sense

适用场景

Application needs to run on multiple platforms (Windows, macOS, Linux, Web, mobile)
Team has WPF/XAML expertise that transfers to WinUI XAML surface
Willing to invest in cross-platform adaptation (platform-specific behaviors, responsive layouts)

应用需要在多平台运行（Windows、macOS、Linux、Web、移动端）
团队具备WPF/XAML经验，可迁移至WinUI XAML界面
愿意投入跨平台适配工作（平台特定行为、响应式布局）

When to Consider Alternatives

替代方案考量

If Windows-only -> migrate to WinUI 3 (simpler, no cross-platform overhead)
If application is in maintenance mode -> migrate to WPF .NET 8+ (lowest effort)
If team has web skills -> consider Blazor for web delivery

如果仅限Windows平台 -> 迁移至WinUI 3（更简单，无跨平台开销）
如果应用处于维护阶段 -> 迁移至WPF .NET 8+（工作量最低）
如果团队具备Web开发技能 -> 考虑使用Blazor进行Web交付

Migration Approach

迁移方法

The migration from WPF to Uno Platform is similar to WPF to WinUI 3 (since Uno uses the WinUI API surface), with additional cross-platform considerations:

Create an Uno Platform project with the desired target platforms
Migrate ViewModels and services -- these are platform-independent
Adapt XAML to WinUI syntax (same changes as WPF to WinUI migration)
Handle platform-specific features using conditional compilation or Uno platform extensions
Replace Windows-only APIs with cross-platform alternatives (file dialogs, notifications, etc.)
Test each target platform -- rendering and behavior may differ across Skia and native targets

从WPF到Uno Platform的迁移与WPF到WinUI 3的迁移类似（因为Uno使用WinUI API界面），但需要额外考虑跨平台因素：

创建Uno Platform项目并选择所需的目标平台
迁移视图模型和服务——这些是平台无关的
调整XAML以适配WinUI语法（与WPF到WinUI迁移的更改相同）
使用条件编译或Uno平台扩展处理平台特定功能
将Windows专属API替换为跨平台替代方案（文件对话框、通知等）
测试每个目标平台——Skia和原生目标的渲染和行为可能有所不同

Uno Extensions for Common Patterns

用于常见模式的Uno扩展

Uno Extensions provides cross-platform replacements for common WPF patterns:

WPF Pattern	Uno Extensions Replacement
Custom navigation	`Uno.Extensions.Navigation`
Manual DI setup	`Uno.Extensions.DependencyInjection` (wraps MS DI)
`appsettings.json` config	`Uno.Extensions.Configuration`
Manual HTTP clients	`Uno.Extensions.Http` (typed clients with Refit)
Manual serialization	`Uno.Extensions.Serialization`

For Uno Platform development patterns, see [skill:dotnet-uno-platform]. For per-target deployment guidance, see [skill:dotnet-uno-targets].

WPF模式	Uno Extensions替代方案
自定义导航	`Uno.Extensions.Navigation`
手动DI设置	`Uno.Extensions.DependencyInjection` （封装MS DI）
`appsettings.json` 配置	`Uno.Extensions.Configuration`
手动HTTP客户端	`Uno.Extensions.Http` （搭配Refit的类型化客户端）
手动序列化	`Uno.Extensions.Serialization`

关于Uno Platform开发模式，详见[skill:dotnet-uno-platform]。关于各目标平台的部署指南，详见[skill:dotnet-uno-targets]。

WinForms .NET Framework to .NET 8+

WinForms .NET Framework迁移至.NET 8+

Similar to WPF migration but typically simpler due to WinForms' less complex project structure.

与WPF迁移类似，但由于WinForms的项目结构更简单，通常迁移难度更低。

Using dotnet-upgrade-assistant

使用dotnet-upgrade-assistant

bash

undefined

bash

undefined

Analyze first

先分析项目

upgrade-assistant analyze MyWinFormsApp.sln

Upgrade

执行升级

upgrade-assistant upgrade MyWinFormsApp.sln


**What the upgrade assistant handles:**
- `.csproj` conversion to SDK-style with `<UseWindowsForms>true</UseWindowsForms>`
- TFM change to `net8.0-windows`
- `packages.config` to `PackageReference`
- `AssemblyInfo.cs` migration to project properties

**What requires manual work:**
- `App.config` / `Settings.settings` migration
- `My.Settings` (VB.NET) migration to modern configuration
- Third-party control library updates (some WinForms controls may lack .NET 8 support)
- Crystal Reports or other legacy reporting tools (evaluate alternatives)
- COM interop adjustments

upgrade-assistant upgrade MyWinFormsApp.sln


**升级助手处理的内容**：
- 将`.csproj`转换为SDK风格格式并添加`<UseWindowsForms>true</UseWindowsForms>`
- 将目标框架（TFM）更改为`net8.0-windows`
- 将`packages.config`迁移至`PackageReference`
- 将`AssemblyInfo.cs`中的属性迁移至项目属性

**需要手动处理的内容**：
- 迁移`App.config` / `Settings.settings`
- 将`My.Settings`（VB.NET）迁移至现代配置系统
- 更新第三方控件库（部分WinForms控件可能不支持.NET 8）
- Crystal Reports或其他旧版报表工具（评估替代方案）
- COM互操作调整

Designer Compatibility

设计器兼容性

WinForms designer files (

.Designer.cs

) generally migrate cleanly. The Visual Studio WinForms designer for .NET 8+ is fully supported.

Known designer issues:

Custom designer serializers may need updates
Some third-party controls may not render in the .NET 8 designer

DPI-unaware designer mode available in .NET 9+ (

<ForceDesignerDPIUnaware>true</ForceDesignerDPIUnaware>

)

WinForms设计器文件（

.Designer.cs

）通常可顺利迁移，Visual Studio对.NET 8+的WinForms设计器提供全面支持。

已知设计器问题：

自定义设计器序列化器可能需要更新
部分第三方控件可能无法在.NET 8设计器中渲染

.NET 9+提供了DPI感知关闭的设计器模式（

<ForceDesignerDPIUnaware>true</ForceDesignerDPIUnaware>

）

Post-Migration Modernization

迁移后的现代化改造

After migrating to .NET 8+, consider adopting modern patterns incrementally:

Add dependency injection via Host builder (see [skill:dotnet-winforms-basics])
Replace synchronous calls with async/await
Enable high-DPI with
```
PerMonitorV2
```
mode
Enable dark mode (experimental in .NET 9+)

For WinForms .NET 8+ patterns, see [skill:dotnet-winforms-basics].

迁移至.NET 8+后，可逐步采用现代模式：

通过Host构建器添加依赖注入（详见[skill:dotnet-winforms-basics]）
将同步调用替换为async/await
启用高DPI支持，设置为
```
PerMonitorV2
```
模式
启用深色模式（.NET 9+中为实验性功能）

关于WinForms .NET 8+模式，详见[skill:dotnet-winforms-basics]。

UWP to WinUI 3

UWP迁移至WinUI 3

UWP's natural migration target. WinUI 3 uses the same XAML API surface with namespace changes.

这是UWP的自然迁移目标，WinUI 3使用与UWP相同的XAML API界面，但命名空间有所变化。

Namespace Changes

命名空间变化

The primary migration task is updating namespaces from

Windows.UI.*

Microsoft.UI.*

UWP Namespace	WinUI 3 Namespace
`Windows.UI.Xaml`	`Microsoft.UI.Xaml`
`Windows.UI.Xaml.Controls`	`Microsoft.UI.Xaml.Controls`
`Windows.UI.Xaml.Media`	`Microsoft.UI.Xaml.Media`
`Windows.UI.Composition`	`Microsoft.UI.Composition`
`Windows.UI.Text`	`Microsoft.UI.Text`

Keep as-is:

Windows.Storage

Windows.Networking

Windows.Security

Windows.ApplicationModel

Windows.Devices

-- these WinRT APIs remain unchanged.

主要迁移工作是将命名空间从

Windows.UI.*

更新为

Microsoft.UI.*

：

UWP命名空间	WinUI 3命名空间
`Windows.UI.Xaml`	`Microsoft.UI.Xaml`
`Windows.UI.Xaml.Controls`	`Microsoft.UI.Xaml.Controls`
`Windows.UI.Xaml.Media`	`Microsoft.UI.Xaml.Media`
`Windows.UI.Composition`	`Microsoft.UI.Composition`
`Windows.UI.Text`	`Microsoft.UI.Text`

保持不变的命名空间：

Windows.Storage

、

Windows.Networking

、

Windows.Security

、

Windows.ApplicationModel

、

Windows.Devices

——这些WinRT API保持不变。

App Model Differences

应用模型差异

Concern	UWP	WinUI 3
App lifecycle	`CoreApplication` + suspension	Windows App SDK `AppInstance`
Window management	`Window.Current` (singleton)	Track window references manually
Dispatcher	`CoreDispatcher.RunAsync`	`DispatcherQueue.TryEnqueue`
Background tasks	Built-in, requires package identity	Available with MSIX, limited without
File access	Broad capabilities via manifest	Standard Win32 file access + `StorageFile`
Store APIs	`Windows.Services.Store`	Same (still available)

关注点	UWP	WinUI 3
应用生命周期	`CoreApplication` + 挂起	Windows App SDK `AppInstance`
窗口管理	`Window.Current` （单例）	手动跟踪窗口引用
调度器	`CoreDispatcher.RunAsync`	`DispatcherQueue.TryEnqueue`
后台任务	内置，需要包标识	仅在MSIX部署下可用，非打包部署下受限
文件访问	通过清单获取广泛权限	标准Win32文件访问 + `StorageFile`
商店API	`Windows.Services.Store`	相同（仍可用）

Migration Steps

迁移步骤

Create a new WinUI 3 project using the Windows App SDK template
Copy source files and update namespaces (
```
Windows.UI.Xaml
```
to
```
Microsoft.UI.Xaml
```
)
Replace deprecated APIs (
```
Window.Current
```
to manual tracking,
```
CoreDispatcher
```
to
```
DispatcherQueue
```
)
Update MSIX manifest from UWP format to Windows App SDK format
Migrate capabilities -- review and update capability declarations
Update NuGet packages to Windows App SDK-compatible versions
Test Windows integration -- notifications, background tasks, file associations may behave differently

UWP .NET 9 preview path: Microsoft announced UWP support on .NET 9 as a preview. If full WinUI 3 migration is too costly, this allows UWP apps to use modern .NET runtime features without migrating the UI framework.

For WinUI 3 development patterns, see [skill:dotnet-winui].

使用Windows App SDK模板创建新的WinUI 3项目
复制源文件并更新命名空间（将
```
Windows.UI.Xaml
```
改为
```
Microsoft.UI.Xaml
```
）
替换已弃用的API（将
```
Window.Current
```
改为手动跟踪，
```
CoreDispatcher
```
改为
```
DispatcherQueue
```
）
将UWP格式的MSIX清单更新为Windows App SDK格式
迁移权限声明——审核并更新权限声明
将NuGet包更新为兼容Windows App SDK的版本
测试Windows集成功能——通知、后台任务、文件关联的行为可能有所不同

UWP .NET 9预览版路径：微软宣布在.NET 9预览版中支持UWP，如果完整WinUI 3迁移成本过高，此方案可让UWP应用使用现代.NET运行时功能而无需迁移UI框架。

关于WinUI 3开发模式，详见[skill:dotnet-winui]。

UWP to Uno Platform

UWP迁移至Uno Platform

When cross-platform reach is needed from a UWP codebase. Uno Platform implements the WinUI XAML API surface, making it the most natural cross-platform migration path for UWP.

Since Uno Platform uses the same WinUI XAML API surface that UWP XAML is based on, much of the UWP code transfers with fewer changes than migrating to other cross-platform frameworks:

XAML files often work with minimal changes (Uno supports
```
x:Bind
```
,
```
x:Load
```
, etc.)
ViewModels and services transfer directly (platform-independent code)
Windows-specific APIs need cross-platform alternatives for non-Windows targets

当你需要从UWP代码库扩展至跨平台时选择此迁移路径。Uno Platform实现了WinUI XAML API界面，是UWP最自然的跨平台迁移路径。

由于Uno Platform使用与UWP XAML基于的WinUI XAML API界面相同，大部分UWP代码可直接迁移，相较于迁移至其他跨平台框架，所需更改更少：

XAML文件通常只需少量修改即可使用（Uno支持
```
x:Bind
```
、
```
x:Load
```
等）
视图模型和服务可直接迁移（平台无关代码）
Windows专属API需要为非Windows平台提供跨平台替代方案

Key Considerations

关键考量

Platform-specific code using
```
Windows.*
```
APIs needs conditional compilation or abstraction for non-Windows targets
WinRT APIs (sensors, geolocation, media capture) need Uno implementations or platform-specific alternatives
MSIX packaging is Windows-only -- other platforms use their native distribution mechanisms

For Uno Platform development patterns, see [skill:dotnet-uno-platform]. For per-target deployment, see [skill:dotnet-uno-targets].

使用
```
Windows.*
```
API的平台特定代码需要通过条件编译或抽象层适配非Windows平台
WinRT API（传感器、地理位置、媒体捕获）需要Uno实现或平台特定替代方案
MSIX打包仅适用于Windows平台——其他平台使用各自的原生分发机制

关于Uno Platform开发模式，详见[skill:dotnet-uno-platform]。关于各目标平台的部署，详见[skill:dotnet-uno-targets]。

Decision Matrix

决策矩阵

Use this matrix when deciding which migration path to take. The right choice depends on your specific constraints -- there is no universal "best" migration target.

使用此矩阵选择合适的迁移路径，正确选择取决于你的具体约束条件——不存在通用的“最佳”迁移目标。

By Primary Goal

按主要目标选择

Goal	Recommended Path	Alternative
Lowest risk, fastest migration	WPF/WinForms to .NET 8+	--
Modern Windows UI	WPF to WinUI 3	WPF .NET 9+ with Fluent theme
Cross-platform from Windows app	WPF to Uno Platform	Rewrite critical paths in Blazor
Cross-platform from UWP	UWP to Uno Platform	UWP to WinUI 3 (stay Windows-only)
UWP modernization (Windows-only)	UWP to WinUI 3	UWP on .NET 9 preview
Legacy WinForms modernization	WinForms to .NET 8+	Gradual rewrite in Blazor or WPF

目标	推荐路径	替代方案
风险最低、迁移速度最快	WPF/WinForms迁移至.NET 8+	--
现代化Windows UI	WPF迁移至WinUI 3	WPF .NET 9+搭配Fluent主题
从Windows应用扩展至跨平台	WPF迁移至Uno Platform	重写关键路径为Blazor
从UWP扩展至跨平台	UWP迁移至Uno Platform	UWP迁移至WinUI 3（仅限Windows平台）
UWP现代化（仅限Windows平台）	UWP迁移至WinUI 3	UWP .NET 9预览版
旧版WinForms现代化	WinForms迁移至.NET 8+	逐步重写为Blazor或WPF

By Constraint

按约束条件选择

Constraint	Best Path	Rationale
Limited budget/time	.NET 8+ migration (same framework)	Lowest effort, same codebase
Must stay Windows-only	WinUI 3 or WPF .NET 8+	WinUI for modern UI; WPF for minimal change
Must go cross-platform	Uno Platform	Broadest reach with WinUI XAML surface
Large existing WPF codebase	WPF .NET 8+ first, then evaluate	Stabilize on modern runtime before UI rewrite
Existing UWP codebase	WinUI 3 (Windows) or Uno (cross-platform)	Closest API surface to existing code
Team has web skills	Blazor (rewrite)	Leverage web expertise for desktop/mobile

约束条件	最佳路径	理由
预算/时间有限	.NET 8+迁移（同一框架）	工作量最低，代码库保持不变
必须仅限Windows平台	WinUI 3或WPF .NET 8+	WinUI用于现代化UI；WPF用于最小化变更
必须支持跨平台	Uno Platform	通过WinUI XAML界面实现最广泛的平台覆盖
现有WPF代码库庞大	先迁移至WPF .NET 8+，再评估后续方案	在现代化运行时上稳定后，再考虑UI重写
现有UWP代码库	WinUI 3（Windows）或Uno（跨平台）	与现有代码的API界面最接近
团队具备Web开发技能	Blazor（重写）	利用Web经验开发桌面/移动端应用

Staged Migration Strategy

分阶段迁移策略

For large applications, a staged approach reduces risk:

Stage 1: Runtime migration -- Move from .NET Framework to .NET 8+ (same UI framework). Validates compatibility, gains performance, enables modern NuGet packages.
Stage 2: Modernize patterns -- Adopt Host builder, DI, MVVM Toolkit, modern C#. See [skill:dotnet-wpf-modern] or [skill:dotnet-winforms-basics].
Stage 3: UI migration (if needed) -- Migrate to WinUI 3, Uno Platform, or Blazor based on requirements. Only pursue if Stage 1 and 2 are stable.

This approach avoids the "big bang" rewrite risk and delivers incremental value at each stage.

对于大型应用，分阶段迁移可降低风险：

第一阶段：运行时迁移——从.NET Framework迁移至.NET 8+（同一UI框架）。验证兼容性，提升性能，启用现代NuGet包。
第二阶段：模式现代化——采用Host构建器、DI、MVVM Toolkit、现代C#。详见[skill:dotnet-wpf-modern]或[skill:dotnet-winforms-basics]。
第三阶段：UI迁移（如有需要）——根据需求迁移至WinUI 3、Uno Platform或Blazor。仅在第一、二阶段稳定后再进行。

此方法避免了“大爆炸式”重写的风险，且每个阶段都能带来增量价值。

Agent Gotchas

注意事项

Do not recommend a single migration target as "the right choice" without understanding constraints. Always present options with trade-offs. Budget, timeline, team expertise, and platform requirements all affect the decision.
Do not skip the .NET 8+ runtime migration before suggesting a UI framework change. Moving from .NET Framework to .NET 8+ (same UI framework) should be Stage 1. A WPF-to-WinUI migration from .NET Framework is significantly harder than from .NET 8+.
Do not assume WPF is "legacy" and must be migrated away. WPF on .NET 8+ is actively maintained with new features (Fluent theme in .NET 9+, performance improvements). Many applications are well-served by staying on WPF.
Do not use
dotnet-upgrade-assistant
without running
analyze
first. Always analyze before upgrading to understand the scope of changes and potential issues.
Do not conflate WPF XAML with WinUI XAML. While concepts are similar, the API surfaces differ (
```
Window
```
,
```
DataContext
```
vs
```
x:Bind
```
,
```
NavigationView
```
patterns). Migration requires more than namespace changes.
Do not forget that UWP to WinUI 3 migration involves app model changes, not just namespace updates.
```
Window.Current
```
,
```
CoreDispatcher
```
,
```
CoreApplication
```
APIs are all replaced with different patterns.
Do not recommend Uno Platform for simple Windows-only apps. If the application does not need cross-platform reach, WinUI 3 or WPF .NET 8+ is simpler and has lower maintenance overhead.

不要在不了解约束条件的情况下，推荐单一迁移目标为“正确选择”。始终提供包含取舍的选项，预算、时间线、团队经验和平台需求都会影响决策。
在建议更改UI框架之前，不要跳过.NET 8+运行时迁移。从.NET Framework迁移至.NET 8+（同一UI框架）应作为第一阶段。直接从.NET Framework进行WPF到WinUI的迁移比从.NET 8+迁移难度大得多。
不要认为WPF是“ legacy”技术而必须迁移。.NET 8+上的WPF仍在积极维护，且具备新功能（.NET 9+中的Fluent主题、性能改进）。许多应用继续使用WPF即可满足需求。
不要在未运行
analyze
的情况下使用
dotnet-upgrade-assistant
。升级前务必先分析，以了解变更范围和潜在问题。
不要混淆WPF XAML和WinUI XAML。虽然概念相似，但API界面有所不同（
```
Window
```
、
```
DataContext
```
vs
```
x:Bind
```
、
```
NavigationView
```
模式）。迁移不仅仅是更改命名空间。
不要忘记UWP到WinUI 3的迁移涉及应用模型变更，而非仅命名空间更新。
```
Window.Current
```
、
```
CoreDispatcher
```
、
```
CoreApplication
```
等API都被不同的模式替代。
不要为简单的Windows-only应用推荐Uno Platform。如果应用不需要跨平台支持，WinUI 3或WPF .NET 8+更简单，维护开销更低。