PowerToys Settings V2 项目架构总览WinUI3、MVVM 与 Runner 通信的三层设计【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToysPowerToys 的设置界面Settings V2是一个基于 Windows App SDK 的 WinUI3 非打包Unpackaged.NET 桌面应用。本文基于仓库中 项目总览文档 展开逐层解析 Settings 工程的三部分构成——UI 组件层、视图模型/数据层、以及与主进程 Runner 的通信职责并结合src/settings-ui/下的实际工程文件说明 MVVM 分层在 PowerToys 中的落点、快捷键Hotkey逻辑所在位置以及设置应用被 Runner 拉起和终止的完整生命周期。一、Settings V2 是什么Windows App SDK WinUI3 Unpackaged 应用原总览文档对 Settings 的定义是一句话Settingsis Windows App Sdk WinUI3 .Net Unpackaged desktop application。这句话里包含三个关键技术选型均可在工程文件中得到印证选型含义仓库证据Windows App SDK使用微软面向 WinUI3 的跨打包/非打包开发 SDK而非传统的 UWP/Win32 框架PowerToys.Settings.csproj 中引用Microsoft.WindowsAppSDKWinUI3UI 用 XAML WinUI 控件描述C# 编写视图模型同上csproj 中UseWinUItrue/UseWinUI.Net Unpackaged.NET 桌面应用形态不使用 MSIX 打包以散文件方式随 PowerToys 安装目录分发csproj 中WindowsPackageTypeNone/WindowsPackageType此外csproj 中WindowsAppSDKSelfContainedtrue/WindowsAppSDKSelfContained表明运行时随应用自带self-contained配合OutputPath$(RepoRoot)$(Platform)\$(Configuration)\WinUI3Apps/OutputPath可以看到Settings 的构建产物统一输出到解决方案输出目录下的WinUI3Apps子目录由安装器installer/下的Settings.wxs与 PowerToys 主体一起打包分发。从依赖列表还能看到两个对理解架构很重要的引用csprojStreamJsonRpc用于进程间 RPC 通信的 NuGet 包是 Settings 与 Runner 之间 IPC 的基础设施CommunityToolkit.WinUI.*系列WinUI3 社区工具包提供设置页常用控件如 SettingsExpander、Segmented 等。二、工程结构总览三部分构成与 MVVM 分层总览文档 的核心内容是 Settings V2 的工程结构。文档指出该工程遵循MVVM 架构模式图形界面与视图模型分离并将工程划分为三个部分src/settings-ui/ ├── Settings.UI/ # ① UI 组件Views/XAML ③ Settings Runner 进程宿主 │ ├── SettingsXAML/ # 页面、控件、OOBE 引导窗口 │ └── ViewModels/ # ShellViewModel 与各模块 ViewModel ├── Settings.UI.Library/ # ② 数据模型/视图模型数据XSettings、XProperties ├── Settings.UI.Controls/ # 公共 UI 控件库 ├── Settings.UI.UnitTests/ # 单元测试 └── Settings.UITests/ # UI 自动化测试下面按文档的三个小节逐一展开并补充源码层面的细节。2.1 UI 组件src/settings-ui/Settings.UI/文档原文The UI Components are part of PowerToys.Settings project. It contains the xaml files for each of the UI components. It also contains the Hotkey logic for the settings control.即 UI 组件属于PowerToys.Settings工程包含各 UI 组件的 XAML 文件同时包含设置界面中快捷键Hotkey控制相关的逻辑。从源码结构看这一描述对应如下布局Settings.UI/SettingsXAML/全部 XAML 页面与自定义控件包括各模块的设置页、标题栏Controls/TitleBar/、仪表盘组件Controls/Dashboard/、OOBE 首次运行引导OOBE/Settings.UI/ViewModels/MVVM 中的 ViewModel 层入口是 ShellViewModel页面基类为 PageViewModelBase并存在与每个 PowerToy 模块一一对应的 ViewModel如 FancyZonesViewModel、MouseWithoutBordersViewModel、ColorPickerViewModel、WorkspacesViewModel 等快捷键逻辑集中体现在ShortcutControl设置页中可按键捕获的快捷键输入控件GlobalHotkeyConflictManager 与 HotkeyConflictHelper当用户在界面中修改快捷键时检测全局快捷键冲突并弹窗提示对应仪表盘中的ShortcutConflictWindow组件快捷键被修改后的下发路径见 IPCResponseService它负责把界面变更通过 IPC 发给 Runner。2.2 视图模型数据src/settings-ui/Settings.UI.Library文档原文The Settings.UI.Library project contains the data that is to be rendered by the UI components.即 Library 工程存放供 UI 组件渲染的数据。它是纯 C# 类库是 MVVM 中 Model 与 ViewModel 绑定的数据契约层。从 目录内容 看其组织规律非常清晰每个模块都有成对的数据模型XxxSettings.cs模块的运行时状态开关、参数值例如AdvancedPasteSettings.cs、AwakeSettings.cs、ColorPickerSettings.csXxxProperties.cs模块的静态属性描述模块名、启用开关元数据等例如AwakeProperties.cs、CmdPalProperties.cs基础类型BasePTModuleSettings 是所有模块设置的基类BoolProperty.cs、DoubleProperty.cs等则是带默认值与序列化/反序列化能力的属性封装供 ViewModel 与配置文件之间做双向同步。这种Settings状态 Properties元数据的成对设计使得 UI 层无需关心 JSON 配置文件格式只需绑定 Library 暴露出的强类型属性即可。2.3 Settings Runner界面变更到 Runner 的通信中枢文档原文The function of the settings runner project is to communicate all changes that the user makes in the user interface, to the runner so that it can be dispatched and reflected in all the modules.注意这里settings runner指的是设置进程本身承担的职责把用户在界面做的每一次变更通信给 PowerToys 主进程Runner位于src/runner/由 Runner 统一分发给各个 PowerToy 模块并生效。这个进程的生命周期在 App.xaml.cs 中体现得最完整由 Runner 带参拉起。设置进程启动时接收 Runner 传入的一组命令行参数参数枚举 定义了全部 10 个位置参数参数含义PTPipeName/SettingsPipeName与 Runner 双向通信的两个命名管道名PTPidRunner 进程 PID存入App.PowerToysPIDTheme主题旧版设置的遗留参数ElevatedStatus/IsUserAdmin是否以管理员身份运行 / 用户是否为管理员影响部分模块可用性显示ShowOobeWindow/ShowScoobeWindow是否显示 OOBE首次配置/ SCOBE升级后引导窗口ContainsSettingsWindow是否打开设置主窗口建立 IPC 并注册回调。构造函数中初始化TwoWayPipeMessageIPCManaged来自PowerToys.Interop对应src/interop/工程Runner 侧发来的消息通过IPCMessageReceivedCallback回调注入 UI。等待 Runner 的终止信号。构造函数尾部调用NativeEventWaiter.WaitForEventLoop(Constants.PowerToysRunnerTerminateSettingsEvent(), ...)App.xaml.cs设置进程挂起等待一个 Windows 命名事件当主 Runner 释放该事件时设置进程清理 ETW Trace 后以退出码 0 结束。也就是说设置进程的生命周期完全受 Runner 管控——Runner 退出或需要重载设置时通过事件触发设置进程优雅退出。变更下发。用户修改任何开关或参数后对应模块的 ViewModel 经IPCResponseService将 JSON 形式的设置变更发送到 Runner 管道Runner 读取后更新powertoys_settings.json并通知各模块。这条链路的更细粒度文档见 Runner IPC 文档 与 模块通信文档。三、MVVM 在 Settings V2 中的落点总览文档 明确指出工程遵循 MVVMModel-View-ViewModel模式图形界面与视图模型分离。结合前面的源码结构可以把三层对应关系归纳为MVVM 角色代码位置说明View视图src/settings-ui/Settings.UI/SettingsXAML/XAML 页面 控件代码只负责呈现与用户输入ViewModelsrc/settings-ui/Settings.UI/ViewModels/ShellViewModel管理导航/页面生命周期各XxxViewModel暴露绑定属性与命令Model数据src/settings-ui/Settings.UI.Library/XxxSettings/XxxProperties强类型数据模型含序列化契约跨进程服务src/settings-ui/Settings.UI/Services/IPCResponseService等把 ViewModel 的变更序列化后经管道交给 RunnerShellViewModel作为导航壳实现见持有当前页面集合与导航状态每个模块页面都继承PageViewModelBase保证返回导航、页面标题、模块状态图标等行为一致。其可测性由 Settings.UI.UnitTests 中的单元测试覆盖例如ShellViewModelTests这从侧面印证了 View 与 ViewModel 确实解耦——测试无需启动 XAML 即可验证导航逻辑。四、进一步深入配套文档地图总览文档 是 Settings 系列文档的入口见 系列索引。读懂本篇后可按主题继续阅读同目录下的细化文档UI 架构窗口、导航、主题的完整设计ViewModels视图模型层的数据流约定Settings 实现配置读写与模块联动细节Runner IPC 与 模块通信进程间消息协议Hotkey 控制与键盘钩子快捷键捕获、全局钩子与冲突处理遥测、GPO 集成、DSC 配置、与旧版设置的兼容。五、小结PowerToys Settings V2 的本质是一个受 Runner 管控生命周期的 WinUI3 非打包应用技术栈Windows App SDK WinUI3 .NET Unpackagedself-contained 运行时随安装目录分发分层Settings.UIXAML 视图 ViewModel Hotkey 逻辑与Settings.UI.LibrarySettings/Properties 数据模型分离严格执行 MVVM通信进程由 Runner 带 10 个参数拉起通过StreamJsonRpc命名管道双向通信所有界面变更经IPCResponseService下发至 Runner再分发给各 PowerToy 模块进程退出则由 Runner 的命名事件触发优雅收尾。理解这套结构后无论是排查设置改不动、快捷键冲突提示异常还是为某个 PowerToy 模块新增设置页都能快速定位到对应的 ViewModel、数据模型与 IPC 服务文件。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 PowerToys Settings V2 项目架构总览：WinUI3、MVVM 与 Runner 通信的三层设计
PowerToys Settings V2 项目架构总览WinUI3、MVVM 与 Runner 通信的三层设计【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToysPowerToys 的设置界面Settings V2是一个基于 Windows App SDK 的 WinUI3 非打包Unpackaged.NET 桌面应用。本文基于仓库中 项目总览文档 展开逐层解析 Settings 工程的三部分构成——UI 组件层、视图模型/数据层、以及与主进程 Runner 的通信职责并结合src/settings-ui/下的实际工程文件说明 MVVM 分层在 PowerToys 中的落点、快捷键Hotkey逻辑所在位置以及设置应用被 Runner 拉起和终止的完整生命周期。一、Settings V2 是什么Windows App SDK WinUI3 Unpackaged 应用原总览文档对 Settings 的定义是一句话Settingsis Windows App Sdk WinUI3 .Net Unpackaged desktop application。这句话里包含三个关键技术选型均可在工程文件中得到印证选型含义仓库证据Windows App SDK使用微软面向 WinUI3 的跨打包/非打包开发 SDK而非传统的 UWP/Win32 框架PowerToys.Settings.csproj 中引用Microsoft.WindowsAppSDKWinUI3UI 用 XAML WinUI 控件描述C# 编写视图模型同上csproj 中UseWinUItrue/UseWinUI.Net Unpackaged.NET 桌面应用形态不使用 MSIX 打包以散文件方式随 PowerToys 安装目录分发csproj 中WindowsPackageTypeNone/WindowsPackageType此外csproj 中WindowsAppSDKSelfContainedtrue/WindowsAppSDKSelfContained表明运行时随应用自带self-contained配合OutputPath$(RepoRoot)$(Platform)\$(Configuration)\WinUI3Apps/OutputPath可以看到Settings 的构建产物统一输出到解决方案输出目录下的WinUI3Apps子目录由安装器installer/下的Settings.wxs与 PowerToys 主体一起打包分发。从依赖列表还能看到两个对理解架构很重要的引用csprojStreamJsonRpc用于进程间 RPC 通信的 NuGet 包是 Settings 与 Runner 之间 IPC 的基础设施CommunityToolkit.WinUI.*系列WinUI3 社区工具包提供设置页常用控件如 SettingsExpander、Segmented 等。二、工程结构总览三部分构成与 MVVM 分层总览文档 的核心内容是 Settings V2 的工程结构。文档指出该工程遵循MVVM 架构模式图形界面与视图模型分离并将工程划分为三个部分src/settings-ui/ ├── Settings.UI/ # ① UI 组件Views/XAML ③ Settings Runner 进程宿主 │ ├── SettingsXAML/ # 页面、控件、OOBE 引导窗口 │ └── ViewModels/ # ShellViewModel 与各模块 ViewModel ├── Settings.UI.Library/ # ② 数据模型/视图模型数据XSettings、XProperties ├── Settings.UI.Controls/ # 公共 UI 控件库 ├── Settings.UI.UnitTests/ # 单元测试 └── Settings.UITests/ # UI 自动化测试下面按文档的三个小节逐一展开并补充源码层面的细节。2.1 UI 组件src/settings-ui/Settings.UI/文档原文The UI Components are part of PowerToys.Settings project. It contains the xaml files for each of the UI components. It also contains the Hotkey logic for the settings control.即 UI 组件属于PowerToys.Settings工程包含各 UI 组件的 XAML 文件同时包含设置界面中快捷键Hotkey控制相关的逻辑。从源码结构看这一描述对应如下布局Settings.UI/SettingsXAML/全部 XAML 页面与自定义控件包括各模块的设置页、标题栏Controls/TitleBar/、仪表盘组件Controls/Dashboard/、OOBE 首次运行引导OOBE/Settings.UI/ViewModels/MVVM 中的 ViewModel 层入口是 ShellViewModel页面基类为 PageViewModelBase并存在与每个 PowerToy 模块一一对应的 ViewModel如 FancyZonesViewModel、MouseWithoutBordersViewModel、ColorPickerViewModel、WorkspacesViewModel 等快捷键逻辑集中体现在ShortcutControl设置页中可按键捕获的快捷键输入控件GlobalHotkeyConflictManager 与 HotkeyConflictHelper当用户在界面中修改快捷键时检测全局快捷键冲突并弹窗提示对应仪表盘中的ShortcutConflictWindow组件快捷键被修改后的下发路径见 IPCResponseService它负责把界面变更通过 IPC 发给 Runner。2.2 视图模型数据src/settings-ui/Settings.UI.Library文档原文The Settings.UI.Library project contains the data that is to be rendered by the UI components.即 Library 工程存放供 UI 组件渲染的数据。它是纯 C# 类库是 MVVM 中 Model 与 ViewModel 绑定的数据契约层。从 目录内容 看其组织规律非常清晰每个模块都有成对的数据模型XxxSettings.cs模块的运行时状态开关、参数值例如AdvancedPasteSettings.cs、AwakeSettings.cs、ColorPickerSettings.csXxxProperties.cs模块的静态属性描述模块名、启用开关元数据等例如AwakeProperties.cs、CmdPalProperties.cs基础类型BasePTModuleSettings 是所有模块设置的基类BoolProperty.cs、DoubleProperty.cs等则是带默认值与序列化/反序列化能力的属性封装供 ViewModel 与配置文件之间做双向同步。这种Settings状态 Properties元数据的成对设计使得 UI 层无需关心 JSON 配置文件格式只需绑定 Library 暴露出的强类型属性即可。2.3 Settings Runner界面变更到 Runner 的通信中枢文档原文The function of the settings runner project is to communicate all changes that the user makes in the user interface, to the runner so that it can be dispatched and reflected in all the modules.注意这里settings runner指的是设置进程本身承担的职责把用户在界面做的每一次变更通信给 PowerToys 主进程Runner位于src/runner/由 Runner 统一分发给各个 PowerToy 模块并生效。这个进程的生命周期在 App.xaml.cs 中体现得最完整由 Runner 带参拉起。设置进程启动时接收 Runner 传入的一组命令行参数参数枚举 定义了全部 10 个位置参数参数含义PTPipeName/SettingsPipeName与 Runner 双向通信的两个命名管道名PTPidRunner 进程 PID存入App.PowerToysPIDTheme主题旧版设置的遗留参数ElevatedStatus/IsUserAdmin是否以管理员身份运行 / 用户是否为管理员影响部分模块可用性显示ShowOobeWindow/ShowScoobeWindow是否显示 OOBE首次配置/ SCOBE升级后引导窗口ContainsSettingsWindow是否打开设置主窗口建立 IPC 并注册回调。构造函数中初始化TwoWayPipeMessageIPCManaged来自PowerToys.Interop对应src/interop/工程Runner 侧发来的消息通过IPCMessageReceivedCallback回调注入 UI。等待 Runner 的终止信号。构造函数尾部调用NativeEventWaiter.WaitForEventLoop(Constants.PowerToysRunnerTerminateSettingsEvent(), ...)App.xaml.cs设置进程挂起等待一个 Windows 命名事件当主 Runner 释放该事件时设置进程清理 ETW Trace 后以退出码 0 结束。也就是说设置进程的生命周期完全受 Runner 管控——Runner 退出或需要重载设置时通过事件触发设置进程优雅退出。变更下发。用户修改任何开关或参数后对应模块的 ViewModel 经IPCResponseService将 JSON 形式的设置变更发送到 Runner 管道Runner 读取后更新powertoys_settings.json并通知各模块。这条链路的更细粒度文档见 Runner IPC 文档 与 模块通信文档。三、MVVM 在 Settings V2 中的落点总览文档 明确指出工程遵循 MVVMModel-View-ViewModel模式图形界面与视图模型分离。结合前面的源码结构可以把三层对应关系归纳为MVVM 角色代码位置说明View视图src/settings-ui/Settings.UI/SettingsXAML/XAML 页面 控件代码只负责呈现与用户输入ViewModelsrc/settings-ui/Settings.UI/ViewModels/ShellViewModel管理导航/页面生命周期各XxxViewModel暴露绑定属性与命令Model数据src/settings-ui/Settings.UI.Library/XxxSettings/XxxProperties强类型数据模型含序列化契约跨进程服务src/settings-ui/Settings.UI/Services/IPCResponseService等把 ViewModel 的变更序列化后经管道交给 RunnerShellViewModel作为导航壳实现见持有当前页面集合与导航状态每个模块页面都继承PageViewModelBase保证返回导航、页面标题、模块状态图标等行为一致。其可测性由 Settings.UI.UnitTests 中的单元测试覆盖例如ShellViewModelTests这从侧面印证了 View 与 ViewModel 确实解耦——测试无需启动 XAML 即可验证导航逻辑。四、进一步深入配套文档地图总览文档 是 Settings 系列文档的入口见 系列索引。读懂本篇后可按主题继续阅读同目录下的细化文档UI 架构窗口、导航、主题的完整设计ViewModels视图模型层的数据流约定Settings 实现配置读写与模块联动细节Runner IPC 与 模块通信进程间消息协议Hotkey 控制与键盘钩子快捷键捕获、全局钩子与冲突处理遥测、GPO 集成、DSC 配置、与旧版设置的兼容。五、小结PowerToys Settings V2 的本质是一个受 Runner 管控生命周期的 WinUI3 非打包应用技术栈Windows App SDK WinUI3 .NET Unpackagedself-contained 运行时随安装目录分发分层Settings.UIXAML 视图 ViewModel Hotkey 逻辑与Settings.UI.LibrarySettings/Properties 数据模型分离严格执行 MVVM通信进程由 Runner 带 10 个参数拉起通过StreamJsonRpc命名管道双向通信所有界面变更经IPCResponseService下发至 Runner再分发给各 PowerToy 模块进程退出则由 Runner 的命名事件触发优雅收尾。理解这套结构后无论是排查设置改不动、快捷键冲突提示异常还是为某个 PowerToy 模块新增设置页都能快速定位到对应的 ViewModel、数据模型与 IPC 服务文件。【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考