数据库迁移
- 作者仓库星标 133,756
- 许可证 Complete terms in LICENSE.txt
- 作者更新于 实时读取
- 作者仓库 PowerToys
- 领域
- 工程开发
- 兼容 Agent
-
- Claude Code
- Cursor
- Cline
- Codex
- Windsurf
- Gemini CLI
- +20
- 信任分
- 94 / 100 · 已通过审计
- 作者 / 版本 / 许可
- @microsoft · Complete terms in LICENSE.txt
- Token 消耗评级
- 低消耗
- 接入复杂程度
- 需简单配置
- 是否需要外部 API Key
- 不需要
- 兼容的系统
- Windows
- 底层运行要求
- 无特殊要求
- 文件与系统权限
-
- 只读
- 允许写入 / 修改
- Shell 执行
- 网络行为
- 仅限本地
- 安装命令数
- 26 条
档案由构建时根据 SKILL.md 与安装命令自动衍生，可能与作者实际意图存在差异。
需要注意： 未限定 allowed-tools，默认拥有全部工具权限。
---
name: wpf-to-winui3-migration
description: Guide for migrating PowerToys modules from WPF to WinUI 3 (Windows App SDK). Use when asked to m…
category: 工程开发
runtime: 无特殊运行时
---
# wpf-to-winui3-migration 输出预览
## PART A: 任务判断
- 适用问题：代码实现、重构、调试或代码审查。
- 输入要求：目标材料、限制条件、期望输出和验收方式。
- 证据边界：围绕“When to Use This Skill / Prerequisites / Migration Strategy”读取原文规则，不把推断写成作者承诺。
## PART B: 执行结果
- **01** 任务判断：确认你的需求是否属于代码实现、重构、调试或代码审查，并标出输入、限制和预期结果。
- **02** 执行计划：优先按“When to Use This Skill / Prerequisites / Migration Strategy”拆成步骤，说明每一步会读取什么、修改什么、产出什么。
- **03** 交付结果：给出可复制的命令、文件改动、检查清单或内容草稿，并说明如何继续迭代。
- **04** 风险边界：结合 读取文件、写入/修改文件、执行终端命令、主要在本地完成、通常不需要额外 API Key 给出执行前确认项。
## Running Rules
- 读取文件、写入/修改文件、执行终端命令；主要在本地完成；通常不需要额外 API Key。
- 先小样例验证，再放大到真实任务。
- 交付时同时给结果、检查口径和下一步迭代建议。 先确认触发方式
原文没有稳定的斜杠命令要求。安装验证后通常全局生效，直接在对话里点名这个 Skill 并描述任务即可。
给清楚输入和边界
告诉 Agent 目标文件或材料、期望结果、不可改范围、是否允许联网或执行命令。本 Skill 的权限画像是：读取文件、写入/修改文件、执行终端命令。
小样例验证后再放大
先用一个小任务确认它会围绕“When to Use This Skill / Prerequisites / Migration Strategy”工作；涉及文件或命令时，先看 diff、日志、预览或测试结果。
复核后再交付
检查最终产物是否包含明确结果、必要证据和下一步动作；如果输出泛泛而谈，就补充输入、边界和验收标准后重跑。
---
name: wpf-to-winui3-migration
description: Guide for migrating PowerToys modules from WPF to WinUI 3 (Windows App SDK). Use when asked to m…
category: 工程开发
source: microsoft/PowerToys
---
# wpf-to-winui3-migration
## 什么时候使用
- 把工程方向的常用动作沉淀成 Agent 可调用的技能 适合处理工程开发场景下的代码实现、调试、重构、测试或代码审查，核心价值是把输入、判断、执行、验证和交付边界固定下来，避免 Agent 泛泛回答。 把任务拆成可执行、可检查、可继续迭代…
- 面向代码实现、重构、调试或代码审查，优先处理能明确输入、步骤和验收标准的工作。
## 需要提供什么
- 目标材料、目录范围、期望结果和不可改动内容。
- 是否允许联网、执行命令、读写文件或调用外部服务。
## 执行规则
- 围绕「When to Use This Skill / Prerequisites / Migration Strategy」组织步骤，不把推断写成作者事实。
- 读取文件、写入/修改文件、执行终端命令；主要在本地完成；通常不需要额外 API Key。
- 先跑小样例，确认结果可检查后再扩大任务范围。
## 输出要求
- 给出最终产物、关键证据、验证方式和下一步动作。
- 信息不足时标记 unknown，不编造命令、平台或依赖。 证据边界与执行链路
作者原文负责流程事实；仓库文件负责来源和命令；流狐只补充适用场景、限制和质量判断。
skill "wpf-to-winui3-migration" {
输入层 -> 用户目标 + 目标文件 + 禁止范围 + 验收标准
上下文层 -> When to Use This Skill / Prerequisites / Migration Strategy
规则层 -> SKILL.md 触发条件 / 执行顺序 / 输出格式
运行层 -> 无特殊运行时 | 读取文件、写入/修改文件、执行终端命令 | 主要在本地完成
安全层 -> 通常不需要额外 API Key + 小任务验证 + diff / 日志复核
输出层 -> 可复制结果 + 检查清单 + 下一步迭代
}WPF to WinUI 3 Migration Skill
Migrate PowerToys modules from WPF (System.Windows.*) to WinUI 3 (Microsoft.UI.Xaml.* / Windows App SDK). Based on patterns validated in the ImageResizer module migration.
When to Use This Skill
- Migrate a PowerToys module from WPF to WinUI 3
- Convert WPF XAML files to WinUI 3 XAML
- Replace
System.Windowsnamespaces withMicrosoft.UI.Xaml - Migrate
Dispatcherusage toDispatcherQueue - Migrate custom
Observable/RelayCommandto CommunityToolkit.Mvvm source generators - Replace WPF-UI (Lepo) controls with native WinUI 3 controls
- Convert imaging code from
System.Windows.Media.ImagingtoWindows.Graphics.Imaging - Handle WPF
Windowvs WinUIWindowdifferences (sizing, positioning, SizeToContent) - Migrate resource files from
.resxto.reswwithResourceLoader - Fix installer/build pipeline issues after WinUI 3 migration
- Update project files, NuGet packages, and signing config
Prerequisites
- Visual Studio 2022 17.4+
- Windows App SDK NuGet package (
Microsoft.WindowsAppSDK) - .NET 8+ with
net8.0-windows10.0.19041.0TFM - Windows 10 1803+ (April 2018 Update or newer)
Migration Strategy
Recommended Order
- Project file — Update TFM, NuGet packages, set
<UseWinUI>true</UseWinUI> - Data models and business logic — No UI dependencies, migrate first
- MVVM framework — Replace custom Observable/RelayCommand with CommunityToolkit.Mvvm
- Resource strings — Migrate
.resx→.resw, introduceResourceLoaderInstance - Services and utilities — Replace
System.Windowstypes, async-ify imaging code - ViewModels — Update Dispatcher usage, binding patterns
- Views/Pages — Starting from leaf pages with fewest dependencies
- Main page / shell — Last, since it depends on everything
- App.xaml / startup code — Merge carefully (do NOT overwrite WinUI 3 boilerplate)
- Installer & build pipeline — Update WiX, signing, build events
- Tests — Adapt for WinUI 3 runtime, async patterns
Key Principles
- Do NOT overwrite
App.xaml/App.xaml.cs— WinUI 3 has different application lifecycle boilerplate. Merge your resources and initialization code into the generated WinUI 3 App class. - Do NOT create Exe→WinExe
ProjectReference— Extract shared code to a Library project. This causes phantom build artifacts. - Use
Lazy<T>for resource-dependent statics —ResourceLoaderis not available at class-load time in all contexts.
Quick Reference Tables
Namespace Mapping
| WPF | WinUI 3 |
|---|---|
System.Windows |
Microsoft.UI.Xaml |
System.Windows.Controls |
Microsoft.UI.Xaml.Controls |
System.Windows.Media |
Microsoft.UI.Xaml.Media |
System.Windows.Media.Imaging |
Microsoft.UI.Xaml.Media.Imaging (UI) / Windows.Graphics.Imaging (processing) |
System.Windows.Input |
Microsoft.UI.Xaml.Input |
System.Windows.Data |
Microsoft.UI.Xaml.Data |
System.Windows.Threading |
Microsoft.UI.Dispatching |
System.Windows.Interop |
WinRT.Interop |
Critical API Replacements
| WPF | WinUI 3 | Notes |
|---|---|---|
Dispatcher.Invoke() |
DispatcherQueue.TryEnqueue() |
Different return type (bool) |
Dispatcher.CheckAccess() |
DispatcherQueue.HasThreadAccess |
Property vs method |
Application.Current.Dispatcher |
Store DispatcherQueue in static field |
See Threading |
MessageBox.Show() |
ContentDialog |
Must set XamlRoot |
DynamicResource |
ThemeResource |
Theme-reactive only |
clr-namespace: |
using: |
XAML namespace prefix |
{x:Static props:Resources.Key} |
x:Uid or ResourceLoader.GetString() |
.resx → .resw |
DataType="{x:Type m:Foo}" |
Remove or use code-behind | x:Type not supported |
Properties.Resources.MyString |
ResourceLoaderInstance.ResourceLoader.GetString("MyString") |
Lazy-init pattern |
Application.Current.MainWindow |
Custom App.Window static property |
Must track manually |
SizeToContent="Height" |
Custom SizeToContent() via AppWindow.Resize() |
See Windowing |
MouseLeftButtonDown |
PointerPressed |
Mouse → Pointer events |
Pack URI (pack://...) |
ms-appx:/// |
Resource URI scheme |
Observable (custom base) |
ObservableObject + [ObservableProperty] |
CommunityToolkit.Mvvm |
RelayCommand (custom) |
[RelayCommand] source generator |
CommunityToolkit.Mvvm |
JpegBitmapEncoder |
BitmapEncoder.CreateAsync(JpegEncoderId, stream) |
Async, unified API |
encoder.QualityLevel = 85 |
BitmapPropertySet { "ImageQuality", 0.85f } |
int 1-100 → float 0-1 |
NuGet Package Migration
| WPF | WinUI 3 |
|---|---|
Microsoft.Xaml.Behaviors.Wpf |
Microsoft.Xaml.Behaviors.WinUI.Managed |
WPF-UI (Lepo) |
Remove — use native WinUI 3 controls |
CommunityToolkit.Mvvm |
CommunityToolkit.Mvvm (same) |
Microsoft.Toolkit.Wpf.* |
CommunityToolkit.WinUI.* |
| (none) | Microsoft.WindowsAppSDK |
| (none) | Microsoft.Windows.SDK.BuildTools |
| (none) | WinUIEx (optional, for window helpers) |
| (none) | CommunityToolkit.WinUI.Converters |
XAML Syntax Changes
| WPF | WinUI 3 |
|---|---|
xmlns:local="clr-namespace:MyApp" |
xmlns:local="using:MyApp" |
{DynamicResource Key} |
{ThemeResource Key} |
{x:Static Type.Member} |
{x:Bind} or code-behind |
{x:Type local:MyType} |
Not supported |
<Style.Triggers> / <DataTrigger> |
VisualStateManager |
{Binding} in Setter.Value |
Not supported — use StaticResource |
Content="{x:Static p:Resources.Cancel}" |
x:Uid="Cancel" with .Content in .resw |
<ui:FluentWindow> / <ui:Button> (WPF-UI) |
Native <Window> / <Button> |
<ui:NumberBox> / <ui:ProgressRing> (WPF-UI) |
Native <NumberBox> / <ProgressRing> |
BasedOn="{StaticResource {x:Type ui:Button}}" |
BasedOn="{StaticResource DefaultButtonStyle}" |
IsDefault="True" / IsCancel="True" |
Style="{StaticResource AccentButtonStyle}" / handle via KeyDown |
<AccessText> |
Not available — use AccessKey property |
<behaviors:Interaction.Triggers> |
Migrate to code-behind or WinUI behaviors |
Detailed Reference Docs
Read only the section relevant to your current task:
- Namespace and API Mapping — Full type mapping, NuGet changes, project file, CsWinRT interop
- XAML Migration Guide — XAML syntax, WPF-UI removal, markup extensions, styles, resources, data binding
- Threading and Window Management — Dispatcher, DispatcherQueue, SizeToContent, AppWindow, HWND interop, custom entry point
- Imaging API Migration — BitmapEncoder/Decoder, SoftwareBitmap, CodecHelper, async patterns, int→uint
- PowerToys-Specific Patterns — MVVM migration, ResourceLoader, Lazy init, installer, signing, test adaptation, build pipeline
Common Pitfalls (from ImageResizer migration)
| Pitfall | Solution |
|---|---|
ContentDialog throws "does not have a XamlRoot" |
Set dialog.XamlRoot = this.Content.XamlRoot before ShowAsync() |
FilePicker throws error in desktop app |
Call WinRT.Interop.InitializeWithWindow.Initialize(picker, hwnd) |
Window.Dispatcher returns null |
Use Window.DispatcherQueue instead |
Resources on Window element not found |
Move resources to root layout container (Grid.Resources) |
VisualStateManager on Window fails |
Use UserControl or Page inside the Window |
Satellite assembly installer errors (WIX0103) |
Remove .resources.dll refs from Resources.wxs; WinUI 3 uses .pri |
Phantom .exe/.deps.json in root output dir |
Avoid Exe→WinExe ProjectReference; use Library project |
ResourceLoader crash at static init |
Wrap in Lazy<T> or null-coalescing property — see Lazy Init |
SizeToContent not available |
Implement manual content measurement + AppWindow.Resize() with DPI scaling |
x:Bind default mode is OneTime |
Explicitly set Mode=OneWay or Mode=TwoWay |
DynamicResource / x:Static not compiling |
Replace with ThemeResource / ResourceLoader or x:Uid |
IValueConverter.Convert signature mismatch |
Last param: CultureInfo → string (language tag) |
| Test project can't resolve WPF types | Add <UseWPF>true</UseWPF> temporarily; remove after imaging migration |
Pixel dimension type mismatch (int vs uint) |
WinRT uses uint for pixel sizes — add u suffix in test assertions |
$(SolutionDir) empty in standalone project build |
Use $(MSBuildThisFileDirectory) with relative paths instead |
| JPEG quality value wrong after migration | WPF: int 1-100; WinRT: float 0.0-1.0 |
| MSIX packaging fails in PreBuildEvent | Move to PostBuildEvent; artifacts not ready at PreBuild time |
| RC file icon path with forward slashes | Use double-backslash escaping: ..\\ui\\Assets\\icon.ico |
Troubleshooting
| Issue | Solution |
|---|---|
| Build fails after namespace rename | Check for lingering System.Windows usings; some types have no direct equivalent |
Missing PresentationCore.dll at runtime |
Ensure ALL imaging code uses Windows.Graphics.Imaging, not System.Windows.Media.Imaging |
DataContext not working on Window |
WinUI 3 Window is not a DependencyObject; use a root Page or UserControl |
| XAML designer not available | WinUI 3 does not support XAML Designer; use Hot Reload instead |
| NuGet restore failures | Run build-essentials.cmd after adding Microsoft.WindowsAppSDK package |
Parallel.ForEach compilation error |
Migrate to Parallel.ForEachAsync for async imaging operations |
| Signing check fails on leaked artifacts | Run generateAllFileComponents.ps1; verify only WinUI3Apps\\ paths in signing config |
先判断是否适合
作者设计意图
作者的方法与取舍
边界和复核