winui-code-review

何时使用

在应用成功生成后、提交前运行代码审查。这样可以发现构建错误和 UI 测试无法发现的质量问题——也就是那些能够编译和运行，却存在错误、脆弱或缓慢模式的问题。

如何审查

阅读项目的 XAML 和 C# 文件，并检查下面的每个部分。有关分析器的设置，请参阅 winui-dev-workflow；如果尚未安装，请告知用户这些检查未运行。

报告 API 不匹配或建议替代方案之前，请通过 CLI 0.7+ 的 winapp find-api，根据已还原的应用项目的引用进行验证，例如 winapp find-api members NavigationView --filter selected --json --project-dir <app-project-dir>。批量属性检查和项目选择请参阅 winui-design；机器 SDK 的结果不能证明应用程序包中有相应 API。

分析器会检查一组经过筛选的 WinUI 3 / Windows App SDK 问题，并使用按类别划分的 4 位 ID：

• WUI0xxx — UWP → WinUI 3 API 兼容性（UwpXamlNamespace、Window.Current、CoreDispatcher、GetForCurrentView）
• WUI1xxx — 基于迁移表的数据驱动提示（UWP API 有对应的 WinAppSDK API、没有对应 API、功能领域提示）
• WUI2xxx — 运行时 / 布局 / XAML 陷阱（原始 TabView 内容、可空绑定路径、无效的绑定模式、空 Converter、缺少 AutomationId、附加属性语法）
• WUI3xxx — MVVM 模式（旧式 [ObservableProperty] 字段语法）
• WUI4xxx — 互操作（WebView2 未初始化、已移除的 ONNX Runtime GenAI API WUI4101-WUI4103）

规则详情请使用已安装包中的诊断帮助链接。将未指定模式视为缺陷之前，请检查继承的 x:DefaultBindMode 以及事件 / 命令 / 转换器例外情况。修复根本原因；任何合理的误报抑制都必须范围狭窄且有文档说明，不要一概使用 NoWarn。同时保持启用 IL/CsWinRT 警告；WinUI 分析器不能替代 AOT/修剪分析。

MVVM 合规性

• ViewModel 继承 ObservableObject，使用 [ObservableProperty] 部分属性（而不是字段）
• 命令使用 [RelayCommand] 特性，而不是手动实现 ICommand
• ViewModel 中不包含 UI 类型（SolidColorBrush、Visibility、BitmapImage）——这些应放在转换器或 XAML 中
• 后台代码中不包含业务逻辑——仅处理导航、对话框协调和事件连接
• 异步方法使用 async Task，仅事件处理程序使用 async void
• 不要替换 ObservableCollection<T>——使用 .Clear() 后重新添加

x:Bind 和数据绑定

• 对已知源类型优先使用 {x:Bind}；运行时 {Binding} 需要有合理的源，并且在 AOT 场景下需要生成的属性提供程序
• 动态值使用有效的 OneWay/TwoWay 模式（显式指定或继承 x:DefaultBindMode），并实现更改通知；不要为了满足一刀切的模式规则而改写稳定的事件 / 命令 / 转换器绑定
• 使用编译型 x:Bind 的 DataTemplate 上应有 x:DataType，而不是在 Page 上
• 嵌套的可空路径（例如 ViewModel.Selected.Name）必须设置 FallbackValue

原生 AOT / 修剪（适用时）

• 已测试发布的构件（Release JIT 运行不算 AOT 验证），并修复而非抑制 IL/CsWinRT 警告
• 跨越 ABI 的类型为 partial；JSON 和运行时绑定使用源代码生成——参阅 winui-packaging 中的 references/sourcegen-patterns.md

无障碍

• 每个可交互控件（Button、TextBox、ComboBox、ToggleSwitch、ListView、NavigationViewItem）都设置了 AutomationProperties.AutomationId
• 仅含图标的按钮和没有可见文本的控件设置了 AutomationProperties.Name
• 使用语义控件（Button、HyperlinkButton），而不是可点击的 Border/TextBlock
• 不要仅通过颜色传达信息

主题

• 所有颜色都使用 {ThemeResource} 画刷——不使用硬编码的 #FF0000 或 Color="Blue"
• 排版使用内置样式（TitleTextBlockStyle、SubtitleTextBlockStyle、BodyTextBlockStyle、CaptionTextBlockStyle）——不使用原始 FontSize
• 间距使用 4px 网格的倍数（4、8、12、16、24、32、48）
• 圆角使用 ControlCornerRadius / OverlayCornerRadius——不使用硬编码值
• 样式使用 {StaticResource} 引用，而非 {ThemeResource}（画刷的使用位置除外）

安全性

• 源代码中没有机密信息、API 密钥或令牌
• 不使用未经清理的用户输入调用 Process.Start
• 使用外部输入前先进行验证和清理
• 未经验证，不直接将来自用户输入的文件路径用于 File.Delete / File.WriteAllText

性能

• 长列表或动态列表使用 ListView / GridView（虚拟化），而非使用 foreach 的 StackPanel
• 对并非始终可见的内容（例如对话框、辅助面板）使用 x:Load
• 通过 Task.Run 或 async/await 将繁重工作移出 UI 线程——绝不阻塞 UI
• 不使用 .Result / .Wait() / .GetAwaiter().GetResult()——这些会导致 UI 线程死锁
• 对所有可释放对象使用 using 语句（Model、Tokenizer、InferenceSession、Generator）

全球化

• 面向用户的字符串在 XAML 中使用 x:Uid，在 C# 中使用 ResourceLoader——不使用硬编码字符串
• 字符串资源放在 Strings/en-us/Resources.resw 中（而非 .resx）
• 日期/数字格式使用 CultureInfo.CurrentCulture——不使用硬编码格式
• 布局支持 RTL（FlowDirection 从根元素继承，不使用会在 RTL 下错位的绝对定位）
• 面向用户的消息不使用字符串拼接——使用 string.Format，或使用资源字符串进行插值

审查报告

审查后，请总结：

1. 发现的问题： 列出每项问题，并注明文件、行号和具体问题
2. 严重程度： Error（必须修复）、Warning（应该修复）或 Note（可以改进）
3. 建议的修复方案： 针对每项问题给出具体的代码更改

参考资料

详细规则和代码示例请参阅 references/quality-rules.md——其中涵盖深入的性能分析（x:Phase、布局优化）、安全性（PasswordVault、DPAPI、WebView2 加固）、无障碍功能（键盘导航、屏幕阅读器）、代码质量（.editorconfig、命名）以及全球化（x:Uid 模式、RTL、复数形式）。