Winget DSC (Desired State Configuration)

What is Desired State Configuration?

Desired State Configuration (DSC) is a management platform in PowerShell that allows you to define the desired state of your IT infrastructure. It ensures that systems automatically conform to this defined state, maintaining consistency and correcting any deviations. This automation reduces manual intervention, enhances reliability, and ensures uniformity across multiple systems.

Key Features of DSC:

Software Installation: Automatically install or update applications, ensuring users have the necessary tools.
Service Management: Ensure essential services (like antivirus or backup services) are always running.
Configuration Settings: Apply and maintain specific system settings, such as network configurations or security policies.
File Management: Ensure certain files or directories are present and correctly configured.

These tasks help maintain consistency, security, and functionality across user devices with minimal manual intervention.

Differences between PowerShell DSC 2.0 and DSC 3.0

Platform Independence:
- DSC 2.0: Relies on PowerShell and uses PowerShell scripts for configurations 1.
- DSC 3.0: Does not depend on PowerShell and can manage resources using various languages like Bash, Python, and C# 2.
Configuration Management:
- DSC 2.0: Uses Managed Object Format (MOF) files for configuration 1.
- DSC 3.0: Uses JSON or YAML files for configuration documents 2.
Local Configuration Manager:
- DSC 2.0: Includes a Local Configuration Manager (LCM) that runs as a service to apply configurations 1.
- DSC 3.0: Does not include an LCM and is invoked as a command, not running as a service 2.
Cross-Platform Support:
- DSC 2.0: Primarily focused on Windows environments 1.
- DSC 3.0: Designed with cross-platform capabilities, supporting Windows, Linux, and macOS 2.

These updates in DSC 3.0 make it more flexible and versatile, especially for managing diverse environments and using different scripting languages.

WARNING

Please be aaware that DSC 3.0 is not yet feature complete and is still in development.

1: Microsoft Learn - PowerShell DSC Overview
2: Microsoft Learn - DSC v3 Overview

Differences between PowerShell DSC and WinGet DSC

PowerShell Desired State Configuration (DSC) and WinGet DSC are both tools for managing system configurations, but they have some key differences:

Platform Dependency:
- PowerShell DSC: Primarily relies on PowerShell and uses PowerShell scripts to define configurations 1.
- WinGet DSC: Built on top of PowerShell DSC but uses YAML files to define configurations, focusing on managing software installations and settings via the Windows Package Manager 2.
Scope and Usage:
- PowerShell DSC: More comprehensive, managing a wide range of system settings, services, and configurations across different platforms 1.
- WinGet DSC: Specifically designed for managing software installations and configurations on Windows devices 2.

WinGet DSC leverages PowerShell DSC 3.0, allowing it to use advanced features such as the ability to manage configurations using JSON or YAML files. This integration makes it easier to define and enforce software configurations on Windows devices using the Windows Package Manager.

1: Microsoft Learn - DSC v3 Overview
2: Microsoft Dev Blogs - WinGet configuration Preview

How to get started with WinGet DSC

What can be configured with WinGet DSC?

Configruation Settings
- Windows Explorer
- Dark Mode
- Taskbar
Software Installation
- Winget
- MS Store
- Software Configruations
Powershell Scripts
- Whatever you can think of

INFO

Windows Feature installation are not yet supported in WinGet DSC.

How to create a WinGet DSC configuration file

Create a text file and save it with a .dsc.yaml extension.
Open the file in a text editor and add content in the following format:
1. Schema (Defines the structure and properties required to configure a resource.)
2. Properties (Defines the properties of a resource.)
3. Assertions (Defines the conditions that must be met for a configuration to apply.)
  - resources
4. Resources (Defines the resources that are being configured.)
  - resources
5. Configuration Version (Defines the version of the configuration.)

Example Code:

yaml

# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2

properties:
  assertions:
    - resource: Microsoft.Windows.Developer/OsVersion
      directives:
        description: Verify min OS version requirement Windows 11 Version 23H2
        allowPrerelease: true
      settings:
        MinVersion: '10.0.22631'
  resources:
    - resource: Microsoft.WindowsSandbox.DSC/WindowsSandbox
      directives:
        description: Create Windows Sandbox
        allowPrerelease: true
      settings:
        Ensure: Present # Ensure the resource is present
        LogonCommand: >
          # Define a command to run when the sandbox is started
  configurationVersion: 0.2.0

Examle of the above shown WinGet DSC configuration file executing: drawing

How to apply a WinGet DSC configuration file

Open a PowerShell window and use the following code:

powershell

winget configure [filename].dsc.yaml

INFO

Your configuration file does not have to be local, it can be a hosted file. This would allow you to apply a configuration file remotely via intune or other means.

Example of the Microsoft Sandbox WinGet DSC configuration file executing: drawing

Example of a WinGet DSC configuration file with many possible configurations

WARNING

Please be aware that a few configurations need to be run as an administrator (i.e. Installing Powershell Modules).

yaml

# yaml-language-server: $schema=https://aka.ms/configuration-dsc-schema/0.2

