DSC Resources
In Microsoft's Desired State Configuration (DSC) platform, DSC Resources represent a standardized interface for managing the settings of a system. Resources can model components as generic as a file or as specific as an IIS server setting. Resources use a declarative syntax rather than imperative. Instead of specifying how to set a system to the desired state, with DSC you specify what the desired state is. Resources handle the "how" for you.
Resources manage instances of a configurable component. For example, the
PSDscResources/Environment
resource manages environment variables. Each environment variable is a
different instance of the resource. Every resource defines a schema that describes how to validate
and manage an instance of the resource.
DSCv3 supports several kinds of resources:
- A resource defined with a resource manifest is a command-based resource. DSC uses the manifest to determine how to invoke the resource and how to validate the resource instance properties.
- A resource group is a command-based resource with a
resources
property that takes an array of resource instances and processes them. Resource groups may apply special handling to their nested resource instances, like changing the user the resources run as. - A resource provider is a resource group that enables the use of non-command-based resources
with DSCv3. For example, the
DSC/PowerShellGroup
resource provider enables the use of DSC Resources implemented in PowerShell modules.
Resource type names
Resources are identified by their fully qualified type name. The type name is used to specify a
resource in configuration documents and as the value of the --resource
flag when using the
dsc resource *
commands.
The fully qualified type name of a resource uses the following syntax:
<owner>[.<group>][.<area>]/<name>
Every resource must define an owner
and a name
. The group
and area
components enable
organizing resources into related namespaces, like Microsoft.SqlServer/Database
and
Microsoft.SqlServer.Database/Role
.
For more information about type names and how DSC validates them, see DSC Resource fully qualified type name schema reference.
Resource properties
The properties of a resource are the settings and options a user can declare for managing an instance. Resources always have at least one property. Resources define their properties in their schema.
Properties are optional by default. Resources can be invoked directly or declared in a configuration with only the properties that are relevant to the current task or purpose. You don't need to declare every property for an instance. Properties may have default values for their desired state.
Most properties are one of the basic types:
- String properties require the property value to be a set of characters, like
machine
. - Integer properties require the property value to be a number without a fractional part, like
5
. - Boolean properties require the property value to be either
true
orfalse
. - Array properties require the property value to be a list of items. Usually, array properties specify that the values must be of a particular type, like a list of exit code integers or a list of file paths.
Complex properties require the property value to be an object with defined subproperties. The subproperties can be basic or complex, but they're usually a basic type.
Listing resources
You can use DSC to list the available resources with the dsc resource list
command. DSC searches
the PATH
for command-based resources and invokes available resource providers to list their
resources.
By default, the command returns every discovered DSC Resource.
dsc resource list
type version tags description
---- ------- ---- -----------
Test/TestGroup 0.1.0
Microsoft/OSInfo 0.1.0 {os, linux, windows, macos} Returns information about the operating system.
Microsoft.Windows/Registry 0.1.0 {Windows, NT} Registry configuration provider for the Windows Registry
This is a test resource.
DSC/PowerShellGroup 0.1.0 {PowerShell} Resource provider to classic DSC Powershell resources.
DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration.
DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently.
This is a test resource.
DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group.
You can filter the results by a resource's type name, description, and tags. For more information, see dsc resource list
Invoking resources
You can invoke resources directly with the dsc resource *
commands to manage a single instance
through the three DSC operations Get, Test, and Set.
Get operations
Every resource implements the Get operation, which retrieves the actual state of a resource
instance. Use the dsc resource get
command to invoke the operation.
For example, you can use the Microsoft.Windows/Registry
resource to get the actual state for a
registry key value:
'{
"keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion",
"valueName": "SystemRoot"
}' | dsc resource get --resource Microsoft.Windows/Registry
actualState:
$id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
keyPath: HKLM\Software\Microsoft\Windows NT\CurrentVersion
valueName: SystemRoot
valueData:
String: C:\WINDOWS
Test operations
Some resources implement the Test operation. For resources that don't implement the Test operation, DSCv3 can validate an instance's state with a synthetic test. The synthetic test is a strict case-insensitive comparison of the desired and actual values for the instance's properties. Only resources that have advanced or complex validation requirements need to implement the Test operation themselves.
Use the dsc resource test
command to invoke the operation. DSC returns data that includes:
- The desired state for the instance.
- The actual state of the instance.
- Whether the instance is in the desired state.
- The list of properties that aren't in the desired state.
For example, you can test whether a specific registry key exists:
'{
"keyPath": "HKCU\\key\\that\\does\\not\\exist",
}' | dsc resource test --resource Microsoft.Windows/Registry
desiredState:
keyPath: HKCU\key\that\does\not\exist
actualState:
$id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
keyPath: ''
_inDesiredState: false
inDesiredState: false
differingProperties:
- keyPath
Set operations
Most resources implement the Set operation, which enforces the desired state for an instance. When used with DSCv3, the Set operation is idempotent, which means that the resource only invokes the operation when an instance isn't in the desired state. Because the operation is idempotent, invoking it repeatedly is the same as invoking it once. The idempotent model prevents side effects from unnecessarily executing code.
Resources that don't implement the Set operation are assertion resources. You can use assertion resources to retrieve and validate the state of an instance, but you can't use them to enforce a desired state.
Use the dsc resource set
command to invoke the operation. DSC returns data that includes:
- The state of the instance before the operation.
- The state of the instance after the operation.
- The list of properties the operation changed.
For example, you can create a registry key by setting the desired state for a key that doesn't exist.
'{
"keyPath": "HKCU\\example\\key",
"valueName": "Example",
"valueData": { "String": "This is an example." }
}' | dsc resource set --resource Microsoft.Windows/Registry
beforeState:
$id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
keyPath: ''
afterState:
$id: https://developer.microsoft.com/json-schemas/windows/registry/20230303/Microsoft.Windows.Registry.schema.json
keyPath: HKCU\example\key
valueName: Example
valueData:
String: This is an example.
changedProperties:
- keyPath
- valueName
- valueData
Declaring resource instances
DSC Configuration documents enable managing more than one resource or resource instance at a time. Configuration documents declare a collection of resource instances and their desired state. This makes it possible to model complex desired states by composing different resources and instances together, like defining a security baseline for compliance or the settings for a web farm.
A resource instance declaration always includes:
name
- A short, human-readable name for the instance that's unique in the document. This name is used for logging and it helps to document an instance's purpose in the document.type
- The fully qualified type name for the resource to identify the resource DSC should use to manage the instance.properties
- The desired state for the instance. DSC validates the values against the resource's instance schema.
This example configuration document snippet declares an instance of the
Microsoft.Windows/Registry
resource.
$schema: https://schemas.microsoft.com/dsc/2023/08/configuration.schema.json
resources:
- name: example key value
type: Microsoft.Windows/Registry
properties:
keyPath: HKCU\example\key
valueName: Example
valueData:
String: This is an example.
See also
- Anatomy of a command-based DSC Resource to learn about authoring resources in your language of choice.
- Configuration Documents to learn about using resources in a configuration document.
- Command line reference for the 'dsc resource' command