Configurer PowerToys avec Microsoft DSC

PowerToys inclut une implémentation microsoft Desired State Configuration (DSC) v3 via l’outil PowerToys.DSC.exe en ligne de commande, ce qui permet la gestion moderne de la configuration déclarative des PowerToys paramètres.

Aperçu

L’outil PowerToys.DSC.exe en ligne de commande pour PowerToys fournit :

  • Outil de configuration autonome sans dépendances PowerShell
  • Modules de ressources DSC individuels pour chaque PowerToys utilitaire
  • Opérations DSC v3 standard : get, set, test, export, schema, manifest
  • Génération de schéma JSON pour la validation
  • Génération de manifeste DSC pour la découverte de ressources
  • Intégration à WinGet et à d’autres outils d’orchestrateur

Disponible depuis :PowerToys v0.95.0

Prerequisites

  • PowerToys v0.95.0 ou version ultérieure : l’outil PowerToys.DSC.exe est inclus à PowerToys partir de la version 0.95.0

Facultatif : Utilisation des outils d’orchestration

Si vous souhaitez utiliser des outils d’orchestration pour gérer la PowerToys configuration :

  • WinGet v1.6.2631 ou version ultérieure : requis pour WinGet l’intégration des fichiers de configuration. Télécharger à partir de la WinGet page des sorties
  • Microsoft DSC (dsc.exe) v3.1.1 ou version ultérieure : requis pour l’utilisation Microsoft DSC de documents de configuration avec l’outil dsc en ligne de commande. Télécharger depuis la page des versions DSC

Note

Ces outils d’orchestration sont facultatifs. Vous pouvez utiliser PowerToys.DSC.exe directement sans WinGet ou dsc.exe pour la gestion de la configuration autonome.

Emplacement

L’exécutable PowerToys.DSC.exe est installé avec PowerToys:

  • Installation par utilisateur :%LOCALAPPDATA%\PowerToys\PowerToys.DSC.exe
  • Installation à l’échelle de l’ordinateur :%ProgramFiles%\PowerToys\PowerToys.DSC.exe

Vous pouvez ajouter le PowerToys répertoire à votre PATH variable d’environnement pour faciliter l’accès ou utiliser le chemin complet de l’exécutable.

Usage

Microsoft DSC pour PowerToys prend en charge trois schémas d'utilisation :

1. Exécution directe de la ligne de commande

Exécutez des opérations DSC directement à l’aide de l’outil PowerToys.DSC.exe :

# Get current settings for a module
PowerToys.DSC.exe get --resource 'settings' --module Awake

# Set settings 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

# Test if settings match desired state
PowerToys.DSC.exe test --resource 'settings' --module Awake --input $input

2. Microsoft DSC Documents de configuration

Utilisez des documents de configuration standard Microsoft DSC pour définir les PowerToys paramètres :

# 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

Appliquez la configuration à l’aide de l’interface dsc de ligne de commande (le cas échéant) ou par le biais WinGet de la configuration.

3. WinGet Intégration de la configuration

Intégrer la PowerToys configuration à l’installation WinGet du package :

# 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

Appliquer avec WinGet:

winget configure winget-powertoys.yaml

Opérations courantes

Répertorier les modules pris en charge

Répertoriez tous les PowerToys utilitaires qui peuvent être configurés :

PowerToys.DSC.exe modules --resource 'settings'

Obtenir la configuration actuelle

Récupérez l’état actuel des paramètres d’un module :

# Get settings for a specific module
PowerToys.DSC.exe get --resource 'settings' --module FancyZones

# Format output for readability
PowerToys.DSC.exe get --resource 'settings' --module Awake | ConvertFrom-Json | ConvertTo-Json -Depth 10

Appliquer la configuration

Définissez la configuration souhaitée pour un module :

# Define desired configuration (using PowerShell)
$config = @{
    settings = @{
        properties = @{
            fancyzones_shiftDrag = $true
            fancyzones_mouseSwitch = $true
            fancyzones_overrideSnapHotkeys = $true
        }
        name = "FancyZones"
        version = "1.0"
    }
} | ConvertTo-Json -Depth 10 -Compress

# Apply configuration
PowerToys.DSC.exe set --resource 'settings' --module FancyZones --input $config

Configuration de test

Vérifiez si les paramètres actuels correspondent à l’état souhaité :

$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 matches desired state"
} else {
    Write-Host "Configuration has drifted"
}

Générer un schéma JSON

Obtenez le schéma JSON d’un module pour comprendre les propriétés disponibles :

# Get schema for a module
PowerToys.DSC.exe schema --resource 'settings' --module ColorPicker

# Format for readability
PowerToys.DSC.exe schema --resource 'settings' --module ColorPicker | ConvertFrom-Json | ConvertTo-Json -Depth 10