properties:
  ########################################################################
  # Windows assertion Section: Defines the conditions that must be met for a configuration to apply
  ########################################################################
  assertions:
    - resource: Microsoft.Windows.Developer/OsVersion
      directives:
        description: Verify min OS version requirement Windows 11 Version 24H2
        allowPrerelease: true
      settings:
        MinVersion: '10.0.26200'
  ########################################################################
  # Windows resources Section: Defines the resources that are being configured
  ########################################################################
  resources:
  ########################################################################
  # Windows Settings: Enable Dark Mode
  ########################################################################
  - resource: Microsoft.Windows.Developer/EnableDarkMode
    directives:
      description: Enable dark mode
      allowPrerelease: true
    settings:
      Ensure: present # [Present, Absent]
      # Use caution when setting `RestartExplorer: true` as this will force explorer to close.
      RestartExplorer: true # Required to apply changes
  ########################################################################
  # Windows Feature: Hyper-V (Code is correct, but there is a bug with the DSC resource which produces the error "Class not registered")
  # https://github.com/microsoft/winget-cli/issues/4264
  ########################################################################
  - resource: PSDscResources/WindowsOptionalFeature
    directives:
      description: Enable Hyper-V
    settings:
      Ensure: present # [Present, Absent]
      Name: Microsoft-Hyper-V-All
  ########################################################################
  # Winget: Install VS-Code & YAML extension
  ########################################################################
  - resource: Microsoft.WinGet.DSC/WinGetPackage
    id: install-vs-code
    directives:
      description: Install Microsoft Visual Studio Code
      allowPrerelease: true
    settings:
      id: Microsoft.VisualStudioCode
      source: winget
      Ensure: Present
  - resource: Microsoft.VSCode.Dsc/VSCodeExtension
    id: install_vscode-yaml
    dependsOn:
      - install-vs-code
    directives:
      description: Install YAML extension for VSCode
      allowPrerelease: true
    settings:
      Name: redhat.vscode-yaml
      Exist: true
  ########################################################################
  # Powershell: Install PowerShell Modules
  ########################################################################
  - resource: PowerShellModule/PSModuleResource
    id: install-microsoft.graph
    directives:
      description: Install MS Graph module
      allowPrerelease: true
    settings:
      Module_Name: microsoft.graph
      Ensure: Present
  ########################################################################
  # MSStore: Install Microsoft Company Portal with Winget
  ########################################################################
  - resource: Microsoft.WinGet.DSC/WinGetPackage
    directives:
      description: Installing Microsoft Company Portal
      allowPrerelease: true
      securityContext: current
    settings:
      id: "9WZDNCRFJ3PZ"
      source: msstore
    id: 9WZDNCRFJ3PZ
  ########################################################################
  # Powershell Script: Check Autostart for OneDrive
  ########################################################################
  - resource: PSDscResources/Script
    id: OneDrive-Autostart
    directives:
      description: Autostart OneDrive
      allowPrerelease: true
    settings:
      GetScript: |
        # Your custom PowerShell code to check app configuration
      TestScript: |
        If( (Get-Item HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Run).property -contains "OneDrive" ){ return $TRUE } else{ return $FALSE }
      SetScript: |
        # PowerShell script commands to install VSCode extensions
        New-ItemProperty -Path "HKCU:\SOFTWARE\Microsoft\Windows\CurrentVersion\Run" -Name "OneDrive" -Value "C:\Program Files\Microsoft OneDrive\OneDrive.exe -background"  
  ########################################################################
  # Configuration Version: Defines the version of the configuration
  ########################################################################
  configurationVersion: 0.2.0

💾 Download from GitHub

Where do I find more information and configurations to use?

I have created a list with a few resources you can use to get further information and keep up to date.

Here you can find more Information regarding DSC 3.0 on which the Winget DSC builds: Microsoft Learn - Powershell DSC 3.0
Here you can find further Information and track issues regarding Winget: GitHub - Windows Package Manager Microsoft Repository
Here you can find a few examples of configuration files and further Information regarding Winget here: GitHub - Windows Package Manager Community Repository
Here you can find more Information regarding DSC on which the Winget DSC builds: GitHub - DSC Community Repository
Here you can find the DSC Resources of the PowerShell Gallery: PowerShell Gallery - DSC
Here you can find community module resources: DSC Community and Resource Kit
With the Reverse DSC tool you can create a DSC configuration from a running machine: Microsoft Dev Blog - Reverse Desired State Configuration: How it works
Here you can find instructions from Microsoft on how to author a configuration file: Microsoft Learn - How to author a WinGet Configuration file
Here you can find sample configurations: GitHub - DevHome Sample Configurations for Specific DSC Resource

Winget DSC (Desired State Configuration) ​

What is Desired State Configuration? ​

Key Features of DSC: ​

Differences between PowerShell DSC 2.0 and DSC 3.0 ​

Differences between PowerShell DSC and WinGet DSC ​

How to get started with WinGet DSC ​

What can be configured with WinGet DSC? ​

How to create a WinGet DSC configuration file ​

How to apply a WinGet DSC configuration file ​

Example of a WinGet DSC configuration file with many possible configurations ​

Where do I find more information and configurations to use? ​