Skip to content

Commit c9590e0

Browse files
michaeltlombardimichaeltlombardi
committed
(DOCS) Add reference docs for extensions
This change adds reference docs for: - The `dsc extension` command - The `dsc extension list` command and its output - The extension manifest - The expected output for the `discover` extension operation
1 parent c02ff0f commit c9590e0

File tree

6 files changed

+729
-0
lines changed

6 files changed

+729
-0
lines changed

‎docs/reference/cli/extension/index.md

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
description: Command line reference for the 'dsc extension' command
3+
ms.date: 03/25/2025
4+
ms.topic: reference
5+
title: dsc extension
6+
---
7+
8+
# dsc extension
9+
10+
## Synopsis
11+
12+
Operations on DSC extensions.
13+
14+
## Syntax
15+
16+
```sh
17+
dsc extension [Options] <COMMAND>
18+
```
19+
20+
## Description
21+
22+
The `dsc extension` command contains a subcommand for listing DSC extensions.
23+
24+
## Commands
25+
26+
### list
27+
28+
The `list` command returns the list of available DSC extensions with an optional filter. For more
29+
information, see [dsc extension list][01].
30+
31+
### help
32+
33+
The `help` command returns help information for this command or a subcommand.
34+
35+
To get the help for a command or subcommand, use the syntax:
36+
37+
```sh
38+
dsc extension help [<SUBCOMMAND>]
39+
```
40+
41+
For example, `dsc extension help` gets the help for this command. `dsc extension help list`
42+
gets the help for the `list` subcommand.
43+
44+
You can also use the [--help](#--help) option on the command or subcommand to display the help
45+
information. For example, `dsc extension --help` or `dsc extension list --help`.
46+
47+
## Options
48+
49+
### -h, --help
50+
51+
<a id="-h"></a>
52+
<a id="--help"></a>
53+
54+
Displays the help for the current command or subcommand. When you specify this option, the
55+
application ignores all other options and arguments.
56+
57+
```yaml
58+
Type : boolean
59+
Mandatory : false
60+
LongSyntax : --help
61+
ShortSyntax : -h
62+
```
63+
64+
[01]: ./list.md

‎docs/reference/cli/extension/list.md

Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
---
2+
description: Command line reference for the 'dsc extension list' command
3+
ms.date: 03/25/2025
4+
ms.topic: reference
5+
title: dsc extension list
6+
---
7+
8+
# dsc extension list
9+
10+
## Synopsis
11+
12+
Retrieves the list of available DSC extensions with an optional filter.
13+
14+
## Syntax
15+
16+
```sh
17+
dsc extension list [Options] <EXTENSION_NAME>
18+
```
19+
20+
## Description
21+
22+
The `list` subcommand searches for available DSC extensions and returns their information. DSC
23+
discovers extensions by first searching the `PATH` or `DSC_RESOURCE_PATH` environment variable for
24+
`.dsc.extension.json`, `.dsc.extension.yml`, and `dsc.extension.yaml` files. For more information
25+
about the environment variables DSC uses, see [Environment variables][01]
26+
27+
DSC returns the list of discovered extensions with their implementation information and metadata. If
28+
the command includes the `EXTENSION_NAME` argument, DSC filters the list of discovered extensions
29+
before returning them. Filters are always applied after extension discovery.
30+
31+
## Examples
32+
33+
### Example 1 - List all extensions
34+
35+
Without any filters, the command returns every discovered DSC extension.
36+
37+
```sh
38+
dsc extension list
39+
```
40+
41+
```Output
42+
Type Version Capabilities Description
43+
----------------------------------------------------------------------------------------------------------
44+
Microsoft.Windows.Appx/Discover 0.1.0 d Discovers DSC resources packaged as Appx packages.
45+
```
46+
47+
### Example 2 - List a specific extension
48+
49+
When the `EXTENSION_NAME` argument doesn't include a wildcard, the command returns only the extension
50+
with the specified type name.
51+
52+
```sh
53+
dsc extension list Microsoft.Windows.Appx/Discover
54+
```
55+
56+
```Output
57+
Type Version Capabilities Description
58+
----------------------------------------------------------------------------------------------------------
59+
Microsoft.Windows.Appx/Discover 0.1.0 d Discovers DSC resources packaged as Appx packages.
60+
```
61+
62+
### Example 3 - List extensions with a matching type name
63+
64+
When the `EXTENSION_NAME` argument includes a wildcard, the command returns every extension with a
65+
matching type name.
66+
67+
```sh
68+
dsc extension list Microsoft*
69+
```
70+
71+
```Output
72+
Type Version Capabilities Description
73+
----------------------------------------------------------------------------------------------------------
74+
Microsoft.Windows.Appx/Discover 0.1.0 d Discovers DSC resources packaged as Appx packages.
75+
```
76+
77+
## Arguments
78+
79+
### EXTENSION_NAME
80+
81+
Specifies an optional filter to apply for the type names of discovered DSC extensions. The filter
82+
can include wildcards (`*`). The filter isn't case-sensitive.
83+
84+
When this argument is specified, DSC filters the results to include only extensions where the
85+
extension type name matches the filter.
86+
87+
For example, specifying the filter `Microsoft.*` returns only the extensions published by
88+
Microsoft. Specifying the filter `*Windows*` returns any extension with the string `Windows` in its
89+
name, regardless of the casing.
90+
91+
```yaml
92+
Type : string
93+
Mandatory : false
94+
```
95+
96+
## Options
97+
98+
### -o, --output-format
99+
100+
<a id="-o"></a>
101+
<a id="--output-format"></a>
102+
103+
The `--output-format` option controls which format DSC uses for the data the command returns. The
104+
available formats are:
105+
106+
- `json` to emit the data as a [JSON Line][02].
107+
- `pretty-json` to emit the data as JSON with newlines, indentation, and spaces for readability.
108+
- `yaml` to emit the data as YAML.
109+
- `table-no-truncate` to emit the data as a summary table without truncating each line to the
110+
current console width.
111+
112+
The default output format depends on whether DSC detects that the output is being redirected or
113+
captured as a variable:
114+
115+
- If the command isn't being redirected or captured, DSC displays the output as a summary table
116+
described in the [Output](#output) section of this document.
117+
- If the command output is redirected or captured, DSC emits the data as the `json` format to
118+
stdout.
119+
120+
When you use this option, DSC uses the specified format regardless of whether the command is being
121+
redirected or captured.
122+
123+
When the command isn't redirected or captured, the output in the console is formatted for improved
124+
readability. When the command isn't redirected or captured, the output includes terminal sequences
125+
for formatting.
126+
127+
```yaml
128+
Type : string
129+
Mandatory : false
130+
ValidValues : [json, pretty-json, yaml, table-no-truncate]
131+
LongSyntax : --output-format <OUTPUT_FORMAT>
132+
ShortSyntax : -o <OUTPUT_FORMAT>
133+
```
134+
135+
### -h, --help
136+
137+
<a id="-h"></a>
138+
<a id="--help"></a>
139+
140+
Displays the help for the current command or subcommand. When you specify this option, the
141+
application ignores all other options and arguments.
142+
143+
```yaml
144+
Type : boolean
145+
Mandatory : false
146+
LongSyntax : --help
147+
ShortSyntax : -h
148+
```
149+
150+
## Output
151+
152+
This command returns a formatted array containing an object for each extension that includes the
153+
extension's type, version, manifest settings, and other metadata. For more information, see
154+
[dsc extension list result schema][03].
155+
156+
If the output of the command isn't captured or redirected, it displays in the console by default as
157+
a summary table for the returned extensions. The summary table includes the following columns,
158+
displayed in the listed order:
159+
160+
- **Type** - The fully qualified type name of the extension.
161+
- **Version** - The semantic version of the extension.
162+
- **Capabilities** - A display of the extension's [capabilities][04] as flags. The capabilities are
163+
displayed in the following order, using a `-` instead of the appropriate letter if the extension
164+
doesn't have a specific capability:
165+
166+
- `d` indicates that the extension has the [discover capability][05].
167+
168+
For example, the `icrosoft.Windows.Appx/Discover` extension has the following capabilities: `d`,
169+
indicating it has the `discover` capability.
170+
- **Description** - The short description of the extension's purpose and usage.
171+
172+
For more information about the formatting of the output data, see the
173+
[--output-format option](#--output-format).
174+
175+
<!-- Link reference definitions -->
176+
[01]: ../index.md#environment-variables
177+
[02]: https://jsonlines.org/
178+
[03]: ../../schemas/outputs/extension/list.md
179+
[04]: ../../schemas/outputs/extension/list.md#capabilities
180+
[05]: ../../schemas/outputs/extension/list.md#capability-discover

‎docs/reference/schemas/extension/manifest/discover.md

Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
---
2+
description: JSON schema reference for the 'discover' property in a DSC extension manifest
3+
ms.date: 02/28/2025
4+
ms.topic: reference
5+
title: DSC extension manifest discover property schema reference
6+
---
7+
8+
# DSC extension manifest discover property schema reference
9+
10+
## Synopsis
11+
12+
Defines how to retrieve DSC resources not available in `PATH` or `DSC_RESOURCE_PATH`.
13+
14+
## Metadata
15+
16+
```yaml
17+
SchemaDialect: https://json-schema.org/draft/2020-12/schema
18+
SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/v3.1.0/extension/manifest.discover.json
19+
Type: object
20+
```
21+
22+
## Description
23+
24+
A DSC extension that can enumerate DSC resource not discoverable in the `PATH` or `DSC_RESOURCE_PATH` environment variables
25+
should define the `export` property in its manifest. This property defines how DSC can get the
26+
path to otherwise undiscoverable manifests.
27+
28+
When the DSC performs discovery for any operation, it calls the command defined by this property.
29+
The extension must return the path to discovered manifests as [JSON lines][05]. Each JSON Line
30+
should be an object representing the instance and validate against the
31+
[DSC extension discover operation stdout schema reference][06].
32+
33+
## Required Properties
34+
35+
The `discover` definition must include these properties:
36+
37+
- [executable](#executable)
38+
39+
## Properties
40+
41+
### executable
42+
43+
The `executable` property defines the name of the command to run. The value must be the name of a
44+
command discoverable in the system's `PATH` environment variable or the full path to the command. A
45+
file extension is only required when the command isn't recognizable by the operating system as an
46+
executable.
47+
48+
```yaml
49+
Type: string
50+
Required: true
51+
```
52+
53+
### args
54+
55+
The `args` property defines the list of arguments to pass to the command. The arguments can be any
56+
number of strings. If you want to pass the JSON object representing the property bag for the
57+
extension input to an argument, you can define a single item in the array as a
58+
[JSON object](#json-input-argument), indicating the name of the argument with the `jsonInputArg`
59+
string property and whether the argument is mandatory for the command with the `mandatory` boolean
60+
property.
61+
62+
```yaml
63+
Type: array
64+
Required: false
65+
Default: []
66+
Type: [string, object(JSON Input Argument)]
67+
```
68+
69+
#### String arguments
70+
71+
Any item in the argument array can be a string representing a static argument to pass to the
72+
command, like `discover` or `--format`.
73+
74+
```yaml
75+
Type: string
76+
```
77+
78+
#### JSON input argument
79+
80+
Defines an argument for the command that accepts the JSON input object as a string. DSC passes the
81+
JSON input to the named argument when available. A JSON input argument is defined as a JSON object
82+
with the following properties:
83+
84+
- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`.
85+
- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command,
86+
even when there's no JSON input for the command. In that case, DSC passes an empty string to the
87+
JSON input argument.
88+
89+
You can only define one JSON input argument per arguments array.
90+
91+
```yaml
92+
Type: object
93+
RequiredProperties: [jsonInputArg]
94+
```
95+
96+
[05]: https://jsonlines.org/
97+
[06]: ../stdout/discover.md

0 commit comments

Comments
 (0)