PowerToys Image Resizer DSC 配置参考：以声明式配置管理图像缩放模块

Microsoft PowerToys 的 Image Resizer 是一个 Windows Shell 扩展工具，允许用户直接在文件资源管理器右键菜单中批量缩放一张或多张图像。随着 PowerToys 引入 DSC（Desired State Configuration）v3 支持，Image Resizer 的预设尺寸、JPEG 质量、文件名模板等所有可配置项都可以通过 PowerToys.DSC.exe 命令行、标准 DSC YAML 配置文档或 WinGet Configuration 三种方式进行声明式管理。读完本文，你可以掌握 ImageResizer 模块全部 DSC 配置属性的类型、取值范围与默认值，并能为 Web 开发、摄影工作流、社交媒体等场景编写可直接落地的自动化配置。

模块概述与工作方式

DSC 中的 ImageResizer 模块（资源类型 Microsoft.PowerToys/ImageResizerSettings）管理的是 PowerToys Image Resizer 工具的配置。该工具支持：

• 自定义尺寸预设（预设名称、宽高、单位、缩放模式）；
• 是否仅缩小（不放大）图像、是否覆盖原文件；
• 是否忽略 EXIF 方向信息；
• JPEG 输出质量、PNG 交错、TIFF 压缩选项；
• 缩放后文件的重命名模板；
• 是否保留原始修改时间、以及不支持格式的回退编码器。

从源码结构看，这套 DSC 属性与 PowerToys 设置系统共用同一份属性模型 ImageResizerProperties，每个属性以 imageresizer_ 前缀持久化到设置 JSON 中（如 imageresizer_jpegQualityLevel），DSC 的 set 操作最终更新的就是这些设置项。

可配置属性详解

以下属性均可在 properties 下配置，与文档 doc/dsc/modules/ImageResizer.md 保持一致。

ImageResizerSizes：预设尺寸列表

定义 Image Resizer 界面中可选的预设尺寸。

• 类型：对象数组
• 对象属性：
  • Name（string）：预设的显示名称；
  • Width（integer）：宽度值；
  • Height（integer）：高度值；
  • Unit（string）：计量单位，取值为 "Pixel"、"Percent"、"Centimeter"、"Inch"；
  • Fit（string）：缩放模式，取值为 "Fit"、"Fill"、"Stretch"。

从源码结构看，这些取值对应内部枚举 ResizeUnit 与 ResizeFit（ResizeFit: Fill/Fit/Stretch；ResizeUnit: Centimeter/Inch/Percent/Pixel）。若不配置 ImageResizerSizes，PowerToys 使用内置的四个默认预设（Small 854×480、Medium 1366×768、Large 1920×1080、Phone 320×568，均为 Pixel 单位、Fit 模式），见 ImageResizerProperties 构造函数。预设数据在设置 JSON 中以 imageresizer_sizes.value 数组形式存储，序列化模型见 ImageresizerSizes。

ImageresizerSelectedSizeIndex：默认选中的预设

• 类型：integer
• 默认值：0

设置界面中默认高亮的预设索引（0 基）。

ImageresizerShrinkOnly：仅缩小

• 类型：boolean
• 默认值：false

启用后，只有当图像比目标尺寸更大时才会被缩小，较小的图像保持原尺寸不被放大。

ImageresizerReplace：覆盖原文件

• 类型：boolean
• 默认值：false

启用后，缩放结果直接替换原始文件；关闭时生成新文件、保留原图。

ImageresizerIgnoreOrientation：忽略 EXIF 方向

• 类型：boolean
• 默认值：true

控制缩放时是否忽略 EXIF 方向数据。对照片场景建议设为 false，让方向信息参与处理。

ImageresizerJpegQualityLevel：JPEG 质量等级

• 类型：integer
• 取值范围：1–100
• 默认值：90

设置 JPEG 编码器输出质量，对应 ImageResizerProperties 中的默认值 90。

ImageresizerPngInterlaceOption：PNG 交错选项

• 类型：integer
• 允许值：0（不交错）、1（交错）
• 默认值：0

