Validate and test DSC resources

The Validate Resource feature in WinGet Studio helps you discover DSC (Desired State Configuration) resources, explore their properties, and test their operations before adding them to configurations. This tutorial walks you through using the resource validator to work with both Microsoft DSC 3.0 and PowerShell DSC 2.0 resources.

Prerequisites

Before you begin, ensure you have:

• WinGet Studio installed from the GitHub releases page
• Windows Package Manager (WinGet) installed
• PowerShell 7 or later for working with Microsoft DSC 3.x resources
• Administrator privileges for certain resource operations

To install PowerShell 7 if needed:

winget install Microsoft.PowerShell

What you'll learn

In this tutorial, you'll learn how to:

• Navigate to the Validate Resource page
• Search for and select DSC resources
• View resource schemas and properties
• Use the Get, Set, and Test operations
• Work with Microsoft DSC 3.0 resources
• Work with PowerShell DSC 2.0 resources
• Understand resource requirements and dependencies

Understanding DSC resource operations

DSC resources provide standard methods for managing system components:

• Get: Retrieves the current state without making changes
• Set: Applies the desired state to the system
• Test: Checks if the system is in the desired state

Some Microsoft DSC 3.0 resources also support Export, which generates configurations from the current system state. This feature is not yet implemented in WinGet Studio.

For more information about resource types, see Understanding DSC resources.

Launching the resource validator

When you launch WinGet Studio, the Home screen displays two main options:

Select Validate Resource to open the resource validation page.

The Validate Resource page provides tools to discover resources, explore their settings, and test their operations.

Discovering DSC resource versions

DSC resources come in three versions:

• PowerShell DSC 1.1: Original PowerShell DSC platform
• PowerShell DSC 2.0: Enhanced PowerShell DSC with class-based resources
• Microsoft DSC 3.0: Modern cross-platform DSC with command-based resources

This tutorial focuses on Microsoft DSC 3.0 and PowerShell DSC 2.0 resources, as these are the most commonly used with WinGet Configuration files.

Searching for resources

WinGet Studio searches both locally installed DSC resources and resources available in the PowerShell Gallery.

Search for Microsoft DSC 3.0 resources

Type "winget" in the Search DSC resources field. WinGet Studio displays matching resources:

The search results display:

• Left side: Resource name and version number
• Right side: Source indicator (LocalDscV3 for local Microsoft DSC 3.0 resources)

For resources from PowerShell Gallery, the source shows PSGallery.

Select a resource

Select Microsoft.WinGet.DSC/WinGetPackage from the dropdown list.

Viewing resource information

After selecting a resource, click the ℹ️ icon to the right of the resource input field.

WinGet Studio displays the settings exposed by the resource.

Understanding resource schemas

Microsoft DSC 3.0 resources use JSON schemas to define properties and default values. Click View JSON schema under the Code column to see the schema definition.

The schema helps you understand property data types, valid values, and requirements.

Exploring property definitions

Scroll through the schema to find specific properties. For example, the installMode property shows it's an enumeration with specific valid values:

Switching between views

Click View to return to the settings display.

Select Summary view to see the simplified settings overview.

Working with resource settings

Copy default settings

Click Copy as YAML to copy the default properties and values to your clipboard. A notification appears confirming the copy operation.

Paste and configure settings

Click in the Settings editor and paste the YAML (Ctrl+V). The editor displays all available settings with their default values.

Configure required properties

For the Microsoft.WinGet.DSC/WinGetPackage resource, the most important properties are:

• id: The WinGet package identifier
• source: The WinGet source where the package is available

Remove unnecessary settings and configure the required ones:

id: Microsoft.AppInstaller
source: winget

Testing resource operations

Using the Get operation

The Get operation retrieves the current state without making changes. Many resources require specific settings to return results. For Microsoft.WinGet.DSC/WinGetPackage, the id property is required.

Click Get to retrieve the current state.

WinGet Studio displays a progress indicator while the operation runs. When complete, the results show the current state:

The results include additional properties beyond what you specified, providing a complete picture of the resource's current state.

Using the Test operation

The Test operation checks if the system is in the desired state. DSC may perform a synthetic test by calling Get and comparing the results against your desired state configuration.

Click Test to check the desired state.

When the operation completes, a message in the top-right corner indicates whether the system is in the desired state:

To see what happens when the system is not in the desired state, add an incorrect value to the settings:

id: Microsoft.AppInstaller
source: winget
version: "0"

Run Test again to see the "not in desired state" result:

Using the Set operation

The Set operation applies the desired state to the system.

Testing Set with a different resource

To demonstrate the Set operation safely, use the Microsoft.WinGet/UserSettingsFile resource instead:

1. Search for and select Microsoft.WinGet/UserSettingsFile
2. Click the ℹ️ button to view resource information
3. Review the JSON schema to understand the required settings property
4. Configure the settings property in the editor
5. Click Get to see current WinGet settings

The Get operation returns your current WinGet configuration:

Modifying WinGet settings

To experiment with WinGet settings, try configuring the progress bar and Sixel support:

settings:
  visual:
    progressBar: rainbow
    enableSixels: true
  $schema: https://aka.ms/winget-settings.schema.json

Valid progressBar values include:

• accent
• rainbow
• retro
• sixel
• disabled

For more settings options, see the WinGet Settings Schema.

The action property in the resource determines whether to:

• Partial: Set only the specified values
• Full: Perform a complete overwrite with your settings

After configuring your desired settings, click Set to apply them.

To verify the changes, run a WinGet command that displays visual elements:

winget show GitHub.GitHubDesktop

This command shows the modified progress bar and, if supported, a Sixel icon:

Working with PowerShell DSC 2.0 resources

PowerShell DSC 2.0 resources are implemented in PowerShell modules and are available from the PowerShell Gallery. WinGet Studio can show their settings even if the module isn't installed, but you must install the module to execute Get, Set, or Test operations.

Checking for installed modules

Verify if the Microsoft.Windows.Settings module is installed:

Get-DSCResource -Module Microsoft.Windows.Settings

If the module isn't installed, you can install it using PowerShellGet or PSResourceGet:

# Using PowerShellGet (PowerShell 5.1+)
Install-Module Microsoft.Windows.Settings -Scope CurrentUser
# Using PSResourceGet (PowerShell 7+)
Install-PSResource Microsoft.Windows.Settings -Scope CurrentUser

Searching for PowerShell DSC resources

Type "windowssettings" in the resource search field. The results show PowerShell DSC resources from the PowerShell Gallery:

The source indicator shows PSGallery instead of LocalDscV3.

Viewing PowerShell DSC resource properties

Click the ℹ️ button to view resource information. PowerShell DSC 2.0 resources display differently than Microsoft DSC 3.0 resources:

Instead of JSON schema links, the Code column shows extracted PowerShell code from the resource definition.

Switch to Code View to see the PowerShell code that defines the resource properties:

The code view helps identify:

• Property names and types
• Default values
• Required properties (marked with [Key])
• Properties that should not be set

For the WindowsSettings resource, the $SID property is marked as a key property that should not be manually set.

Testing PowerShell DSC resources

Click Get to retrieve the current Windows settings. The results include:

• SystemColorMode
• AppColorMode
• TaskbarAlignment
• DeveloperMode state

The SID property returns as a blank value, as expected.

Copy the results to the settings editor and remove the SID line before making changes.

Applying PowerShell DSC settings

You can modify other properties without requiring elevation. For example, change the AppColorMode to Dark:

SystemColorMode: Dark
AppColorMode: Dark
TaskbarAlignment: Left

Click Set to apply the changes. Some changes may require restarting applications to take full effect.

Next steps

Now that you understand how to validate and test DSC resources:

• Create your first configuration using the resources you've explored
• Understand DSC resource concepts in more depth
• Learn about configuration versions and format differences
• Customize exported configurations with parameters and dependencies

Troubleshooting

Module not found errors

If you encounter "module not found" errors when testing PowerShell DSC resources:

1. Verify the module is installed:

   # Using PowerShellGet (PowerShell 5.1+)
   Get-Module -ListAvailable -Name <ModuleName>
   
   # Using PSResourceGet (PowerShell 7+)
   Get-PSResource -Name <ModuleName>
   

2. Install the module if missing:

   # Using PowerShellGet (PowerShell 5.1+)
   Install-Module <ModuleName> -Scope CurrentUser
   
   # Using PSResourceGet (PowerShell 7+)
   Install-PSResource <ModuleName> -Scope CurrentUser
   

Permission denied errors

Some resources require elevated permissions. If you encounter access denied errors:

1. Launch WinGet Studio as administrator
2. Or use the CLI with elevated privileges

Resource not found errors

If WinGet Studio cannot find a resource you're searching for:

1. Navigate to Settings > Resources
2. Click Clear cache to refresh the resource catalog
3. Search for the resource again

For more information about resource discovery, see Understanding DSC resources.

Related content

• Get started with WinGet Studio
• Understanding DSC resources
• WinGet Configuration versions
• Customize exported configurations
• WinGet Configuration documentation