dsc config set

2025-03-26

Synopsis

Enforces the desired state of resource instances in a configuration document.

Syntax

Configuration document from file

dsc config set [Options] --file <FILE>

Configuration document from option string

dsc config set [Options] --input <INPUT>

Configuration document from stdin

cat <FILE> | dsc config set [Options] --file -

Description

The set subcommand enforces the desired state of the resource instances in a configuration document. When this command runs, DSC validates the configuration document before invoking the test operation for each resource instance defined in the document. DSC then invokes the set operation for each resource instance that isn't in the desired state.

The configuration document must be passed to this command as JSON or YAML with the --input or --file option.

Examples

Example 1 - Set a configuration's resource instances to the desired state

The command inspects the resource instances defined in the configuration document saved as example.dsc.config.yaml and sets them to the desired state as needed.

# example.dsc.config.yaml
$schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
resources:
- name: Windows only
  type: Microsoft.DSC/Assertion
  properties:
    $schema: https://aka.ms/dsc/schemas/v3/bundled/config/document.json
    resources:
    - name: os
      type: Microsoft/OSInfo
      properties:
        family: Windows
- name: Current user registry example
  type: Microsoft.Windows/Registry
  properties:
    keyPath: HKCU\example
    _exist: true
  dependsOn:
    - "[resourceId('Microsoft.DSC/Assertion', 'Windows only')"

cat ./example.dsc.config.yaml | dsc config set --file -

Example 2 - Passing a file to read as the configuration document

The command uses the path option to enforce the configuration defined in the example.dsc.config.yaml file.

dsc config set --path ./example.dsc.config.yaml

Example 3 - Passing a configuration document as a variable

The command uses the document option to enforce the configuration stored in the $desired variable.

dsc config set --document $desired

Options

-i, --input

Specifies the configuration document to enforce state for.

The document must be a string containing a JSON or YAML object. DSC validates the document against the configuration document schema. If the validation fails, DSC raises an error.

This option is mutually exclusive with the --file option.

Type        : string
Mandatory   : false
LongSyntax  : --input <INPUT>
ShortSyntax : -i <INPUT>

-f, --file

Defines the path to a configuration document to enforce state for.

The specified file must contain a configuration document as a JSON or YAML object. DSC validates the document against the configuration document schema. If the validation fails, or if the specified file doesn't exist, DSC raises an error.

You can also use this option to pass a configuration document from stdin, as shown in Example 1.

This option is mutually exclusive with the --input option.

Type        : string
Mandatory   : false
LongSyntax  : --file <FILE>
ShortSyntax : -f <FILE>

-w, --what-if

When you specify this flag option, DSC doesn't actually change the system state with the set operation. Instead, it returns output indicating how the operation will change system state when called without this option. Use this option to preview the changes DSC will make to a system.

The output for the command when you use this option is the same as without, except that the ExecutionType metadata field is set to WhatIf instead of Actual.

Type        : boolean
Mandatory   : false
LongSyntax  : --what-if
ShortSyntax : -w

-o, --output-format

The --output-format option controls which format DSC uses for the data the command returns. The available formats are:

json to emit the data as a JSON Line.
pretty-json to emit the data as JSON with newlines, indentation, and spaces for readability.
yaml to emit the data as YAML.

The default output format depends on whether DSC detects that the output is being redirected or captured as a variable:

If the command isn't being redirected or captured, DSC displays the output as the yaml format in the console.
If the command output is redirected or captured, DSC emits the data as the json format to stdout.

When you use this option, DSC uses the specified format regardless of whether the command is being redirected or captured.

When the command isn't redirected or captured, the output in the console is formatted for improved readability. When the command isn't redirected or captured, the output include terminal sequences for formatting.

Type        : string
Mandatory   : false
ValidValues : [json, pretty-json, yaml]
LongSyntax  : --output-format <OUTPUT_FORMAT>
ShortSyntax : -o <OUTPUT_FORMAT>

-h, --help

Displays the help for the current command or subcommand. When you specify this option, the application ignores all other options and arguments.

Type        : boolean
Mandatory   : false
LongSyntax  : --help
ShortSyntax : -h

Output

This command returns formatted data that includes whether the operation or any resources raised any errors, the collection of messages emitted during the operation, and the set operation results for every instance. For more information, see dsc config get result schema.

For more information about the formatting of the output data, see the --output-format option.

Share via