Edit

Share via

dsc resource get

  • Article

Synopsis

Retrieves the actual state of a resource instance.

Syntax

Without instance properties

dsc resource get [Options] --resource <RESOURCE>

Instance properties from input option

dsc resource get --input <INPUT> --resource <RESOURCE>

Instance properties from file

dsc resource get --file <FILE> --resource <RESOURCE>

Instance properties from stdin

cat <FILE> | dsc resource get [Options] --resource <RESOURCE> --file -

Description

The get subcommand returns the current state of a resource instance.

By default, this subcommand returns one instance from a specific DSC Resource. To return multiple resources, use the --all parameter, a resource group, or the dsc config get command.

Any properties the resource requires for retrieving the state of an instance must be passed to this command as a JSON or YAML object with the --input or --file option.

Examples

Example 1 - Get resource instance without any input

For single-instance resources that don't require any property values to return the actual state of the resource instance, the instance properties aren't required.

dsc resource get --resource Microsoft/OSInfo

actualState:
  $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json
  family: Windows
  version: 10.0.22621
  edition: Windows 11 Enterprise
  bitness: '64'

Example 2 - Get resource instance with input option

If a resource requires one or more property values to return the actual state of the instance, the instance properties can be passed with the --input option as either JSON or YAML.

dsc resource get --resource Microsoft.Windows/Registry --input '{
    "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion",
    "valueName": "SystemRoot"
}'

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

Example 3 - Get resource instance with input from stdin

If a resource requires one or more property values to return the actual state of the instance, the instance properties can be passed over stdin as either JSON or YAML with the --file option.

'{
    "keyPath": "HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion",
    "valueName": "SystemRoot"
}' | dsc resource get --resource Microsoft.Windows/Registry --file -

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

Example 4 - Get resource instance with input from a YAML file

If a resource requires one or more property values to return the actual state of the instance, the instance properties can be retrieved from a saved JSON or YAML file.

# ./example.yaml
keyPath:   HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion
valueName: SystemRoot

dsc resource get --resource Microsoft.Windows/Registry --path ./example.yaml

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

Options

-a, --all

Specifies that the command should return every instance of the specified DSC Resource instead of a specific instance.

This option is only valid when the Resource is an exportable resource that defines the export section in the input configuration. If the resource type isn't exportable, DSC raises an error.

When this option is specified, DSC ignores the --input and --path options.

Type:      Boolean
Mandatory: false

-r, --resource

Specifies the fully qualified type name of the DSC Resource to use, like Microsoft.Windows/Registry.

The fully qualified type name syntax is: <owner>[.<group>][.<area>]/<name>, where:

  • The owner is the maintaining author or organization for the resource.
  • The group and area are optional name components that enable namespacing for a resource.
  • The name identifies the component the resource manages.
Type        : string
Mandatory   : true
LongSyntax  : --resource <RESOURCE>
ShortSyntax : -r <RESOURCE>

-i, --input

Specifies the resource instance to retrieve.

The instance must be a string containing a JSON or YAML object. DSC validates the object against the resource's instance 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 file defining the resource instance to retrieve.

The specified file must contain a JSON or YAML object that represents valid properties for the resource. DSC validates the object against the resource's instance 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 an instance from stdin, as shown in Example 3.

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

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

-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. When you use the --all option, each instance is returned 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. When you use the --all option, each instance is returned as a YAML document with the --- document separator between each returned instance.

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

By default, this command returns a formatted data object that includes the actual state of the instance. When the --all option is specified, the command returns the formatted data for each instance.

For more information about the structure of the output JSON, see dsc resource get result schema.

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