Microsoft PowerToys Hosts 模块 DSC 声明式配置指南：从直接执行到 WinGet 批量部署

本文基于 PowerToys 仓库的 DSC 配置参考文档 doc/dsc/modules/Hosts.md，讲解如何通过 DSC v3 的 settings 资源对 Hosts File Editor（hosts 文件编辑器）做声明式管理，覆盖 LaunchAdministrator、LoopbackDuplicates、AdditionalLinesPosition 三个核心属性，并结合 src/dsc 的 DSC 实现源码与 src/modules/Hosts 模块代码，拆解从直接执行到 WinGet 批量部署的完整链路，以及配置项在 settings.json 中的持久化与热加载机制，帮助你在生产环境中建立可审计、幂等的 Hosts 编辑器配置流程。

背景：PowerToys DSC settings 资源与 Hosts 模块

PowerToys 通过一个名为 settings 的 DSC 资源（命令行入口为 PowerToys.DSC.exe）支持对各模块配置的声明式管理，标准 DSC 操作包括 get、set、test、export、schema 和 manifest，详细说明见 doc/dsc/settings-resource.md 与 doc/dsc/overview.md。

从源码看，settings 资源支持的模块清单在 SettingsResource.cs 的构造函数中显式注册，Hosts 模块对应的映射为：

{ nameof(ModuleType.Hosts), CreateModuleFunctionData<HostsSettings> },

即 DSC 配置文档中的资源类型 Microsoft.PowerToys/HostsSettings，其 properties 最终会被反序列化为 HostsSettings（内部包装 HostsProperties 设置模型）。值得注意的是，同一文件中的注释说明了三个不受支持的模块：MouseWithoutBorders（配置含敏感值）、PowerLauncher 与 NewPlus（配置含不可移植的绝对路径），而 Hosts 在支持列表中，可放心用于声明式配置。

该模块有两条典型使用路径：

1. 直接执行：调用随 PowerToys 安装的 PowerToys.DSC.exe，适合脚本化、即席修改与状态校验；
2. 声明式配置：通过 dsc config set --file <配置>.dsc.yaml 或 winget configure <配置>.yaml，适合装机脚本与批量部署（WinGet 路径需要配置文档带 metadata.winget.processor: dscv3 标记）。

Hosts 模块本体是一个 WinUI 3 应用，由 runner 从 WinUI3Apps/PowerToys.HostsModuleInterface.dll 加载，代码分为 Hosts（入口）、HostsModuleInterface（集成接口）、HostsUILib（UI 层）三部分，整体结构可参考 doc/devdocs/modules/hostsfileeditor.md。

Hosts 模块可配置属性

根据 doc/dsc/modules/Hosts.md 的参考定义，Hosts 模块支持以下可配置属性：

属性	类型	参考文档默认值	说明
LaunchAdministrator	boolean	false	编辑器是否默认以管理员权限启动。启用后，编辑器会始终尝试以提权方式启动，这是修改 hosts 文件所必需的
LoopbackDuplicates	boolean	false	是否将回环地址（loopback）视为重复项参与重复检测
AdditionalLinesPosition	integer	0	编辑条目时附加行的位置：0 = Top（顶部），1 = Bottom（底部）

LaunchAdministrator：以管理员身份启动

Windows 的 hosts 文件位于 C:\Windows\System32\drivers\etc\hosts，普通权限无法写回，因此“以管理员身份打开”是 Hosts File Editor 最关键的开关。该属性在设置 UI 侧由 HostsViewModel.cs 绑定到 Settings.Properties.LaunchAdministrator 并即时持久化。

一个需要留意的细节：参考文档中该属性的默认值标注为 false，但从源码 HostsProperties.cs 的构造函数看，LaunchAdministrator 的初始值实际是 true（即 settings.json 不存在、首次生成默认设置时，该项默认开启）。参考文档与代码默认值存在出入，落地时建议以 PowerToys.DSC.exe get --resource 'settings' --module Hosts 的实测输出为准。

LoopbackDuplicates：回环地址的重复检测行为

Hosts 文件里常见的 127.0.0.1、::1 等回环地址，默认不会被标红为“重复项”。从源码看，该逻辑实现在 DuplicateService.cs：服务内置了 7 个回环地址（0.0.0.0、::、::0、0:0:0:0:0:0:0:0、127.0.0.1、::1、0:0:0:0:0:0:0:1），在 Initialize 与 SetDuplicate 两处（L63-L71、L116-L126）均通过 _userSettings.LoopbackDuplicates 判断：

• false（默认）：回环地址条目被跳过/强制清除重复标记，因此 hosts 文件中多次出现的 127.0.0.1 localhost 等行不会被标为重复；
• true：回环地址与其他地址同等参与重复判定，适合需要严格检查 hosts 文件冗余条目的场景。

由于该开关在 UserSettings.cs 中通过 LoopbackDuplicatesChanged 事件对外通知，修改配置后编辑器无需重启即可重新执行重复检测。

AdditionalLinesPosition：附加行位置

该属性决定编辑条目时“附加行”（additional lines）插入的位置。其取值与 HostsAdditionalLinesPosition 枚举一一对应：

public enum HostsAdditionalLinesPosition
{
    Top = 0,
    Bottom = 1,
}

因此 DSC 配置中只能写入 0 或 1 两个整数值，分别表示顶部与底部。

此外，从 HostsProperties.cs 的完整模型看，Hosts 设置还包含 ShowStartupWarning、Encoding（Utf8/Utf8Bom）、NoLeadingSpaces、BackupHosts、BackupPath、DeleteBackupsMode、DeleteBackupsDays、DeleteBackupsCount 等属性。如需确认当前安装版本中 DSC 实际暴露的完整属性清单与类型，最可靠的做法是直接查询 JSON Schema：

