Microsoft's Desired State Configuration (DSC) is a declarative configuration platform. You can use DSC resources to query, audit, and set the state of a specific component on a system. You can use DSC configuration documents to describe how a system should be configured using one or more resources. This document describes how you can discover the resources available on a machine, invoke those resources directly, and manage a configuration.
Prerequisites
- Install DSC version
3.0.0on a Windows machine. - A terminal emulator, like Windows Terminal.
Discover resources
You can use the dsc resource list command to enumerate the available DSC resources on a machine.
DSC discovers resources by searching the folders in your PATH environment variable for files that
have any of the following suffixes:
.dsc.resource.json.dsc.resource.yaml.dsc.resource.yml
Files with the .dsc.resource.<extension> suffix are DSC resource manifests. They describe both
the settings they enable you to manage and how DSC can invoke them as a command.
Open a terminal and run the following command:
dsc resource list
DSC outputs a table showing the available resources and summary information about each resource.
Type Kind Version Capabilities RequireAdapter Description
------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Microsoft.DSC.Debug/Echo Resource 1.0.0 gs--t---
Microsoft.DSC.Transitional/RunCommandOnSet Resource 0.1.0 gs------ Takes a single-command line to execute on DSC set operation
Microsoft.DSC/Assertion Group 0.1.0 gs--t--- `test` will be invoked for all resources in the supplied configuration.
Microsoft.DSC/Group Group 0.1.0 gs--t--- All resources in the supplied configuration is treated as a group.
Microsoft.DSC/Include Importer 0.1.0 gs--t--- Allows including a configuration file with optional parameter file.
Microsoft.DSC/PowerShell Adapter 0.1.0 gs--t-e- Resource adapter to classic DSC Powershell resources.
Microsoft.Windows/RebootPending Resource 0.1.0 g------- Returns info about pending reboot.
Microsoft.Windows/Registry Resource 0.1.0 gs-w-d-- Manage Windows Registry keys and values
Microsoft.Windows/WMI Adapter 0.1.0 g------- Resource adapter to WMI resources.
Microsoft.Windows/WindowsPowerShell Adapter 0.1.0 gs--t--- Resource adapter to classic DSC Powershell resources in Windows PowerShell.
Microsoft/OSInfo Resource 0.1.0 g-----e- Returns information about the operating system.
Microsoft/Process Resource 0.1.0 gs--t-e- Returns information about running processes.
Together, the columns describe each resource:
The Type column defines the fully qualified type name for a resource. This name identifies the resource on a system and in a configuration document.
The Kind column indicates how you can use the resource.
Adapterindicates that the resource is an adapter resource and enables you to configure components that don't define a DSC resource manifest, like PowerShell DSC (PSDSC) resources.Groupindicates that the resource is a group resource and changes how DSC processes a list of resource instances. Group resources don't directly manage state on a system.Importerindicates that the resource is an importer resource that retrieves a configuration document from an external source to insert into the current configuration document.Resourceindicates that the resource is typical - not an adapter, group, or importer resource.
The Version column indicates the latest discovered version of the resource on the system.
The Capabilities column indicates how the resource is implemented and what you can expect when using it. The table displays the capabilities as flags in the following order, using a
-instead of the appropriate letter if the resource doesn't have a specific capability:gindicates that the resource has thegetcapability.sindicates that the resource has thesetcapability.xindicates that the resource has thesetHandlesExistcapability.windicates that the resource has thewhatIfcapability.tindicates that the resource has thetestcapability.dindicates that the resource has thedeletecapability.eindicates that the resource has theexportcapability.rindicates that the resource has theresolvecapability.
The RequireAdapter column indicates which adapter resource, if any, the resource requires.
The Description column defines a synopsis for the resource.
By default, the dsc resource list command only returns command resources, which always have a
resource manifest. You can use the --adapter option to return the resources for one or more
adapted resources.
Run the following command to return the available adapted resources instead of command resources:
$adaptedResources = dsc resource list --adapter * | ConvertFrom-Json
$adaptedResources |
Group-Object -NoElement -Property requireAdapter |
Format-Table -AutoSize
Count Name
----- ----
27 Microsoft.Windows/WindowsPowerShell
961 Microsoft.Windows/WMI
The output of dsc resource list is saved to the $resources variable as an array of PowerShell
objects. When you first ran the dsc resource list command, the output in the terminal was a table
view. By default, when DSC detects output redirection, it formats the output as JSON. Converting the
JSON into a PowerShell object with the ConvertFrom-Json cmdlet enables you to treat the output
like any other PowerShell object.
The Group-Object cmdlet summarizes the available adapted resources, grouped by the adapter that
they require. The specific count for adapted resources depends on the machine you're using and the
installed PowerShell modules that export any PSDSC resources.
Run the following command to display only the resources available with the
Microsoft.Windows/WindowsPowerShell adapter.
$adaptedResources |
Where-Object requireAdapter -EQ Microsoft.Windows/WindowsPowerShell |
Format-Table -Property type, kind, version, capabilities, description
type kind version capabilities description
---- ---- ------- ------------ -----------
PSDesiredStateConfiguration/Archive resource 1.1 {get, set, test}
PSDesiredStateConfiguration/Environment resource 1.1 {get, set, test}
PSDesiredStateConfiguration/File resource 1.0.0 {get, set, test}
PSDesiredStateConfiguration/Group resource 1.1 {get, set, test}
PSDesiredStateConfiguration/GroupSet resource 1.1 {get, set, test}
PSDesiredStateConfiguration/Log resource 1.1 {get, set, test}
PSDesiredStateConfiguration/Package resource 1.1 {get, set, test}
PSDesiredStateConfiguration/ProcessSet resource 1.1 {get, set, test}
PSDesiredStateConfiguration/Registry resource 1.1 {get, set, test}
PSDesiredStateConfiguration/Script resource 1.1 {get, set, test}
PSDesiredStateConfiguration/Service resource 1.1 {get, set, test}
PSDesiredStateConfiguration/ServiceSet resource 1.1 {get, set, test}
PSDesiredStateConfiguration/SignatureValidation resource 1.0.0 {get, set, test}
PSDesiredStateConfiguration/User resource 1.1 {get, set, test}
PSDesiredStateConfiguration/WaitForAll resource 1.1 {get, set, test}
PSDesiredStateConfiguration/WaitForAny resource 1.1 {get, set, test}
PSDesiredStateConfiguration/WaitForSome resource 1.1 {get, set, test}
PSDesiredStateConfiguration/WindowsFeature resource 1.1 {get, set, test}
PSDesiredStateConfiguration/WindowsFeatureSet resource 1.1 {get, set, test}
PSDesiredStateConfiguration/WindowsOptionalFeature resource 1.1 {get, set, test}
PSDesiredStateConfiguration/WindowsOptionalFeatureSet resource 1.1 {get, set, test}
PSDesiredStateConfiguration/WindowsPackageCab resource 1.1 {get, set, test}
PSDesiredStateConfiguration/WindowsProcess resource 1.1 {get, set, test}
PackageManagement/PackageManagement resource 1.4.8.1 {get, set, test} PackageManagement (a.k.a. OneGet) is a new way to discover and install software packa…
PackageManagement/PackageManagementSource resource 1.4.8.1 {get, set, test} PackageManagement (a.k.a. OneGet) is a new way to discover and install software packa…
PowerShellGet/PSModule resource 2.2.5 {get, set, test} PowerShell module with commands for discovering, installing, updating and publishing …
PowerShellGet/PSRepository resource 2.2.5 {get, set, test} PowerShell module with commands for discovering, installing, updating and publishing …
For more information about the command, see dsc resource list.
Invoke a resource
You can use DSC to directly invoke a resource. When you invoke a resource, you're performing a
specific operation on an instance of the resource. A resource instance is a specific item the
resource represents. The following examples use the Microsoft.Windows/Registry resource to invoke
DSC operations.
First, use the dsc resource list command to see what capabilities the Registry resource has.
$resource = dsc resource list Microsoft.Windows/Registry | ConvertFrom-Json
$resource.capabilities
get
set
whatIf
delete
Together, these capabilities tell us that you can use the Registry command resource to:
- The
getcapability indicates that you can invoke the Get operation to retrieve the current state of an instance. - The
setcapability indicates that you can invoke the Set operation to modify the state of an instance. - The
whatIfcapability indicates that you can invoke the Set operation in what-if mode to see how the resource would change the instance without actually modifying the system. - The
deletecapability indicates that you can invoke the Delete operation to remove an instance from the system.
Get the current state of a resource
You can use the dsc resource get command to retrieve the current state of an instance. Run the
following command to define the data that represents a registry value:
$instance = @{
keyPath = 'HKLM\Software\Microsoft\Windows NT\CurrentVersion'
valueName = 'SystemRoot'
} | ConvertTo-Json
For this example:
- The
keyPathproperty to indicate the path to the registry key that should contain the value you want to manage.keyPathis a required property for theRegistryresource - you always need to specify it. - The
valueNameproperty identifies which registry value to manage for the registry key. - The
_existcanonical property indicates whether the registry value should exist. In this example, the value istrue, which indicates that the instance should exist.
Run the following command to get the current state of the registry key:
dsc resource get --resource $resource.type --input $instance
actualState:
keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
valueName: SystemRoot
valueData:
String: C:\WINDOWS
The output shows that the value is set to the string C:\WINDOWS.
Test whether a resource is in the desired state
Retrieving the current state of a resource is useful, but in practice you more often want to know
whether an instance is in the desired state. The dsc resource test command not only tells you
whether an instance is out of state, but how it's out state.
{!NOTE} Remember that the
Registryresource doesn't have thetestcapability. Fortunately, that doesn't mean that you can't use the Test operation for a resource. When a resource doesn't have thetestcapability, it is indicating that the resource depends on DSC's synthetic test capabilities. DSC itself calls the Get operation for the resource and compares it to the desired state.
Run the following commands to define the desired state of a registry key that doesn't exist and test it.
$desired = @{
keyPath = 'HKCU\dsc\example\key'
_exist = $true
} | ConvertTo-Json
dsc resource test --resource $resource.type --input $desired
desiredState:
keyPath: HKCU\dsc\example\key
_exist: true
actualState:
keyPath: HKCU\dsc\example\key
_exist: false
inDesiredState: false
differingProperties:
- _exist
The output for the command shows you the desired state, actual state, and how they differ. In this
case, the registry key doesn't exist - the _exist property is false when the desired state is
true.
Set the desired state of a resource
You can also directly invoke a resource to set the state for an instance if the resource has the
set capability.
Run the following command to create the registry key:
dsc resource set --resource $resource.type --input $desired
beforeState:
keyPath: HKCU\dsc\example\key
_exist: false
afterState:
keyPath: HKCU\dsc\example\key
changedProperties:
- _exist
The output indicates that the resource created the missing instance.
Manage a configuration
Invoking resources directly is useful, but tedious for defining the desired state of a system. You can define a DSC configuration document to describe a set of resource instances together.
Copy the following code block and save it in a file named example.dsc.config.yaml.
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Example registry key
type: Microsoft.Windows/Registry
properties:
keyPath: HKCU\dsc\example\key
_exist: true
- name: PSDSC resources
type: Microsoft.Windows/WindowsPowerShell
properties:
resources:
- name: DSC_EXAMPLE env variable
type: PSDesiredStateConfiguration/Environment
properties:
Name: DSC_EXAMPLE
Ensure: Present
Value: Set by DSC
The configuration document specifies two resource instances at the top level:
- The
Microsoft.Windows/Registryresource to ensure that a registry key exists. - The
Microsoft.Windows/WindowsPowerShelladapter resource to define PowerShell DSC (PSDSC) resources.
The WindowsPowerShell adapter instance defines a single property, resources, as an array of
resource instances. In this configuration, it defines two instances:
- The first instance uses the
PSRepositoryPSDSC resource from the PowerShellGet module to make sure the PowerShell Gallery is available for use as a repository. - The second instance uses the
PSModulePSDSC resource from the same module to make sure that the Microsoft.WinGet.Client module is installed.
Open a terminal with elevated permissions. PSDSC resources in Windows PowerShell need to run as
administrator. In the elevated terminal, change directory to the folder where you saved the
configuration document as example.dsc.config.yaml. Then run the following command.
dsc config test --file ./example.dsc.config.yaml
metadata:
Microsoft.DSC:
version: 3.0.0
operation: test
executionType: actual
startDatetime: 2025-03-03T17:11:25.726475600-06:00
endDatetime: 2025-03-03T17:11:32.567311800-06:00
duration: PT6.8408362S
securityContext: elevated
results:
- metadata:
Microsoft.DSC:
duration: PT0.1818183S
name: Example registry key
type: Microsoft.Windows/Registry
result:
desiredState:
keyPath: HKCU\dsc\example\key
_exist: true
actualState:
keyPath: HKCU\dsc\example\key
inDesiredState: true
differingProperties: []
- metadata:
Microsoft.DSC:
duration: PT3.0461988S
name: PSDSC resources
type: Microsoft.Windows/WindowsPowerShell
result:
desiredState:
resources:
- name: DSC_EXAMPLE env variable
type: PSDesiredStateConfiguration/Environment
properties:
Name: DSC_EXAMPLE
Ensure: Present
Value: Set by DSC
metadata:
Microsoft.DSC:
context: configuration
actualState:
result:
- name: DSC_EXAMPLE env variable
type: PSDesiredStateConfiguration/Environment
properties:
InDesiredState: false
inDesiredState: false
differingProperties:
- resources
- metadata
messages: []
hadErrors: false
The output shows that:
The
Registryinstance is in the desired state. Earlier in this article, you created the key by invoking the Set operation directly.The adapted
EnvironmentPSDSC resource reports that theDSC_EXAMPLEenvironment variable is not in the desired state.
Run the following command to enforce the desired state on the system.
dsc config set --file ./example.dsc.config.yaml
metadata:
Microsoft.DSC:
version: 3.0.0
operation: set
executionType: actual
startDatetime: 2025-03-03T17:14:15.841393700-06:00
endDatetime: 2025-03-03T17:14:29.136469500-06:00
duration: PT13.2950758S
securityContext: elevated
results:
- metadata:
Microsoft.DSC:
duration: PT0.2633556S
name: Example registry key
type: Microsoft.Windows/Registry
result:
beforeState:
keyPath: HKCU\dsc\example\key
_exist: true
afterState:
keyPath: HKCU\dsc\example\key
changedProperties: null
- metadata:
Microsoft.DSC:
duration: PT8.6601181S
name: PSDSC resources
type: Microsoft.Windows/WindowsPowerShell
result:
beforeState:
result:
- name: DSC_EXAMPLE env variable
type: PSDesiredStateConfiguration/Environment
properties:
ResourceId: null
PsDscRunAsCredential: null
PSComputerName: localhost
ModuleVersion: '1.1'
Value: null
Path: null
ConfigurationName: null
Name: DSC_EXAMPLE
ModuleName: PSDesiredStateConfiguration
SourceInfo: null
DependsOn: null
Ensure: Absent
afterState:
result:
- name: DSC_EXAMPLE env variable
type: PSDesiredStateConfiguration/Environment
properties:
RebootRequired: false
changedProperties:
- result
messages: []
hadErrors: false
To review the actual state of the system, run the dsc config get command:
dsc config get --file ./example.dsc.config.yaml
metadata:
Microsoft.DSC:
version: 3.0.0
operation: get
executionType: actual
startDatetime: 2025-03-03T17:16:39.507848200-06:00
endDatetime: 2025-03-03T17:16:47.734256600-06:00
duration: PT8.2264084S
securityContext: elevated
results:
- metadata:
Microsoft.DSC:
duration: PT0.1739569S
name: Example registry key
type: Microsoft.Windows/Registry
result:
actualState:
keyPath: HKCU\dsc\example\key
- metadata:
Microsoft.DSC:
duration: PT3.9958946S
name: PSDSC resources
type: Microsoft.Windows/WindowsPowerShell
result:
actualState:
result:
- name: DSC_EXAMPLE env variable
type: PSDesiredStateConfiguration/Environment
properties:
ResourceId: null
PsDscRunAsCredential: null
PSComputerName: localhost
ModuleVersion: '1.1'
Value: Set by DSC
Path: null
ConfigurationName: null
Name: DSC_EXAMPLE
ModuleName: PSDesiredStateConfiguration
SourceInfo: null
DependsOn: null
Ensure: Present
messages: []
hadErrors: false
