doc/dsc/overview.md
PowerToys supports Desired State Configuration (DSC) v3 for declarative configuration management of PowerToys settings.
PowerToys includes Microsoft Desired State Configuration (DSC) support
through the PowerToys.DSC.exe command-line tool, enabling you to:
The PowerToys DSC implementation provides a settings resource that manages configuration for all PowerToys utilities (modules). Each utility can be configured independently, allowing granular control over your PowerToys environment.
PowerToys DSC can be used in three ways:
Execute DSC operations directly using the PowerToys.DSC.exe command-line tool:
# Get current settings for a module
PowerToys.DSC.exe get --resource 'settings' --module Awake
# Set settings for a module
$input = '{"settings":{...}}'
PowerToys.DSC.exe set --resource 'settings' --module Awake --input $input
# Test if settings match desired state
PowerToys.DSC.exe test --resource 'settings' --module Awake --input $input
For detailed information, see PowerToys.DSC.exe command reference.
Use PowerToys DSC resources in standard DSC configuration documents:
# powertoys-config.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Configure Awake
type: Microsoft.PowerToys/AwakeSettings
properties:
settings:
properties:
keepDisplayOn: true
mode: 1
name: Awake
version: 0.0.1
Integrate PowerToys configuration with WinGet package installation:
# winget-powertoys.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 FancyZones
type: Microsoft.PowerToys/FancyZonesSettings
properties:
settings:
properties:
fancyzones_shiftDrag: true
fancyzones_mouseSwitch: true
name: FancyZones
version: 1.0
PowerToys DSC provides the following resource:
| Resource | Description |
|---|---|
settings | Manages configuration for PowerToys utility modules. |
For detailed information about the settings resource, see Settings Resource Reference.
The settings resource supports configuration for the following PowerToys utilities:
| Module | Description | Documentation |
|---|---|---|
| App | General PowerToys application settings. | App module |
| AdvancedPaste | Advanced clipboard operations. | AdvancedPaste module |
| AlwaysOnTop | Pin windows to stay on top. | AlwaysOnTop module |
| Awake | Keep computer awake. | Awake module |
| ColorPicker | System-wide color picker utility. | ColorPicker module |
| CropAndLock | Crop and lock portions of windows. | CropAndLock module |
| EnvironmentVariables | Manage environment variables. | EnvironmentVariables module |
| FancyZones | Window layout manager. | FancyZones module |
| FileLocksmith | Identify what's locking files. | FileLocksmith module |
| FindMyMouse | Locate your mouse cursor. | FindMyMouse module |
| Hosts | Quick hosts file editor. | Hosts module |
| ImageResizer | Resize images from context menu. | ImageResizer module |
| KeyboardManager | Remap keys and create shortcuts. | KeyboardManager module |
| MeasureTool | Measure pixels on screen. | MeasureTool module |
| MouseHighlighter | Highlight mouse cursor. | MouseHighlighter module |
| MouseJump | Jump across large or multiple displays. | MouseJump module |
| MousePointerCrosshairs | Display crosshairs centered on mouse. | MousePointerCrosshairs module |
| Peek | Quick file previewer. | Peek module |
| PowerAccent | Quick accent character selector. | PowerAccent module |
| PowerOCR | Extract text from images. | PowerOCR module |
| PowerRename | Bulk rename files. | PowerRename module |
| RegistryPreview | Visualize and edit registry files. | RegistryPreview module |
| ShortcutGuide | Display keyboard shortcuts. | ShortcutGuide module |
| Workspaces | Save and restore application sets. | Workspaces module |
| ZoomIt | Screen zoom and annotation tool. | ZoomIt module |
PowerToys.DSC.exe modules --resource 'settings'
# Get configuration for a specific module.
PowerToys.DSC.exe get --resource 'settings' --module FancyZones
# Export configuration (identical to get).
PowerToys.DSC.exe export --resource 'settings' --module FancyZones
# Set configuration for a module.
$input = '{"settings":{...}}'
PowerToys.DSC.exe set --resource 'settings' --module FancyZones --input $input
# Test if current state matches desired state.
$input = '{"settings":{...}}'
PowerToys.DSC.exe test --resource 'settings' --module FancyZones --input $input
# Get JSON schema for a module's settings.
PowerToys.DSC.exe schema --resource 'settings' --module FancyZones
# Generate manifest for a specific module.
$outputDir = "C:\manifests"
PowerToys.DSC.exe manifest --resource 'settings' --module FancyZones `
--outputDir $outputDir
# Generate manifests for all modules.
PowerToys.DSC.exe manifest --resource 'settings' --outputDir $outputDir
For complete examples, see: