Customize exported configuration files

November 7, 2025 · View on GitHub

WinGet Studio makes it easy to create and export configuration files for system setup and management. Once you export a configuration, you might want to customize it for specific needs, such as adding parameters, adjusting dependencies, or modifying resource properties. This guide shows you how to understand and customize exported configuration files effectively.

Understanding exported configurations

When you export a configuration from WinGet Studio, it generates a Microsoft DSC 3.x format file in YAML. The exported file includes:

  • Schema declaration: Points to the Microsoft DSC 3.x schema
  • Metadata: Information about the configuration (e.g., created by WinGet Studio)
  • Resources: The list of resource instances you configured in WinGet Studio

Example exported configuration

$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
metadata:
  Microsoft.WinGet.Studio:
    version: 0.1.0
resources:
  - name: Install Git
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: Git Package
          type: Microsoft.WinGet.DSC/WinGetPackage
          properties:
            id: Git.Git
            source: winget

Common customizations

Adding parameters

Parameters make your configuration reusable across different environments. You can add parameters to customize values without modifying the configuration logic.

Add a parameters section:

$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
parameters:
  packageId:
    type: string
    defaultValue: Git.Git
    metadata:
      description: The WinGet package identifier to install
  packageSource:
    type: string
    defaultValue: winget
    allowedValues:
      - winget
      - msstore
resources:
  - name: Install Package
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: WinGet Package
          type: Microsoft.WinGet.DSC/WinGetPackage
          properties:
            id: "[parameters('packageId')]"
            source: "[parameters('packageSource')]"

Using parameters:

Create a parameters.json file:

{
  "parameters": {
    "packageId": "Microsoft.VisualStudioCode",
    "packageSource": "winget"
  }
}

Apply with parameters:

dsc config set --file configuration.dsc.yaml --parameters-file parameters.json

Modifying dependencies

Dependencies ensure resources are processed in the correct order. You can add or modify the dependsOn property to control execution sequence.

Add dependencies:

resources:
  - name: Install PowerShell 7
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: PowerShell Package
          type: Microsoft.WinGet.DSC/WinGetPackage
          properties:
            id: Microsoft.PowerShell
            source: winget
  
  - name: Install PowerShell Module
    type: Microsoft.Windows/WindowsPowerShell
    dependsOn:
      - "[resourceId('Microsoft.Windows/WindowsPowerShell', 'Install PowerShell 7')]"
    properties:
      resources:
        - name: Az Module
          type: PSDesiredStateConfiguration/PSModule
          properties:
            Name: Az
            Ensure: Present

The resourceId() function creates a unique identifier for the dependency reference.

Adding metadata

Metadata helps document your configuration and can be used by tools for additional context.

Add custom metadata:

metadata:
  Microsoft.WinGet.Studio:
    version: 0.1.0
  author: Your Name
  description: Development environment setup
  created: 2025-11-04
  tags:
    - development
    - setup
    - automation

Modifying resource properties

You can adjust resource properties to fine-tune behavior.

Example - Adding retry logic:

resources:
  - name: Install Package
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: Git Package
          type: Microsoft.WinGet.DSC/WinGetPackage
          properties:
            id: Git.Git
            source: winget
            # Add version specification
            version: 2.42.0

Using variables

Variables help avoid repetition and make configurations more maintainable.

Add variables section:

variables:
  commonSource: winget
  packageVersion: 1.0.0
  installPath: C:\Tools
resources:
  - name: Install Tool
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: Tool Package
          type: Microsoft.WinGet.DSC/WinGetPackage
          properties:
            id: SomeTool
            source: "[variables('commonSource')]"

Conditional resource inclusion

Use parameters to conditionally include resources.

Example - Optional features:

parameters:
  installGit:
    type: bool
    defaultValue: true
  installVSCode:
    type: bool
    defaultValue: false
resources:
  - name: Install Git
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: Git Package
          type: Microsoft.WinGet.DSC/WinGetPackage
          properties:
            id: Git.Git
            source: winget
            _exist: "[parameters('installGit')]"

Best practices for customization

Document your changes

Add comments to explain customizations:

# Development tools configuration
# Author: Team Name
# Last updated: 2025-11-04
# Purpose: Setup development environment with Git, VS Code, and PowerShell tools
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json

Use descriptive names

Choose clear, descriptive names for resources:

# ❌ Avoid generic names
- name: Package 1
  type: Microsoft.Windows/WindowsPowerShell

# ✅ Use descriptive names
- name: Install Git for Version Control
  type: Microsoft.Windows/WindowsPowerShell

Validate after customization

Always validate your configuration after making changes:

# Validate syntax and structure
dsc config test --file configuration.dsc.yaml

# Check for errors
dsc config validate --file configuration.dsc.yaml

Version control your configurations

Store configurations in version control to track changes:

git add configuration.dsc.yaml parameters.json
git commit -m "Add PowerShell 7 dependency to module installation"

Test in non-production first

Test customized configurations in a safe environment before production:

# Test in a virtual machine or dev environment
dsc config test --file configuration.dsc.yaml --parameters-file dev-params.json

# Verify with whatif (when supported)
dsc config set --file configuration.dsc.yaml --what-if

Modularize complex configurations

Break down large configurations into smaller, focused files:

# base-tools.dsc.yaml - Core development tools
resources:
  - name: Install Git
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: Git Package
          type: Microsoft.WinGet.DSC/WinGetPackage
          properties:
            id: Git.Git
            source: winget

# dev-environment.dsc.yaml - Main configuration
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json
resources:
  - name: Base Tools
    type: Microsoft.DSC/Include
    properties:
      configurationFile: ./base-tools.dsc.yaml
  - name: IDE Setup
    type: Microsoft.DSC/Include
    properties:
      configurationFile: ./ide-tools.dsc.yaml

Handling module dependencies

Note

Automated module installation is currently under development in WinGet Studio, which will make it easier to ensure all required PowerShell modules are available when running configurations on different devices.

Until automated module management is available, document required modules:

# Required PowerShell Modules:
# Install-Module Microsoft.WinGet.DSC -Scope CurrentUser
# Install-Module PSDesiredStateConfiguration -Scope CurrentUser
# Install-Module Microsoft.Windows.Settings -Scope CurrentUser
$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json

Creating a module installation configuration

You can create a configuration that installs required modules first:

resources:
  - name: Install Required Modules
    type: Microsoft.Windows/WindowsPowerShell
    properties:
      resources:
        - name: WinGet DSC Module
          type: PSDesiredStateConfiguration/PSModule
          properties:
            Name: Microsoft.WinGet.DSC
            Ensure: Present
        - name: Windows Settings Module
          type: PSDesiredStateConfiguration/PSModule
          properties:
            Name: Microsoft.Windows.Settings
            Ensure: Present
  
  - name: Configure System
    type: Microsoft.Windows/WindowsPowerShell
    dependsOn:
      - "[resourceId('Microsoft.Windows/WindowsPowerShell',
         'Install Required Modules')]"
    properties:
      resources:
        # Your configuration resources here

Troubleshooting customizations

Common issues

Configuration fails after adding parameters

Check that parameter references use the correct syntax:

# ❌ Incorrect
properties:
  id: $packageId

# ✅ Correct
properties:
  id: "[parameters('packageId')]"

Dependencies not working

Ensure resourceId() references match exact resource names and types:

# Resource definition
- name: Install PowerShell
  type: Microsoft.Windows/WindowsPowerShell

# ❌ Incorrect dependency reference
dependsOn:
  - Install PowerShell

# ✅ Correct dependency reference
dependsOn:
  - "[resourceId('Microsoft.Windows/WindowsPowerShell', 'Install PowerShell')]"

YAML syntax errors

Validate YAML structure with proper indentation:

# Use a YAML validator
dsc config test --file configuration.dsc.yaml 2>&1 | Select-String "error"

Getting help

If you encounter issues:

  1. Check the Microsoft DSC 3.x documentation for syntax and function references
  2. Validate your YAML syntax with an online YAML validator
  3. Test individual resources before combining them
  4. Review WinGet Studio logs for detailed error messages

Related content