mirror of
https://github.com/microsoft/PowerToys.git
synced 2026-04-03 01:36:31 +02:00
Improve DSC documentation (#42554)
<!-- Enter a brief description/summary of your PR here. What does it fix/what does it change/how was it tested (even manually, if necessary)? --> ## Summary of the Pull Request This documentation enhances the DSC documentation by incorporating reference documents and providing examples. Closes #42552. <!-- Please review the items on the PR checklist before submitting--> ## PR Checklist - [x] Closes: #xxx - [ ] **Communication:** I've discussed this with core contributors already. If the work hasn't been agreed, this work might be rejected - [ ] **Tests:** Added/updated and all pass - [ ] **Localization:** All end-user-facing strings can be localized - [ ] **Dev docs:** Added/updated - [ ] **New binaries:** Added on the required places - [ ] [JSON for signing](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ESRPSigning_core.json) for new binaries - [ ] [WXS for installer](https://github.com/microsoft/PowerToys/blob/main/installer/PowerToysSetup/Product.wxs) for new binaries and localization folder - [ ] [YML for CI pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/ci/templates/build-powertoys-steps.yml) for new test projects - [ ] [YML for signed pipeline](https://github.com/microsoft/PowerToys/blob/main/.pipelines/release.yml) - [ ] **Documentation updated:** If checked, please file a pull request on [our docs repo](https://github.com/MicrosoftDocs/windows-uwp/tree/docs/hub/powertoys) and link it here: #xxx <!-- Provide a more detailed description of the PR, other things fixed, or any additional comments/features here --> ## Detailed Description of the Pull Request / Additional comments <!-- Describe how you validated the behavior. Add automated tests wherever possible, but list manual validation steps taken as well --> ## Validation Steps Performed --------- Co-authored-by: Niels Laute <niels.laute@live.nl>
This commit is contained in:
Gijs Reijn
458
doc/dsc/settings-resource.md
Normal file
458
doc/dsc/settings-resource.md
Normal file
@@ -0,0 +1,458 @@
|
||||
---
|
||||
description: Reference for the PowerToys DSC settings resource
|
||||
ms.date: 10/18/2025
|
||||
ms.topic: reference
|
||||
title: Settings Resource
|
||||
---
|
||||
|
||||
# Settings Resource
|
||||
|
||||
## Synopsis
|
||||
|
||||
Manages configuration settings for PowerToys utilities (modules).
|
||||
|
||||
## Description
|
||||
|
||||
The `settings` resource provides Microsoft Desired State Configuration (DSC)
|
||||
support for managing PowerToys configuration. It enables declarative
|
||||
configuration of PowerToys utilities, allowing you to define, test, and
|
||||
enforce desired states for each module.
|
||||
|
||||
Each PowerToys utility (module) has its own configurable properties that can
|
||||
be managed through this resource. The settings resource supports standard DSC
|
||||
operations: get, set, test, export, schema, and manifest generation.
|
||||
|
||||
## Supported modules
|
||||
|
||||
The settings resource supports the following PowerToys modules:
|
||||
|
||||
- **App** - General application settings (enable/disable utilities, run at
|
||||
startup, theme, etc.).
|
||||
- **AdvancedPaste** - Advanced clipboard and paste operations.
|
||||
- **AlwaysOnTop** - Window pinning configuration.
|
||||
- **Awake** - Keep-awake timer settings.
|
||||
- **ColorPicker** - Color picker activation and format settings.
|
||||
- **CropAndLock** - Window cropping settings.
|
||||
- **EnvironmentVariables** - Environment variable editor settings.
|
||||
- **FancyZones** - Window layout and zone configuration.
|
||||
- **FileLocksmith** - File lock detection settings.
|
||||
- **FindMyMouse** - Mouse locator settings.
|
||||
- **Hosts** - Hosts file editor settings.
|
||||
- **ImageResizer** - Image resize configuration.
|
||||
- **KeyboardManager** - Key remapping and shortcut settings.
|
||||
- **MeasureTool** - Screen measurement tool settings.
|
||||
- **MouseHighlighter** - Mouse highlighting configuration.
|
||||
- **MouseJump** - Mouse jump navigation settings.
|
||||
- **MousePointerCrosshairs** - Crosshair display settings.
|
||||
- **Peek** - File preview settings.
|
||||
- **PowerAccent** - Accent character selection settings.
|
||||
- **PowerOCR** - Text extraction settings.
|
||||
- **PowerRename** - Bulk rename configuration.
|
||||
- **RegistryPreview** - Registry file preview settings.
|
||||
- **ShortcutGuide** - Keyboard shortcut overlay settings.
|
||||
- **Workspaces** - Application workspace settings.
|
||||
- **ZoomIt** - Screen zoom and annotation settings.
|
||||
|
||||
For detailed property information for each module, see the individual [module
|
||||
documentation][01].
|
||||
|
||||
## Operations
|
||||
|
||||
### List supported modules
|
||||
|
||||
List all modules that can be configured with the settings resource.
|
||||
|
||||
**Direct execution:**
|
||||
|
||||
```powershell
|
||||
# List all configurable modules.
|
||||
PowerToys.DSC.exe modules --resource 'settings'
|
||||
```
|
||||
|
||||
### Get current state
|
||||
|
||||
Retrieve the current configuration state for a module.
|
||||
|
||||
**Direct execution:**
|
||||
|
||||
```powershell
|
||||
# Get current settings for a module.
|
||||
PowerToys.DSC.exe get --resource 'settings' --module <ModuleName>
|
||||
```
|
||||
|
||||
**DSC configuration:**
|
||||
|
||||
```yaml
|
||||
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
|
||||
resources:
|
||||
- name: Get Awake settings
|
||||
type: Microsoft.PowerToys/AwakeSettings
|
||||
properties: {}
|
||||
```
|
||||
|
||||
**WinGet configuration:**
|
||||
|
||||
```yaml
|
||||
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
|
||||
metadata:
|
||||
winget:
|
||||
processor: dscv3
|
||||
resources:
|
||||
- name: Get FancyZones settings
|
||||
type: Microsoft.PowerToys/FancyZonesSettings
|
||||
properties: {}
|
||||
```
|
||||
|
||||
### Export current state
|
||||
|
||||
Export the current configuration state. The output is identical to the `get`
|
||||
operation.
|
||||
|
||||
**Direct execution:**
|
||||
|
||||
```powershell
|
||||
# Export current settings for a module.
|
||||
PowerToys.DSC.exe export --resource 'settings' --module <ModuleName>
|
||||
```
|
||||
|
||||
### Set desired state
|
||||
|
||||
Apply a configuration to a module, updating only the properties that differ
|
||||
from the desired state.
|
||||
|
||||
**Direct execution:**
|
||||
|
||||
```powershell
|
||||
# Set desired configuration for a module.
|
||||
$input = '{
|
||||
"settings": {
|
||||
"properties": {
|
||||
"keepDisplayOn": true,
|
||||
"mode": 1
|
||||
},
|
||||
"name": "Awake",
|
||||
"version": "0.0.1"
|
||||
}
|
||||
}'
|
||||
PowerToys.DSC.exe set --resource 'settings' --module Awake --input $input
|
||||
```
|
||||
|
||||
**DSC configuration:**
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
**WinGet configuration:**
|
||||
|
||||
```yaml
|
||||
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
|
||||
metadata:
|
||||
winget:
|
||||
processor: dscv3
|
||||
resources:
|
||||
- name: Install and configure 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
|
||||
fancyzones_displayOrWorkAreaChange_moveWindows: true
|
||||
name: FancyZones
|
||||
version: 1.0
|
||||
```
|
||||
|
||||
### Test desired state
|
||||
|
||||
Verify whether the current configuration matches the desired state.
|
||||
|
||||
**Direct execution:**
|
||||
|
||||
```powershell
|
||||
# Test if current state matches desired state.
|
||||
$input = '{
|
||||
"settings": {
|
||||
"properties": {
|
||||
"keepDisplayOn": true,
|
||||
"mode": 1
|
||||
},
|
||||
"name": "Awake",
|
||||
"version": "0.0.1"
|
||||
}
|
||||
}'
|
||||
PowerToys.DSC.exe test --resource 'settings' --module Awake --input $input
|
||||
```
|
||||
|
||||
The output includes an `_inDesiredState` property indicating whether the
|
||||
configuration matches (`true`) or differs (`false`).
|
||||
|
||||
**DSC configuration:**
|
||||
|
||||
```yaml
|
||||
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
|
||||
resources:
|
||||
- name: Test Awake configuration
|
||||
type: Microsoft.PowerToys/AwakeSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
keepDisplayOn: true
|
||||
mode: 1
|
||||
name: Awake
|
||||
version: 0.0.1
|
||||
```
|
||||
|
||||
### Get schema
|
||||
|
||||
Generate the JSON schema for a module's settings, describing all configurable
|
||||
properties and their types.
|
||||
|
||||
**Direct execution:**
|
||||
|
||||
```powershell
|
||||
# Get JSON schema for a module.
|
||||
PowerToys.DSC.exe schema --resource 'settings' --module Awake
|
||||
|
||||
# Format for readability.
|
||||
PowerToys.DSC.exe schema --resource 'settings' --module Awake `
|
||||
| ConvertFrom-Json | ConvertTo-Json -Depth 10
|
||||
```
|
||||
|
||||
### Generate manifest
|
||||
|
||||
Create a DSC resource manifest file for one or all modules.
|
||||
|
||||
**Direct execution:**
|
||||
|
||||
```powershell
|
||||
# Generate manifest for a specific module.
|
||||
$outputDir = "C:\manifests"
|
||||
PowerToys.DSC.exe manifest --resource 'settings' --module Awake `
|
||||
--outputDir $outputDir
|
||||
|
||||
# Generate manifests for all modules.
|
||||
PowerToys.DSC.exe manifest --resource 'settings' --outputDir $outputDir
|
||||
|
||||
# Print manifest to console (omit --outputDir).
|
||||
PowerToys.DSC.exe manifest --resource 'settings' --module Awake
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1 - Enable and configure FancyZones
|
||||
|
||||
This example enables FancyZones and configures window dragging behavior using
|
||||
direct execution.
|
||||
|
||||
```powershell
|
||||
# Get current FancyZones settings.
|
||||
$current = PowerToys.DSC.exe get --resource 'settings' --module FancyZones `
|
||||
| ConvertFrom-Json
|
||||
|
||||
# Modify settings.
|
||||
$desired = @{
|
||||
settings = @{
|
||||
properties = @{
|
||||
fancyzones_shiftDrag = $true
|
||||
fancyzones_mouseSwitch = $true
|
||||
fancyzones_displayOrWorkAreaChange_moveWindows = $true
|
||||
}
|
||||
name = "FancyZones"
|
||||
version = "1.0"
|
||||
}
|
||||
} | ConvertTo-Json -Depth 10 -Compress
|
||||
|
||||
# Apply configuration.
|
||||
PowerToys.DSC.exe set --resource 'settings' --module FancyZones `
|
||||
--input $desired
|
||||
```
|
||||
|
||||
### Example 2 - Configure multiple utilities with DSC
|
||||
|
||||
This example configures multiple PowerToys utilities in a single DSC
|
||||
configuration.
|
||||
|
||||
```yaml
|
||||
# powertoys-multi.dsc.yaml
|
||||
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
|
||||
resources:
|
||||
- name: Enable PowerToys utilities
|
||||
type: Microsoft.PowerToys/AppSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
Enabled:
|
||||
Awake: true
|
||||
FancyZones: true
|
||||
PowerRename: true
|
||||
ColorPicker: true
|
||||
name: App
|
||||
version: 1.0
|
||||
|
||||
- name: Configure Awake
|
||||
type: Microsoft.PowerToys/AwakeSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
keepDisplayOn: true
|
||||
mode: 1
|
||||
name: Awake
|
||||
version: 0.0.1
|
||||
|
||||
- name: Configure ColorPicker
|
||||
type: Microsoft.PowerToys/ColorPickerSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
changecursor: true
|
||||
copiedcolorrepresentation: "HEX"
|
||||
name: ColorPicker
|
||||
version: 1.0
|
||||
```
|
||||
|
||||
### Example 3 - Install and configure with WinGet
|
||||
|
||||
This example installs PowerToys and applies configuration using WinGet.
|
||||
|
||||
```yaml
|
||||
# winget-powertoys-setup.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
|
||||
ensure: Present
|
||||
|
||||
- name: Configure general settings
|
||||
type: Microsoft.PowerToys/AppSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
run_elevated: true
|
||||
startup: true
|
||||
theme: "dark"
|
||||
name: App
|
||||
version: 1.0
|
||||
|
||||
- name: Configure FancyZones
|
||||
type: Microsoft.PowerToys/FancyZonesSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
fancyzones_shiftDrag: true
|
||||
fancyzones_zoneSetChange_moveWindows: true
|
||||
name: FancyZones
|
||||
version: 1.0
|
||||
|
||||
- name: Configure ImageResizer
|
||||
type: Microsoft.PowerToys/ImageResizerSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
ImageResizerSizes:
|
||||
- Name: Small
|
||||
Width: 854
|
||||
Height: 480
|
||||
Unit: Pixel
|
||||
Fit: Fit
|
||||
- Name: Medium
|
||||
Width: 1920
|
||||
Height: 1080
|
||||
Unit: Pixel
|
||||
Fit: Fit
|
||||
name: ImageResizer
|
||||
version: 1.0
|
||||
```
|
||||
|
||||
Apply the configuration:
|
||||
|
||||
```powershell
|
||||
winget configure winget-powertoys-setup.yaml
|
||||
```
|
||||
|
||||
### Example 4 - Test configuration drift
|
||||
|
||||
This example tests whether the current configuration matches the desired
|
||||
state.
|
||||
|
||||
```powershell
|
||||
# Define desired state.
|
||||
$desired = @{
|
||||
settings = @{
|
||||
properties = @{
|
||||
keepDisplayOn = $true
|
||||
mode = 1
|
||||
}
|
||||
name = "Awake"
|
||||
version = "0.0.1"
|
||||
}
|
||||
} | ConvertTo-Json -Depth 10 -Compress
|
||||
|
||||
# Test for drift.
|
||||
$result = PowerToys.DSC.exe test --resource 'settings' --module Awake `
|
||||
--input $desired | ConvertFrom-Json
|
||||
|
||||
if ($result._inDesiredState) {
|
||||
Write-Host "Configuration is in desired state"
|
||||
} else {
|
||||
Write-Host "Configuration has drifted from desired state"
|
||||
|
||||
# Apply configuration.
|
||||
PowerToys.DSC.exe set --resource 'settings' --module Awake `
|
||||
--input $desired
|
||||
}
|
||||
```
|
||||
|
||||
### Example 5 - Export all module configurations
|
||||
|
||||
This example exports configuration for all modules.
|
||||
|
||||
```powershell
|
||||
# Get list of all modules.
|
||||
$modules = PowerToys.DSC.exe modules --resource 'settings'
|
||||
|
||||
# Export each module's configuration.
|
||||
$configurations = @{}
|
||||
foreach ($module in $modules) {
|
||||
$config = PowerToys.DSC.exe export --resource 'settings' `
|
||||
--module $module | ConvertFrom-Json
|
||||
$configurations[$module] = $config
|
||||
}
|
||||
|
||||
# Save to file.
|
||||
$configurations | ConvertTo-Json -Depth 10 `
|
||||
| Out-File "powertoys-backup.json"
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [PowerToys DSC Overview][02]
|
||||
- [Module Documentation][01]
|
||||
- [WinGet Configuration][03]
|
||||
|
||||
<!-- Link reference definitions -->
|
||||
[01]: ./modules/
|
||||
[02]: ./overview.md
|
||||
[03]: https://learn.microsoft.com/windows/package-manager/configuration/
|
||||
Reference in New Issue
Block a user