mirror of
https://github.com/microsoft/PowerToys.git
synced 2026-04-03 09:46:54 +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
238
doc/dsc/modules/Workspaces.md
Normal file
238
doc/dsc/modules/Workspaces.md
Normal file
@@ -0,0 +1,238 @@
|
||||
---
|
||||
description: DSC configuration reference for PowerToys Workspaces module
|
||||
ms.date: 10/18/2025
|
||||
ms.topic: reference
|
||||
title: Workspaces Module
|
||||
---
|
||||
|
||||
# Workspaces Module
|
||||
|
||||
## Synopsis
|
||||
|
||||
Manages configuration for the Workspaces utility, which launches application sets and arranges windows.
|
||||
|
||||
## Description
|
||||
|
||||
The `Workspaces` module configures PowerToys Workspaces, a utility that allows
|
||||
you to save and restore sets of applications with their window positions. It
|
||||
enables you to quickly switch between different work contexts by launching and
|
||||
arranging multiple applications at once.
|
||||
|
||||
## Properties
|
||||
|
||||
The Workspaces module supports the following configurable properties:
|
||||
|
||||
### LaunchHotkey
|
||||
|
||||
Sets the keyboard shortcut to launch the Workspaces editor.
|
||||
|
||||
**Type:** object
|
||||
**Properties:**
|
||||
|
||||
- `win` (boolean) - Windows key modifier
|
||||
- `ctrl` (boolean) - Ctrl key modifier
|
||||
- `alt` (boolean) - Alt key modifier
|
||||
- `shift` (boolean) - Shift key modifier
|
||||
- `code` (integer) - Virtual key code
|
||||
- `key` (string) - Key name
|
||||
|
||||
**Default:** `Win+Shift+;` (VK code 186)
|
||||
|
||||
### MoveExistingWindows
|
||||
|
||||
Controls whether existing application windows are moved when launching a workspace.
|
||||
|
||||
**Type:** boolean
|
||||
**Default:** `false`
|
||||
|
||||
### SpanZonesAcrossMonitors
|
||||
|
||||
Controls whether workspace zones can span across multiple monitors.
|
||||
|
||||
**Type:** boolean
|
||||
**Default:** `false`
|
||||
|
||||
## Examples
|
||||
|
||||
### Example 1 - Configure launch hotkey with direct execution
|
||||
|
||||
This example sets a custom hotkey to launch the Workspaces editor.
|
||||
|
||||
```powershell
|
||||
$config = @{
|
||||
settings = @{
|
||||
properties = @{
|
||||
LaunchHotkey = @{
|
||||
win = $true
|
||||
ctrl = $true
|
||||
alt = $false
|
||||
shift = $false
|
||||
code = 87
|
||||
key = "W"
|
||||
}
|
||||
}
|
||||
name = "Workspaces"
|
||||
version = "1.0"
|
||||
}
|
||||
} | ConvertTo-Json -Depth 10 -Compress
|
||||
|
||||
PowerToys.DSC.exe set --resource 'settings' --module Workspaces --input $config
|
||||
```
|
||||
|
||||
### Example 2 - Configure window behavior with DSC
|
||||
|
||||
This example enables moving existing windows when launching workspaces.
|
||||
|
||||
```bash
|
||||
dsc config set --file workspaces-behavior.dsc.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
# workspaces-behavior.dsc.yaml
|
||||
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
|
||||
resources:
|
||||
- name: Configure Workspaces window behavior
|
||||
type: Microsoft.PowerToys/WorkspacesSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
MoveExistingWindows: true
|
||||
SpanZonesAcrossMonitors: false
|
||||
name: Workspaces
|
||||
version: 1.0
|
||||
```
|
||||
|
||||
### Example 3 - Install and configure with WinGet
|
||||
|
||||
This example installs PowerToys and configures Workspaces.
|
||||
|
||||
```bash
|
||||
winget configure winget-workspaces.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
# winget-workspaces.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 Workspaces
|
||||
type: Microsoft.PowerToys/WorkspacesSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
LaunchHotkey:
|
||||
win: true
|
||||
ctrl: false
|
||||
alt: false
|
||||
shift: true
|
||||
code: 186
|
||||
key: ";"
|
||||
MoveExistingWindows: true
|
||||
name: Workspaces
|
||||
version: 1.0
|
||||
```
|
||||
|
||||
### Example 4 - Multi-monitor setup
|
||||
|
||||
This example configures for multi-monitor workspace management.
|
||||
|
||||
```bash
|
||||
dsc config set --file workspaces-multimonitor.dsc.yaml
|
||||
```
|
||||
|
||||
```yaml
|
||||
# workspaces-multimonitor.dsc.yaml
|
||||
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
|
||||
resources:
|
||||
- name: Multi-monitor configuration
|
||||
type: Microsoft.PowerToys/WorkspacesSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
SpanZonesAcrossMonitors: true
|
||||
MoveExistingWindows: true
|
||||
name: Workspaces
|
||||
version: 1.0
|
||||
```
|
||||
|
||||
### Example 5 - Simple hotkey
|
||||
|
||||
This example sets a simple single-key hotkey combination.
|
||||
|
||||
```powershell
|
||||
$config = @{
|
||||
settings = @{
|
||||
properties = @{
|
||||
LaunchHotkey = @{
|
||||
win = $true
|
||||
ctrl = $false
|
||||
alt = $true
|
||||
shift = $false
|
||||
code = 192
|
||||
key = "~"
|
||||
}
|
||||
}
|
||||
name = "Workspaces"
|
||||
version = "1.0"
|
||||
}
|
||||
} | ConvertTo-Json -Depth 10 -Compress
|
||||
|
||||
PowerToys.DSC.exe set --resource 'settings' --module Workspaces --input $config
|
||||
```
|
||||
|
||||
## Use cases
|
||||
|
||||
### Development environments
|
||||
|
||||
Configure for quick switching between development workspaces:
|
||||
|
||||
```yaml
|
||||
resources:
|
||||
- name: Development workspace
|
||||
type: Microsoft.PowerToys/WorkspacesSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
MoveExistingWindows: true
|
||||
SpanZonesAcrossMonitors: true
|
||||
name: Workspaces
|
||||
version: 1.0
|
||||
```
|
||||
|
||||
### Single monitor usage
|
||||
|
||||
Configure for single-monitor workflow:
|
||||
|
||||
```yaml
|
||||
resources:
|
||||
- name: Single monitor setup
|
||||
type: Microsoft.PowerToys/WorkspacesSettings
|
||||
properties:
|
||||
settings:
|
||||
properties:
|
||||
SpanZonesAcrossMonitors: false
|
||||
MoveExistingWindows: false
|
||||
name: Workspaces
|
||||
version: 1.0
|
||||
```
|
||||
|
||||
## See also
|
||||
|
||||
- [Settings Resource][01]
|
||||
- [PowerToys DSC Overview][02]
|
||||
- [ColorPicker Module][03] - For additional PowerToys configuration
|
||||
- [PowerToys Workspaces Documentation][04]
|
||||
|
||||
<!-- Link reference definitions -->
|
||||
[01]: ../settings-resource.md
|
||||
[02]: ../overview.md
|
||||
[03]: ./ColorPicker.md
|
||||
[04]: https://learn.microsoft.com/windows/powertoys/workspaces
|
||||
Reference in New Issue
Block a user