PowerToys.DSC.exe schema --resource 'settings' --module Hosts

使用示例

以下示例完整继承自 doc/dsc/modules/Hosts.md，按“直接执行 → DSC → WinGet → 开发场景”由浅入深组织。

示例 1：直接执行，启用管理员启动

通过 PowerShell 构造 JSON 输入，调用 PowerToys.DSC.exe set 将 LaunchAdministrator 设为 true：

$config = @{
    settings = @{
        properties = @{
            LaunchAdministrator = $true
        }
        name = "Hosts"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

PowerToys.DSC.exe set --resource 'settings' --module Hosts --input $config

properties 内只需写想要变更的属性；name 固定为模块名 Hosts，version 为资源版本号。

示例 2：使用 DSC 配置文件

将期望状态写入 hosts-config.dsc.yaml，同时启用管理员启动并把附加行位置设为底部：

# hosts-config.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure Hosts File Editor
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
          AdditionalLinesPosition: 1
        name: Hosts
        version: 1.0

dsc config set --file hosts-config.dsc.yaml

示例 3：WinGet 安装并配置（批量部署）

在 winget-hosts.yaml 中先安装 PowerToys 包，再应用 Hosts 配置，一条 winget configure 即可完成装机与配置：

winget configure winget-hosts.yaml

# winget-hosts.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 Hosts File Editor
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
          LoopbackDuplicates: false
        name: Hosts
        version: 1.0

这种两段式写法（先 WinGetPackage 安装、后 HostsSettings 配置）与 doc/dsc/settings-resource.md 中多模块部署的示例模式一致，是批量环境中最常见的形态；仓库中 src/dsc/Microsoft.PowerToys.Configure/examples 目录还附带了 installAndConfiguration.winget、enableAllModules.winget 等可直接参考的示例文件。

示例 4：开发环境配置

面向开发用途，新条目放在文件底部（AdditionalLinesPosition: 1），便于追加本地域名解析而不打扰原有内容：

dsc config set --file hosts-development.dsc.yaml

# hosts-development.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Development hosts configuration
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
          AdditionalLinesPosition: 1
        name: Hosts
        version: 1.0

典型使用场景

参考文档给出的两类场景配置如下，可裁剪进你自己的 dsc.yaml / winget.yaml。

系统管理场景

面向需要频繁编辑 hosts 文件的管理员，固定开启管理员启动：

resources:
  - name: Admin configuration
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
        name: Hosts
        version: 1.0

Web 开发场景

面向开发环境管理：管理员启动 + 新条目置于文件底部：

resources:
  - name: Developer configuration
    type: Microsoft.PowerToys/HostsSettings
    properties:
      settings:
        properties:
          LaunchAdministrator: true
          AdditionalLinesPosition: 1
        name: Hosts
          version: 1.0

底层机制：DSC 如何落地修改 Hosts 配置

理解 set 操作的内部行为，有助于排查“配置没有生效”一类的现场问题。从 SettingsResource.cs 的 SetState 实现看，流程为：

1. 用输入构造 Hosts 的函数数据并先读取当前状态（data.GetState()）；
2. 计算期望状态与当前状态的 diff（GetDiffJson()）；
3. 仅当 TestState() 判定不一致时，才把输入的设置对象整体写回并持久化（data.SetState()）——这保证了 set 的幂等性：重复执行不会触发无谓的写盘；
4. 最终输出写回后的状态 JSON 与 diff JSON 两行结果，供审计使用。

持久化之后，Hosts 编辑器侧的响应链路在 UserSettings.cs 中实现：构造函数为 Hosts 模块的 settings.json 注册了文件监听器（L79），文件变化时自动触发 LoadSettingsFromJson 重新加载全部属性（读取失败时最多重试 5 次、每次间隔 500ms，见 L82-L132）。也就是说，DSC 写入 settings.json 后，正在运行的 Hosts File Editor 会热加载新配置，无需重启模块。

配合 test 操作可以做配置漂移检测，其输出中带有一个 _inDesiredState 布尔属性（TestState 实现），适合放进 CI 或巡检脚本：

$desired = @{
    settings = @{
        properties = @{
            LaunchAdministrator = $true
        }
        name = "Hosts"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

PowerToys.DSC.exe test --resource 'settings' --module Hosts --input $desired

常用命令速查

目的	命令
列出可配置模块	PowerToys.DSC.exe modules --resource 'settings'
读取当前 Hosts 配置	PowerToys.DSC.exe get --resource 'settings' --module Hosts
导出当前状态（同 get）	PowerToys.DSC.exe export --resource 'settings' --module Hosts
应用期望状态	PowerToys.DSC.exe set --resource 'settings' --module Hosts --input $config
漂移检测	PowerToys.DSC.exe test --resource 'settings' --module Hosts --input $config
查询 JSON Schema	PowerToys.DSC.exe schema --resource 'settings' --module Hosts
生成 DSC 资源清单	PowerToys.DSC.exe manifest --resource 'settings' --module Hosts

命令通用形态的完整说明（含多模块配置、备份导出等脚本示例）见 doc/dsc/settings-resource.md，DSC 整体设计背景见 doc/dsc/overview.md。

相关文档

• PowerToys DSC 总览
• Settings 资源参考
• Hosts File Editor 模块开发文档
• KeyboardManager 模块 DSC 参考
• WinGet 配置示例