企业官网建设流程全解析

PowerToys AdvancedPaste DSC 配置参考：用 PowerToys.DSC.exe、DSC 与 WinGet 管理高级粘贴设置

【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys

本文基于 PowerToys 仓库的官方 DSC 模块文档 AdvancedPaste Module 展开，系统讲解如何通过 Desired State Configuration（DSC）声明式管理 Advanced Paste 高级粘贴模块的配置：覆盖全部可配置属性与默认值、五种官方配置方式（PowerShell 直接执行、DSC YAML、WinGet 集成等），并结合仓库源码揭示settings资源的底层映射机制、默认快捷键常量与单元验证逻辑，帮助你在多机环境或脚本化场景中批量下发、校验 Advanced Paste 的 AI 粘贴与快捷键设置。

1. 背景：PowerToys 的 DSC 支持

PowerToys 通过PowerToys.DSC.exe命令行工具支持 DSC v3，用于声明并强制 PowerToys 各模块的期望配置状态（详见 PowerToys DSC Overview）。它提供单一的settings资源，可按模块粒度独立管理配置，支持三种使用方式：

1. 直接执行：调用PowerToys.DSC.exe的get/set/test/export/schema/manifest子命令；
2. 标准 DSC 配置文档：在 DSC v3 YAML 文档中使用资源类型Microsoft.PowerToys/<Module>Settings（本模块即Microsoft.PowerToys/AdvancedPasteSettings）；
3. WinGet Configuration：在winget configure文档中先安装包、再声明期望配置。

AdvancedPaste是受支持的模块之一。在 SettingsResource.cs 中，DSC 资源在构造时把模块名映射到对应的设置类型：

