用途
winui-code-review 是一个代码审查技能,适用于 WinUI 3 应用在构建成功之后、提交代码之前的质量检查。它关注那些不会导致编译失败、也不一定在 UI 测试中暴露的问题——能编译、能运行,但写法错误、脆弱或性能不佳的模式。
主要能力
审查按以下维度组织检查项:
- MVVM 规范:ViewModel 应继承 ObservableObject 并使用 [ObservableProperty] 分部属性(而非字段);命令使用 [RelayCommand] 特性而非手写 ICommand;ViewModel 中不出现 UI 类型(如 SolidColorBrush、Visibility、BitmapImage);code-behind 不含业务逻辑;异步方法使用 async Task,async void 仅用于事件处理;不替换 ObservableCollection<T>。
- x:Bind 与数据绑定:使用 {x:Bind} 而非 {Binding};显式设置 Mode=OneWay 或 TwoWay;每个 DataTemplate 设置 x:DataType;嵌套可空路径需提供 FallbackValue;命令绑定可用 OneTime。
- 可访问性:交互控件设置 AutomationProperties.AutomationId;仅图标按钮设置 AutomationProperties.Name;使用语义化控件而非可点击 Border/TextBlock;不单靠颜色传达信息。
- 主题:颜色使用 {ThemeResource} 画刷;排版使用内置文本样式;间距使用 4px 网格倍数;圆角使用 ControlCornerRadius / OverlayCornerRadius;样式引用使用 {StaticResource}。
- 安全:源码中不含密钥、API Key 或令牌;不对外部输入直接调用 Process.Start;外部输入先校验;用户输入路径不直接用于 File.Delete / File.WriteAllText。
- 性能:长列表使用虚拟化的 ListView/GridView;不常显示的内容使用 x:Load;重任务通过 Task.Run 或 async/await 移出 UI 线程;避免 .Result / .Wait() / .GetAwaiter().GetResult();可释放对象使用 using。
- 全球化:面向用户的字符串使用 x:Uid 和 ResourceLoader;字符串资源放在 Strings/en-us/Resources.resw;日期数字使用 CultureInfo.CurrentCulture;布局支持 RTL;不拼接用户消息字符串。
分析器
技能附带的 Microsoft.WindowsAppSDK.Analyzers Roslyn 分析器通过 winui-dev-workflow 技能注入构建:使用其 BuildAndRun.ps1 脚本编译时,脚本会在项目中放置临时 Directory.Build.props 加载分析器 DLL 与 .targets,构建后清理。普通 dotnet build 或 Visual Studio 不会自动加载该分析器;如需在脚本之外作为构建诊断出现,需在自己的 Directory.Build.props 中添加 <Analyzer Include="..." /> 和 <Import Project="..." />(或等待计划中的 NuGet 包)。
分析器按四位 ID 分类诊断:
- WUI0xxx — UWP → WinUI 3 API 兼容性(UwpXamlNamespace、Window.Current、CoreDispatcher、GetForCurrentView)
- WUI1xxx — 迁移表数据驱动提示(UWP API 是否有 WinAppSDK 等价物等)
- WUI2xxx — 运行时 / 布局 / XAML 陷阱(原始 TabView 内容、无回退的嵌套 x:Bind、缺少 Mode 的 x:Bind、null Converter、缺少 AutomationId、附加属性语法)
- WUI3xxx — MVVM 模式(旧的 [ObservableProperty] 字段语法)
- WUI4xxx — 互操作(WebView2 未初始化、移除的 ONNX Runtime GenAI API WUI4101-WUI4103)
所有诊断均为 Warning 严重级别(无 Error 规则),并带 helpLinkUri。可用 #pragma warning disable WUIxxxx 或 <NoWarn> 抑制。
使用方式
审阅项目的 XAML 与 C# 文件,逐项对照上述检查清单;完成后汇总审查报告,包括:发现的问题(文件、行号、问题描述)、严重程度(Error 必须修复 / Warning 应当修复 / Note 可改进)以及每项问题的具体修复建议。references/quality-rules.md 提供带代码示例的详细规则,涵盖性能深入(x:Phase、布局优化)、安全(PasswordVault、DPAPI、WebView2 加固)、可访问性(键盘导航、屏幕阅读器)、代码质量(.editorconfig、命名)和全球化(x:Uid 模式、RTL、复数化)。
适用场景
适用于 WinUI 3 / Windows App SDK 桌面应用的日常代码审查与提交前自检,帮助团队在构建通过之后进一步发现规范性、可访问性、性能和安全隐患。
限制
分析器需通过特定脚本或手动配置项目文件才能启用,普通构建不会自动加载;资料未提供安装命令、版本要求、收费信息或与其他工具集成的更多细节,这些内容暂未提供。