Edit

Share via

dsc resource list

Synopsis

Retrieves the list of available DSC Resources with an optional filter.

Syntax

dsc resource list [Options] <RESOURCE_NAME>

Description

The list subcommand searches for available DSC Resources and returns their information. DSC discovers resources by first searching the PATH or DSC_RESOURCE_PATH environment variable for .dsc.resource.json, .dsc.resource.yml, and dsc.resource.yaml files. For more information about the environment variables DSC uses, see Environment variables

If any of the discovered resources are resource adapters, DSC calls the list operation for those adapters if the --adapter option specifies a matching filter. By default, DSC doesn't return any adapted resources. When you use the --adapter option, the command doesn't return any non-adapted resources.

DSC returns the list of discovered resources with their implementation information and metadata. If the command includes the RESOURCE_NAME argument, DSC filters the list of discovered resources before returning them. The --description and --tags options filter the results by the resource descriptions and tags. Filters are always applied after resource discovery.

Adapted resource cache

DSC maintains a cache of discovered adapted resources for performance optimization. The location of the cache depends on the operating system, as shown in the following table.

Operating system Cache path
Linux ~/.dsc/AdaptedResourcesLookupTable.json
macOS ~/.dsc/AdaptedResourcesLookupTable.json
Windows %LOCALAPPDATA%\dsc\AdaptedResourcesLookupTable.json

Examples

Example 1 - List all non-adapted resources

Without any filters, the command returns every discovered DSC Resource, but doesn't call the list operation for adapter resources to enumerate any adapted resources.

dsc resource list

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 configu…
Microsoft.DSC/Group                         Group     0.1.0    gs--t---                      All resources in the supplied configuration is treated as a grou…
Microsoft.DSC/Include                       Importer  0.1.0    gs--t---                      Allows including a configuration file with optional parameter fi…
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 …
Microsoft/OSInfo                            Resource  0.1.0    g-----e-                      Returns information about the operating system.

Example 2 - List a specific resource

When the RESOURCE_NAME argument doesn't include a wildcard, the command returns only the resource with the specified type name.

dsc resource list Microsoft.DSC/Group

Type                 Kind   Version  Capabilities  RequireAdapter  Description
-------------------------------------------------------------------------------------------------------------------------------------
Microsoft.DSC/Group  Group  0.1.0    gs--t---                      All resources in the supplied configuration is treated as a group.

Example 3 - List resources with a matching type name

When the RESOURCE_NAME argument includes a wildcard, the command returns every resource with a matching type name.

dsc resource list Microsoft.DSC/*

Type                      Kind      Version  Capabilities  RequireAdapter  Description
--------------------------------------------------------------------------------------------------------------------------------------------------
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.

Example 4 - List resources with a matching description

When the command includes the *--description option, the results include resources that have a description containing the specified value.

dsc resource list --description 'supplied configuration'

Type                     Kind   Version  Capabilities  RequireAdapter  Description
----------------------------------------------------------------------------------------------------------------------------------------------
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.

Example 5 - List resources with matching tags

When the command includes multiple instances of the --tags option, the results include resources that have any of the specified tags.

dsc resource list --tags Windows --tags Linux

Type                        Kind      Version  Capabilities  RequireAdapter  Description
----------------------------------------------------------------------------------------------------------------------------
Microsoft.Windows/Registry  Resource  0.1.0    gs-w-d--                      Manage Windows Registry keys and values
Microsoft/OSInfo            Resource  0.1.0    g-----e-                      Returns information about the operating system.

Example 6 - List resources for a specific adapter

When the command includes the --adapter option, DSC checks for any discovered resource adapters with a matching name. If it discovers any, it then calls the list operation for the adapter and adds the returned list of adapted resources to the discovered resource list. DSC applies any further filters specified with the command after this enumeration.

dsc resource list --adapter Microsoft.Windows/WindowsPowerShell

This next command specifies the resource name filter *Windows*, limiting the list of returned resources:

dsc resource list --adapter Microsoft.Windows/WindowsPowerShell *Windows*

Arguments

RESOURCE_NAME

Specifies an optional filter to apply for the type names of discovered DSC Resources. The filter can include wildcards (*). The filter isn't case-sensitive.

When this argument is specified, DSC filters the results to include only resources where the resource type name matches the filter.

For example, specifying the filter Microsoft.* returns only the resources published by Microsoft. Specifying the filter *Sql* returns any resource with the string Sql in its name, regardless of the casing.

Type      : string
Mandatory : false

Options

-a, --adapter

Specifies a filter to define which adapter resources to enumerate adapted resources for. By default, the command doesn't call the list command for adapter resources. When you specify this option, DSC looks for adapter resources with type names that match the filter. If it discovers any adapters matching the filter, it calls the list command for those adapters and returns the adapted resources. DSC retrieves adapted resources before applying any other filters for the command.

When you use this option, the command doesn't return any non-adapted resources.

If you specify this option with the filter *, DSC calls list for every adapter resource it finds before applying the other filters.

Type        : string
Mandatory   : false
LongSyntax  : --adapter <ADAPTER_NAME>
ShortSyntax : -a <ADAPTER_NAME>

-d, --description

Specifies a string to match in a resource's description. When this option is specified, DSC filters the resources by their description strings. The filter is case-insensitive and matches the value anywhere in the description string. Wildcards aren't permitted.

Type        : string
Mandatory   : false
LongSyntax  : --description <DESCRIPTION>
ShortSyntax : -d <DESCRIPTION>

-t, --tags

Specifies a resource tag to filter on. When this option is specified, DSC filters the resources and only includes those with a matching tag. The filter is case-insensitive. Wildcards aren't permitted.

You can specify this option more than once to filter on a set of tags. The results include resources that have at least one of the tags specified with this option.

Type        : string
Mandatory   : false
LongSyntax  : --tags <TAGS>
ShortSyntax : -t <TAGS>

-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.
  • table-no-truncate to emit the data as a summary table without truncating each line to the current console width.

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 a summary table described in the Output section of this document.
  • 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, table-no-truncate]
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 a formatted array containing an object for each resource that includes the resource's type, version, manifest settings, and other metadata. For more information, see dsc resource list result schema.

If the output of the command isn't captured or redirected, it displays in the console by default as a summary table for the returned resources. The summary table includes the following columns, displayed in the listed order:

  • Type - The fully qualified type name of the resource.

  • Kind - Whether the resource is an adapter, group, importer, or typical Resource. For more information, see DSC Resource kind schema reference.

  • Version - The semantic version of the resource.

  • Capabilities - A display of the resource's capabilities as flags. The capabilities are displayed in the following order, using a - instead of the appropriate letter if the resource doesn't have a specific capability:

    For example, the Microsoft.Windows/Registry resource has the following capabilities: gs--d-, indicating it has the get, set, and delete capabilities.

  • RequireAdapter - The fully qualified type name of the adapter resource that DSC uses to invoke the returned resource.

  • Description - The short description of the resource's purpose and usage.

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