ImageresizerTiffCompressOption：TIFF 压缩选项

• 类型：integer
• 允许值：0（不压缩）、1（LZW 压缩）、2（ZIP 压缩）
• 默认值：0

ImageresizerFileName：重命名模板

• 类型：string
• 默认值："%1 (%2)"
• 占位符：
  • %1：原始文件名
  • %2：所选尺寸名称
  • %3：所选宽度
  • %4：所选高度
  • %5：实际宽度
  • %6：实际高度

例如模板 %1_resized_%2 会将 photo.jpg 用预设 Web Small 缩放后命名为 photo_resized_Web Small.jpg。

ImageresizerKeepDateModified：保留修改时间

• 类型：boolean
• 默认值：false

启用后，缩放生成的文件保留原文件的“修改时间”戳。

ImageresizerFallbackEncoder：回退编码器

• 类型：string
• 允许值："png"、"jpg"、"bmp"、"tiff"、"gif"
• 默认值："png"

当源格式无法按原格式重新编码时使用的回退编码器。从源码结构看，Image Resizer UI 内部以 WIC 编码器 GUID 记录该设置（如 GUID 19e4a5aa-5662-4fc5-a0c0-1758028e1057 映射到 JPEG 编码器，见 CodecHelper 与 Settings.cs），DSC 层则按文档以格式名称作为输入契约。

配置示例

以下五个示例完整继承自 ImageResizer DSC 模块文档。

示例 1：自定义预设尺寸（直接执行）

通过 PowerShell 哈希表构建 JSON 并调用 PowerToys.DSC.exe set 直接下发三个常用预设：

