Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/microsoft/winget-cli/llms.txt

Use this file to discover all available pages before exploring further.

The WinGet Configuration module provides cmdlets for managing configuration files that define desired state for Windows systems.

​
What is WinGet Configuration?

WinGet Configuration allows you to define system setup and package installations in YAML files. These configuration files can:
  • Install multiple packages in a single operation
  • Configure Windows settings
  • Set up development environments
  • Define desired state configuration
  • Be version controlled and shared across teams

​
Configuration Cmdlets

The Microsoft.WinGet.Configuration module provides three main cmdlets:

Get-WinGetConfiguration

Open and load configuration files

Invoke-WinGetConfiguration

Apply configuration sets to the system

Get-WinGetConfigurationDetails

Retrieve details about configuration units

​
Configuration File Format

Configuration files are written in YAML format with a specific schema: 
properties:
  configurationVersion: 0.2.0
  assertions:
    - resource: Microsoft.Windows.Developer/OsVersion
      directives:
        description: Verify min OS version requirement
      settings:
        MinVersion: '10.0.22000'
  resources:
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      directives:
        description: Install Visual Studio Code
      settings:
        id: Microsoft.VisualStudioCode
        source: winget
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      directives:
        description: Install Git
      settings:
        id: Git.Git
        source: winget

​
Basic Workflow

The typical workflow for using configuration cmdlets:

​
1. Create Configuration File

Create a YAML file defining your desired state: 
properties:
  resources:
    - resource: Microsoft.WinGet.DSC/WinGetPackage
      settings:
        id: Microsoft.PowerToys
        source: winget

​
2. Load Configuration

Load the configuration file into PowerShell: 
$config = Get-WinGetConfiguration -File "C:\config\setup.yaml"

​
3. Get Details (Optional)

Review configuration details before applying: 
Get-WinGetConfigurationDetails -Set $config

​
4. Apply Configuration

Apply the configuration to the system: 
Invoke-WinGetConfiguration -Set $config -AcceptConfigurationAgreements

​
Configuration Resources

Configuration files use DSC resources to define desired state. Common resources include:

​
WinGet Package Resource

Install and manage packages: 
- resource: Microsoft.WinGet.DSC/WinGetPackage
  settings:
    id: Microsoft.PowerToys
    source: winget
    version: 0.70.0  # Optional

​
WinGet Source Resource

Manage package sources: 
- resource: Microsoft.WinGet.DSC/WinGetSource
  settings:
    name: custom-source
    argument: https://example.com/packages
    type: Microsoft.PreIndexed.Package

​
User Settings Resource

Configure WinGet user settings: 
- resource: Microsoft.WinGet.DSC/WinGetUserSettings
  settings:
    settings:
      visual:
        progressBar: rainbow
      telemetry:
        disable: true

​
Working with History

Configuration cmdlets support loading configurations from history: 
# Get all configuration history
$configs = Get-WinGetConfiguration -All

# Get specific configuration from history
$config = Get-WinGetConfiguration -InstanceIdentifier "12345678-1234-1234-1234-123456789012"

​
Error Handling

Handle errors when applying configurations: 
try {
    $config = Get-WinGetConfiguration -File "C:\config\setup.yaml"
    Invoke-WinGetConfiguration -Set $config -AcceptConfigurationAgreements -ErrorAction Stop
    Write-Host "Configuration applied successfully"
}
catch {
    Write-Error "Failed to apply configuration: $_"
}

​
Configuration Parameters

​
Module Path

Specify custom module installation location: 
$config = Get-WinGetConfiguration -File "config.yaml" -ModulePath "C:\CustomModules"

​
Processor Path

Use custom DSC processor: 
$config = Get-WinGetConfiguration -File "config.yaml" -ProcessorPath "C:\DSC\processor.exe"

​
Examples

​
Example 1: Basic Configuration

# Load and apply configuration
$config = Get-WinGetConfiguration -File "setup.yaml"
Invoke-WinGetConfiguration -Set $config -AcceptConfigurationAgreements

​
Example 2: Review Before Applying

# Load configuration
$config = Get-WinGetConfiguration -File "setup.yaml"

# Get details
$details = Get-WinGetConfigurationDetails -Set $config

# Review and apply
$details
Invoke-WinGetConfiguration -Set $config -AcceptConfigurationAgreements

​
Example 3: Apply from History

# Get from history and reapply
$config = Get-WinGetConfiguration -InstanceIdentifier "12345678-1234-1234-1234-123456789012"
Invoke-WinGetConfiguration -Set $config -AcceptConfigurationAgreements

​
Best Practices

  1. Version Control: Store configuration files in version control systems
  2. Test First: Test configurations in development environments before production
  3. Use Assertions: Add assertions to verify prerequisites
  4. Document: Include descriptions in directives for clarity
  5. Modular Files: Break large configurations into smaller, reusable files
  6. Review Details: Use Get-WinGetConfigurationDetails before applying

​
Next Steps

Get-WinGetConfiguration

Learn how to load configuration files

Invoke-WinGetConfiguration

Apply configurations to your system

DSC Resources

Explore available DSC resources

Build docs developers (and LLMs) love

Get started for freeTalk to us