_moduleFunctionData = new() { { AppModule, CreateModuleFunctionData<GeneralSettings> }, { nameof(ModuleType.AdvancedPaste), CreateModuleFunctionData<AdvancedPasteSettings> }, { nameof(ModuleType.AlwaysOnTop), CreateModuleFunctionData<AlwaysOnTopSettings> }, // ... 其余模块 ... };

AdvancedPaste因此绑定到 AdvancedPasteSettings 类型——该类型即 Advanced Paste 模块在 PowerToys 中实际使用的设置模型，DSC 写入的状态最终与设置界面、运行时读取的是同一份数据。

2. 可配置属性完整参考

以下属性定义继承自官方模块文档 AdvancedPaste.md，描述对 PowerToys Advanced Paste 进行高级剪贴板操作（纯文本转换、Markdown 格式化、JSON 格式化、AI 文本处理等）时可声明的配置项。

2.1 快捷键对象（Hotkey）结构

三个快捷键属性均为同一结构的对象，包含六个字段：

• win（boolean）——Windows 键修饰符；
• ctrl（boolean）——Ctrl 键修饰符；
• alt（boolean）——Alt 键修饰符；
• shift（boolean）——Shift 键修饰符；
• code（integer）——虚拟键码（Virtual Key Code），例如V键为86（即0x56）；
• key（string）——按键名称，例如V。

2.2 源码佐证：默认值与 JSON 属性名

对照 AdvancedPasteProperties.cs，源码中与文档默认值相互印证或补充的要点：

public static readonly HotkeySettings DefaultAdvancedPasteUIShortcut = new HotkeySettings(true, false, false, true, 0x56); // Win+Shift+V public static readonly HotkeySettings DefaultPasteAsPlainTextShortcut = new HotkeySettings(true, true, true, false, 0x56); // Ctrl+Win+Alt+V // 构造函数中: IsAIEnabled = false; ShowCustomPreview = true; ShowAIPaste = true; CloseAfterLosingFocus = false;

• IsAdvancedAIEnabled与IsAIEnabled的关系：源码中 IsAdvancedAIEnabled 标注了[JsonPropertyName("IsAdvancedAIEnabled")]的遗留别名属性，其 setter 会写入真正的IsAIEnabled属性。也就是说文档中的IsAdvancedAIEnabled是一个受 DSC/配置输入兼容的别名入口，最终作用于 AI 开关状态。
• 快捷键默认值细节：文档标注PasteAsPlainTextHotkey默认为Ctrl+Win+V；而从源码结构看，DefaultPasteAsPlainTextShortcut常量注释为Ctrl+Win+Alt+V（win/ctrl/alt 均为 true）。两处描述存在差异，实际生效值建议在脚本中以PowerToys.DSC.exe get --resource 'settings' --module AdvancedPaste的输出为准。
• 设置文件的实际 JSON 名称：AdvancedPasteProperties 中各快捷键属性带有 kebab-case 的JsonPropertyName，如advanced-paste-ui-hotkey、paste-as-plain-hotkey、paste-as-markdown-hotkey、paste-as-json-hotkey。这意味着 DSC 输入使用文档中的 PascalCase 属性名，而落盘到settings.json后是 kebab-case 名称——排查配置文件时注意这一映射。
• 文档未逐一列出的属性：DSC 资源管理的是整个AdvancedPasteSettings对象，因此ShowAIPaste（默认true）、EnableClipboardPreview（默认true）、AutoCopySelectionForCustomActionHotkey（默认false）以及 Advanced Paste 主界面快捷键（默认Win+Shift+V）等同样属于该设置对象。完整字段清单建议通过PowerToys.DSC.exe schema --resource 'settings' --module AdvancedPaste生成 JSON Schema 后确认。

2.3 设置对象的 name 与 version

每个 DSC 输入中的settings对象除properties外还包含name与version两个字段。从 AdvancedPasteSettings 构造函数 可见，该模块固定为：

Properties = new AdvancedPasteProperties(); Version = "1"; Name = ModuleName; // ModuleName = "AdvancedPaste"

因此所有示例中统一写作name: AdvancedPaste、version: 1.0。这里的version是设置文档自身的版本号，与 DSC 资源清单的资源版本无关。

3. 五种官方配置示例（完整继承）

3.1 示例 1：PowerShell 直接执行，启用 AI 功能

通过PowerToys.DSC.exe set启用 AI 驱动的粘贴转换：

$config = @{ settings = @{ properties = @{ IsAdvancedAIEnabled = $true } name = "AdvancedPaste" version = "1.0" } } | ConvertTo-Json -Depth 10 -Compress PowerToys.DSC.exe set --resource 'settings' --module AdvancedPaste ` --input $config

3.2 示例 2：用 DSC 文档配置粘贴快捷键

自定义不同粘贴格式的键盘快捷键。先编写advancedpaste-hotkeys.dsc.yaml：

# advancedpaste-hotkeys.dsc.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Configure Advanced Paste hotkeys type: Microsoft.PowerToys/AdvancedPasteSettings properties: settings: properties: PasteAsPlainTextHotkey: win: true ctrl: true alt: false shift: false code: 86 key: V PasteAsMarkdownHotkey: win: true ctrl: true alt: false shift: true code: 86 key: V name: AdvancedPaste version: 1.0

然后执行：

dsc config set --file advancedpaste-hotkeys.dsc.yaml

其中code: 86对应虚拟键码0x56，即V键；key: V为可读的按键名。该示例将纯文本粘贴设为Ctrl+Win+V，Markdown 粘贴设为Ctrl+Win+Shift+V。

3.3 示例 3：WinGet 一键安装并配置

先安装 PowerToys 再声明期望配置，适合全新机器或域环境批量部署：

winget configure winget-advancedpaste.yaml

# winget-advancedpaste.yaml $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json metadata: winget: processor: dscv3 resources: - name: Install PowerToys type: Microsoft.WinGet.DSC/WinGetPackage properties: id: Microsoft.PowerToys source: winget - name: Configure Advanced Paste type: Microsoft.PowerToys/AdvancedPasteSettings properties: settings: properties: IsAdvancedAIEnabled: true ShowCustomPreview: true CloseAfterLosingFocus: true name: AdvancedPaste version: 1.0

3.4 示例 4：自定义预览行为

针对自定义粘贴格式的预览窗口行为进行配置：

dsc config set --file advancedpaste-preview.dsc.yaml

# advancedpaste-preview.dsc.yaml $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json resources: - name: Configure preview settings type: Microsoft.PowerToys/AdvancedPasteSettings properties: settings: properties: ShowCustomPreview: true CloseAfterLosingFocus: false name: AdvancedPaste version: 1.0

3.5 示例 5：测试 AI 功能是否已启用（desired state 校验）

test命令只读地比对当前状态与期望状态，常用于 CI/CD 或合规巡检脚本：

$desired = @{ settings = @{ properties = @{ IsAdvancedAIEnabled = $true } name = "AdvancedPaste" version = "1.0" } } | ConvertTo-Json -Depth 10 -Compress $result = PowerToys.DSC.exe test --resource 'settings' ` --module AdvancedPaste --input $desired | ConvertFrom-Json if ($result._inDesiredState) { Write-Host "AI features are enabled" } else { Write-Host "AI features need to be enabled" }

4. 底层实现：set / test 是如何工作的

理解 DSC 文档背后PowerToys.DSC.exe的执行链路，有助于解释示例 5 的判定逻辑。核心实现在 SettingsResource.cs：

• SetState（对应set子命令）：先对输入执行GetState读取当前值，再计算GetDiffJson()；只有当TestState()判定当前状态与期望状态不一致时，才把输入设置写回并触发保存，最后依次输出“新状态”与“差异字段列表”两行 JSON。这就是为什么重复执行相同配置是无副作用（idempotent）的。
• TestState（对应test子命令）：读取当前状态后仅做比对，把结果写入输出对象的InDesiredState字段（即示例 5 中解析的_inDesiredState），并附差异字段，不做任何写入。
• Schema/Manifest：schema子命令输出模块的 JSON Schema；manifest子命令按 GenerateManifest 生成 DSC v3 资源清单，资源名即<模块名>Settings（故 AdvancedPaste 对应Microsoft.PowerToys/AdvancedPasteSettings），并声明export、get、set（支持 pretest）、test、schema五种方法与对应命令行参数。

此外，SettingsResource 构造函数末尾 明确列出了当前不支持的模块及原因，编写 DSC 策略时可避免误用：

// The following modules are not currently supported: // - MouseWithoutBorders Contains sensitive configuration values, making export/import potentially insecure. // - PowerLauncher Uses absolute file paths in its settings, which are not portable across systems. // - NewPlus Uses absolute file paths in its settings, which are not portable across systems.

5. 单元验证：测试如何覆盖 AdvancedPaste 模块

仓库为每个受支持模块提供基于通用基类的 DSC 资源测试。SettingsResourceAdvancedPasteModuleTest 继承自泛型基类 SettingsResourceModuleTest`1.cs，针对 AdvancedPaste 的差异修改动作是：

s.Properties.ShowCustomPreview = !s.Properties.ShowCustomPreview; s.Properties.CloseAfterLosingFocus = !s.Properties.CloseAfterLosingFocus; s.Properties.AdvancedPasteUIShortcut = new HotkeySettings { Key = "mock", Alt = true, };

基类据此自动生成六组测试用例（Get_Success、Export_Success、SetWithDiff_Success、SetWithoutDiff_Success、TestWithDiff_Success、TestWithoutDiff_Success），验证：

1. get/export输出与磁盘上的实际设置深度相等；
2. set在有差异时确实改写了设置（AssertSettingsHasChanged），无差异时设置保持不变且差异输出为空；
3. test在有差异时返回_inDesiredState = false，无差异时返回true。

这组测试从侧面印证了文档示例 5 的判定语义：_inDesiredState字段是test命令对“期望状态是否满足”的正式输出契约。

值得注意的细节：测试修改了AdvancedPasteUIShortcut（Advanced Paste 主界面快捷键），而文档属性表未单独列出该字段——结合 GetAllHotkeyAccessors 可以看到，AdvancedPasteSettings同时暴露四个基础快捷键（PasteAsPlainTextShortcut、AdvancedPasteUIShortcut、PasteAsMarkdownShortcut、PasteAsJsonShortcut）以及附加操作与自定义操作的快捷键。由于 DSC 管理的是完整设置对象，从源码结构看，这些快捷键字段同样可通过 DSC 输入读写，具体字段名以schema命令输出为准。

6. 典型使用场景（Use Cases）

官方文档给出两类典型场景，此处完整保留并略作说明。

6.1 开发工作流：面向代码片段与文档的 AI 转换

resources: - name: Developer paste settings type: Microsoft.PowerToys/AdvancedPasteSettings properties: settings: properties: IsAdvancedAIEnabled: true ShowCustomPreview: true name: AdvancedPaste version: 1.0

6.2 内容创作：面向 Markdown 与格式化文本操作

resources: - name: Content creator settings type: Microsoft.PowerToys/AdvancedPasteSettings properties: settings: properties: ShowCustomPreview: true CloseAfterLosingFocus: false name: AdvancedPaste version: 1.0

保留预览窗口（ShowCustomPreview: true）并在失焦后不关闭窗口（CloseAfterLosingFocus: false），便于在多次粘贴格式化内容时持续操作预览界面。

7. 实操注意事项小结

1. 入口选择：一次性调试用PowerToys.DSC.exe直接执行；纳入配置管理/版本库用 DSC YAML；全新装机流水线用winget configure组合安装与配置。
2. 幂等与安全：set仅在状态不一致时写入（源码SetState先TestState再落盘），可放心在自动化中重复执行；test完全只读，适合放在巡检脚本中依据_inDesiredState分支处理。
3. 属性名与落盘名差异：DSC 输入使用文档的 PascalCase 属性名，而settings.json中快捷键为 kebab-case 名称（如paste-as-plain-hotkey）；IsAdvancedAIEnabled在源码中是IsAIEnabled的遗留兼容别名。
4. 默认快捷键核对：文档标注与源码默认常量在PasteAsPlainTextHotkey上存在描述差异，脚本化下发前建议用get或schema命令核对本机实际默认值。
5. 模块边界：AdvancedPaste属于 DSCsettings资源支持的 25 个模块之一；MouseWithoutBorders、PowerLauncher、NewPlus因敏感配置或绝对路径原因明确不受支持。

8. 延伸阅读

• PowerToys DSC Overview —— DSC 支持的整体概览、命令参考与模块清单
• Settings Resource 参考 ——settings资源的通用说明与示例
• ColorPicker Module —— 同系列模块文档示例（系统级取色器）
• SettingsResource.cs —— DSC 资源核心实现
• AdvancedPasteSettings.cs 与 AdvancedPasteProperties.cs —— 设置模型与默认值定义
• SettingsResourceAdvancedPasteModuleTest.cs —— 模块级 DSC 行为测试

【免费下载链接】PowerToysMicrosoft PowerToys is a collection of utilities that supercharge productivity and customization on Windows项目地址: https://gitcode.com/GitHub_Trending/po/PowerToys