$config = @{
    settings = @{
        properties = @{
            ImageResizerSizes = @(
                @{
                    Name = "Small"
                    Width = 640
                    Height = 480
                    Unit = "Pixel"
                    Fit = "Fit"
                },
                @{
                    Name = "Medium"
                    Width = 1280
                    Height = 720
                    Unit = "Pixel"
                    Fit = "Fit"
                },
                @{
                    Name = "Large"
                    Width = 1920
                    Height = 1080
                    Unit = "Pixel"
                    Fit = "Fit"
                }
            )
        }
        name = "ImageResizer"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

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

示例 2：质量与格式选项（DSC 文档）

使用标准 DSC v3 配置文档下发质量参数：

dsc config set --file imageresizer-quality.dsc.yaml

# imageresizer-quality.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure Image Resizer quality
    type: Microsoft.PowerToys/ImageResizerSettings
    properties:
      settings:
        properties:
          ImageresizerJpegQualityLevel: 95
          ImageresizerShrinkOnly: true
          ImageresizerKeepDateModified: true
        name: ImageResizer
        version: 1.0

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

将安装与配置合并到同一份 WinGet DSC 文档中，实现“装完即用”的 Web 优化预设：

winget configure winget-imageresizer.yaml

# winget-imageresizer.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 Image Resizer
    type: Microsoft.PowerToys/ImageResizerSettings
    properties:
      settings:
        properties:
          ImageResizerSizes:
            - Name: Thumbnail
              Width: 320
              Height: 240
              Unit: Pixel
              Fit: Fit
            - Name: Web Small
              Width: 800
              Height: 600
              Unit: Pixel
              Fit: Fit
            - Name: Web Large
              Width: 1920
              Height: 1080
              Unit: Pixel
              Fit: Fit
          ImageresizerJpegQualityLevel: 85
          ImageresizerFileName: "%1_resized_%2"
        name: ImageResizer
        version: 1.0

仓库中也提供同类安装并配置的参考示例文件，可对照 installAndConfiguration.winget。

示例 4：摄影工作流（高质量 + 元数据保留）

dsc config set --file imageresizer-photo.dsc.yaml

# imageresizer-photography.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Photography configuration
    type: Microsoft.PowerToys/ImageResizerSettings
    properties:
      settings:
        properties:
          ImageresizerJpegQualityLevel: 100
          ImageresizerKeepDateModified: true
          ImageresizerIgnoreOrientation: false
          ImageresizerShrinkOnly: true
        name: ImageResizer
        version: 1.0

该组合把质量拉满、保留拍摄时间戳、尊重 EXIF 方向，并只缩小不放大，适合照片归档前的批量处理。

示例 5：社交媒体预设

$config = @{
    settings = @{
        properties = @{
            ImageResizerSizes = @(
                @{ Name = "Instagram Square"; Width = 1080; Height = 1080; Unit = "Pixel"; Fit = "Fill" },
                @{ Name = "Instagram Portrait"; Width = 1080; Height = 1350; Unit = "Pixel"; Fit = "Fill" },
                @{ Name = "Facebook Cover"; Width = 820; Height = 312; Unit = "Pixel"; Fit = "Fill" },
                @{ Name = "Twitter Header"; Width = 1500; Height = 500; Unit = "Pixel"; Fit = "Fill" }
            )
            ImageresizerJpegQualityLevel = 90
        }
        name = "ImageResizer"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

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

注意这里使用 Fill 模式：平台封面要求“填满画框”，Fill 会裁剪到精确目标尺寸，与保留完整画面的 Fit 形成互补。

典型使用场景

Web 开发

面向 Web 优化的最小配置：

resources:
  - name: Web optimization
    type: Microsoft.PowerToys/ImageResizerSettings
    properties:
      settings:
        properties:
          ImageresizerJpegQualityLevel: 85
          ImageresizerShrinkOnly: true
        name: ImageResizer
        version: 1.0

85 的质量等级兼顾体积与观感，ShrinkOnly 保证小图不被放大虚化。

内容创作

面向社交平台与内容产出的预设：

resources:
  - name: Content creation
    type: Microsoft.PowerToys/ImageResizerSettings
    properties:
      settings:
        properties:
          ImageResizerSizes:
            - Name: HD
              Width: 1920
              Height: 1080
              Unit: Pixel
              Fit: Fit
          ImageresizerJpegQualityLevel: 90
        name: ImageResizer
        version: 1.0

底层实现与验证路径

• 属性模型：所有 DSC 属性与设置界面共用 ImageResizerProperties，其中 Fit/Unit 的枚举值、各属性默认值（如 JPEG 质量默认 90、ignoreOrientation 默认 true）可在此直接核对；
• DSC 资源与命令：settings 资源的 get/set/test/export/schema/manifest 能力由 PowerToys.DSC 实现，命令分别对应 SetCommand、GetCommand 等，资源逻辑见 SettingsResource；
• 测试佐证：SettingsTests 覆盖了 imageresizer_* 设置 JSON 的序列化/反序列化，ImageResizerEndToEndTests 中对 imageresizer_fallbackEncoder 等键值做了端到端断言，可用来验证配置确实落到设置存储；
• 工具本体：Image Resizer 由 Shell 扩展 DLL（src/modules/imageresizer/dll/）、WPF UI（src/modules/imageresizer/ui/）与 CLI（src/modules/imageresizer/ImageResizerCLI/）组成，右键菜单在 Windows 10/11 上采用双注册方案，详见开发文档 Image Resizer 架构说明。

相关文档

• Settings Resource 参考：settings 资源的全部操作（modules/get/set/test/export/schema/manifest）与 25 个受支持模块清单；
• PowerToys DSC 总览：三种使用方式（直接执行、DSC、WinGet）与通用操作；
• MeasureTool 模块文档：同一 DSC 体系下的另一个模块参考；
• Image Resizer 开发文档：Shell 扩展注册、调试方法与右键菜单出现逻辑。

适用前提与限制：DSC 配置要求目标机器已安装支持 DSC 的 PowerToys 版本（PowerToys.DSC.exe 随安装包提供）；属性名区分大小写，ImageResizerSizes 为 DSC 层契约名称，而设置 JSON 内部键为 imageresizer_sizes；PNG 交错与 TIFF 压缩的 DSC 取值（0/1/2）是对外契约，与 UI 内部枚举 PngInterlaceOption、TiffCompressOption 的编号并不一致，编写配置时应以本文列出的 DSC 允许值为准。