Générer des manifestes DSC

Créez des fichiers manifestes de ressources DSC :

# Generate manifest for a specific module
PowerToys.DSC.exe manifest --resource 'settings' --module Awake --outputDir C:\manifests

# Generate manifests for all modules
PowerToys.DSC.exe manifest --resource 'settings' --outputDir C:\manifests

# Print manifest to console
PowerToys.DSC.exe manifest --resource 'settings' --module FancyZones

Exemples de configuration

Exemple 1 : Configurer FancyZones

# fancyzones-config.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure FancyZones window management
    type: Microsoft.PowerToys/FancyZonesSettings
    properties:
      settings:
        properties:
          fancyzones_shiftDrag: true
          fancyzones_mouseSwitch: false
          fancyzones_overrideSnapHotkeys: true
          fancyzones_displayOrWorkAreaChange_moveWindows: true
          fancyzones_zoneSetChange_moveWindows: true
        name: FancyZones
        version: 1.0

Exemple 2 : Configurer plusieurs utilitaires

# multi-utility-config.dsc.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
  - name: Configure general app settings
    type: Microsoft.PowerToys/AppSettings
    properties:
      settings:
        properties:
          Enabled:
            Awake: true
            FancyZones: true
            PowerRename: true
            ColorPicker: true
          run_elevated: true
          startup: 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

Exemple 3 : Installer et configurer avec WinGet

# complete-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: Enable utilities
    type: Microsoft.PowerToys/AppSettings
    properties:
      settings:
        properties:
          startup: true
          theme: "dark"
        name: App
        version: 1.0
  
  - name: Configure PowerToys Run
    type: Microsoft.PowerToys/PowerLauncherSettings
    properties:
      settings:
        properties:
          maximum_number_of_results: 8
          clear_input_on_launch: true
        name: PowerLauncher
        version: 1.0

Ressources disponibles

Microsoft DSC pour PowerToys fournir des types de ressources individuels pour chaque utilitaire. Le nommage du type de ressource suit le modèle : Microsoft.PowerToys/<UtilityName>Settings

Les ressources courantes sont les suivantes :

  • Microsoft.PowerToys/AppSettings - Paramètres généraux de l’application
  • Microsoft.PowerToys/AlwaysOnTopSettings - Configuration Toujours au-dessus
  • Microsoft.PowerToys/AwakeSettings - Paramètres d’éveil de veille
  • Microsoft.PowerToys/ColorPickerSettings - Paramètres du sélecteur de couleurs
  • Microsoft.PowerToys/FancyZonesSettings - Gestion des fenêtres FancyZones
  • Microsoft.PowerToys/PowerLauncherSettings - PowerToys Paramètres d’exécution
  • Microsoft.PowerToys/PowerRenameSettings - PowerRename : renommer en bloc
  • Et bien d’autres pour chaque PowerToys utilitaire

Pour obtenir la liste complète des ressources et de leurs propriétés, consultez la documentation du développeur.

Utilisation avancée

Configuration de la sauvegarde et de la restauration

Exportez toutes les configurations de module pour la sauvegarde :

# Get list of all modules
$modules = PowerToys.DSC.exe modules --resource 'settings'

# Export each module
$backup = @{}
foreach ($module in $modules) {
    $config = PowerToys.DSC.exe export --resource 'settings' --module $module | ConvertFrom-Json
    $backup[$module] = $config
}

# Save backup
$backup | ConvertTo-Json -Depth 10 | Out-File powertoys-backup.json

# Restore from backup
$restore = Get-Content powertoys-backup.json | ConvertFrom-Json
foreach ($module in $restore.PSObject.Properties.Name) {
    $input = $restore.$module | ConvertTo-Json -Depth 10 -Compress
    PowerToys.DSC.exe set --resource 'settings' --module $module --input $input
}

Migration à partir de PowerShell DSC

Si vous effectuez une migration à partir du module DSC PowerShell (Microsoft.PowerToys.Configure), notez les principales différences suivantes :

  1. Nommage des ressources : PowerShell DSC utilise une ressource unique PowerToysConfigure avec des propriétés imbriquées. Microsoft DSC utilise des ressources individuelles par utilitaire (par exemple, AwakeSettings, FancyZonesSettings)

  2. Format de propriété : Certains noms de propriété peuvent différer légèrement. Utilisez la schema commande pour afficher les propriétés disponibles pour chaque module

  3. Structure de configuration :Microsoft DSC utilise le settings wrapper avec properties, nameet version les champs

  4. Aucune commande PowerShell n’est requise :Microsoft DSC s’exécute autonome sans dépendances PowerShell

Voir aussi

  • Last updated on