From 6185ea3ac6e066b1b5396e17b5fac816c7c0c541 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 23 Feb 2024 13:36:07 -0600 Subject: [PATCH 1/2] (DOCS) Update `--format` option in CLI docs This change updates the CLI reference docs and the changelog to reflect the refactoring of the `--format` option from a global option to a per-command option. --- CHANGELOG.md | 15 +++++++++++---- docs/reference/cli/config/export.md | 12 ++++++++++++ docs/reference/cli/config/get.md | 12 ++++++++++++ docs/reference/cli/config/set.md | 12 ++++++++++++ docs/reference/cli/config/test.md | 12 ++++++++++++ docs/reference/cli/dsc.md | 15 --------------- docs/reference/cli/resource/export.md | 12 ++++++++++++ docs/reference/cli/resource/get.md | 12 ++++++++++++ docs/reference/cli/resource/list.md | 12 ++++++++++++ docs/reference/cli/resource/schema.md | 12 ++++++++++++ docs/reference/cli/resource/set.md | 12 ++++++++++++ docs/reference/cli/resource/test.md | 12 ++++++++++++ docs/reference/cli/schema/command.md | 12 ++++++++++++ 13 files changed, 143 insertions(+), 19 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2297b485..0ff53520 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,8 +30,9 @@ changes since the last release, see the [diff on GitHub][unreleased]. - Updated the options for the `dsc` root command: - - The short name for the [--format][36] option, which controls the output format, is now `-o` - instead of `-f`. + - Removed the global [--format][36] option, which controls the output format. Now, the relevant + subcommands that return formattable output have the `--format` option (short option as `-f`) + added to them. - The `--logging-level` option is renamed to [--trace-level][37] with the short name `-l`. The default trace level is now `warning` instead of `info`. - Added the [--trace-format][38] option with the `-f` short name. This option enables you to @@ -41,8 +42,12 @@ changes since the last release, see the [diff on GitHub][unreleased].
Related work items - - Issues: [#286][#286] - - PRs: [#299][#299] + - Issues: + - [#286][#286] + - [#227][#227] + - PRs: + - [#299][#299] + - [#303][#303]
@@ -565,6 +570,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#215]: https://github.com/PowerShell/DSC/issues/215 [#216]: https://github.com/PowerShell/DSC/issues/216 [#217]: https://github.com/PowerShell/DSC/issues/217 +[#227]: https://github.com/PowerShell/DSC/issues/227 [#240]: https://github.com/PowerShell/DSC/issues/240 [#241]: https://github.com/PowerShell/DSC/issues/241 [#248]: https://github.com/PowerShell/DSC/issues/248 @@ -573,6 +579,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#291]: https://github.com/PowerShell/DSC/issues/291 [#294]: https://github.com/PowerShell/DSC/issues/294 [#299]: https://github.com/PowerShell/DSC/issues/299 +[#303]: https://github.com/PowerShell/DSC/issues/303 [#311]: https://github.com/PowerShell/DSC/issues/311 [#45]: https://github.com/PowerShell/DSC/issues/45 [#49]: https://github.com/PowerShell/DSC/issues/49 diff --git a/docs/reference/cli/config/export.md b/docs/reference/cli/config/export.md index c4e20166..b4469d1a 100644 --- a/docs/reference/cli/config/export.md +++ b/docs/reference/cli/config/export.md @@ -33,6 +33,18 @@ configuration, DSC raises an error. ## Options +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/config/get.md b/docs/reference/cli/config/get.md index 36e4755e..d92ea4b3 100644 --- a/docs/reference/cli/config/get.md +++ b/docs/reference/cli/config/get.md @@ -78,6 +78,18 @@ dsc --input $desired config get ## Options +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/config/set.md b/docs/reference/cli/config/set.md index 77e63d1c..ee21bfb4 100644 --- a/docs/reference/cli/config/set.md +++ b/docs/reference/cli/config/set.md @@ -79,6 +79,18 @@ dsc --input $desired config set ## Options +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/config/test.md b/docs/reference/cli/config/test.md index 995d6ebe..aa29a8b9 100644 --- a/docs/reference/cli/config/test.md +++ b/docs/reference/cli/config/test.md @@ -78,6 +78,18 @@ dsc --input $desired config test ## Options +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/dsc.md b/docs/reference/cli/dsc.md index 924ab594..2a6c84d2 100644 --- a/docs/reference/cli/dsc.md +++ b/docs/reference/cli/dsc.md @@ -69,21 +69,6 @@ example, `dsc config --help` or `dsc config set --help`. ## Options -### -o, --format - -The `--format` option controls the console output format for the command. If the command output is -redirected or captured as a variable, the output is always JSON. - -To set the output format for a command or subcommand, specify this option before the command, like -`dsc --format pretty-json resource list`. - -```yaml -Type: String -Mandatory: false -DefaultValue: yaml -ValidValues: [json, pretty-json, yaml] -``` - ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/resource/export.md b/docs/reference/cli/resource/export.md index 952d6682..78c660bd 100644 --- a/docs/reference/cli/resource/export.md +++ b/docs/reference/cli/resource/export.md @@ -43,6 +43,18 @@ Type: String Mandatory: true ``` +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/resource/get.md b/docs/reference/cli/resource/get.md index 318925d4..ac6a6da6 100644 --- a/docs/reference/cli/resource/get.md +++ b/docs/reference/cli/resource/get.md @@ -140,6 +140,18 @@ Type: String Mandatory: false ``` +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/resource/list.md b/docs/reference/cli/resource/list.md index f5e54b7e..30505139 100644 --- a/docs/reference/cli/resource/list.md +++ b/docs/reference/cli/resource/list.md @@ -167,6 +167,18 @@ Type: String Mandatory: false ``` +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/resource/schema.md b/docs/reference/cli/resource/schema.md index 9ae0e6ac..1c604a25 100644 --- a/docs/reference/cli/resource/schema.md +++ b/docs/reference/cli/resource/schema.md @@ -98,6 +98,18 @@ Type: String Mandatory: true ``` +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/resource/set.md b/docs/reference/cli/resource/set.md index 691a7e2b..678d081a 100644 --- a/docs/reference/cli/resource/set.md +++ b/docs/reference/cli/resource/set.md @@ -115,6 +115,18 @@ Type: String Mandatory: false ``` +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/resource/test.md b/docs/reference/cli/resource/test.md index 0b309bc8..6ee02ad8 100644 --- a/docs/reference/cli/resource/test.md +++ b/docs/reference/cli/resource/test.md @@ -96,6 +96,18 @@ Type: String Mandatory: false ``` +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the diff --git a/docs/reference/cli/schema/command.md b/docs/reference/cli/schema/command.md index efce7187..472fe41a 100644 --- a/docs/reference/cli/schema/command.md +++ b/docs/reference/cli/schema/command.md @@ -88,6 +88,18 @@ ValidValues: [ ] ``` +### -f, --format + +The `--format` option controls the console output format for the command. If the command output is +redirected or captured as a variable, the output is always JSON. + +```yaml +Type: String +Mandatory: false +DefaultValue: yaml +ValidValues: [json, pretty-json, yaml] +``` + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the From 668324bdc0a74d5f67844c43be3a835f196369e0 Mon Sep 17 00:00:00 2001 From: Michael Lombardi Date: Fri, 23 Feb 2024 16:07:33 -0600 Subject: [PATCH 2/2] (DOCS) Update docs for input options This change updates the CLI reference and changelog to reflect the refactored options for input to the `config` and `resource` subcommands. --- CHANGELOG.md | 19 ++++-- docs/reference/cli/config/export.md | 60 +++++++++++++++++-- docs/reference/cli/config/get.md | 66 +++++++++++++++++---- docs/reference/cli/config/set.md | 68 +++++++++++++++++---- docs/reference/cli/config/test.md | 68 +++++++++++++++++---- docs/reference/cli/dsc.md | 30 ---------- docs/reference/cli/resource/get.md | 91 +++++++++++++++++++++++++---- docs/reference/cli/resource/set.md | 71 ++++++++++++++++++---- docs/reference/cli/resource/test.md | 70 ++++++++++++++++++---- 9 files changed, 434 insertions(+), 109 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 0ff53520..80ecbee5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,12 +30,16 @@ changes since the last release, see the [diff on GitHub][unreleased]. - Updated the options for the `dsc` root command: - - Removed the global [--format][36] option, which controls the output format. Now, the relevant + - Removed the global `--format` option, which controls the output format. Now, the relevant subcommands that return formattable output have the `--format` option (short option as `-f`) added to them. - - The `--logging-level` option is renamed to [--trace-level][37] with the short name `-l`. The + - Removed the global `--input` and `--input-file` options. Now, the `config` subcommands have the + `--document` and `--path` options for specifying the configuration document as a string or from + a file. The relevant `resource` subcommands have the `--input` and `--path` options for + specifying the instance properties as a string or from a file. + - The `--logging-level` option is renamed to [--trace-level][36] with the short name `-l`. The default trace level is now `warning` instead of `info`. - - Added the [--trace-format][38] option with the `-f` short name. This option enables you to + - Added the [--trace-format][37] option with the `-f` short name. This option enables you to choose the format for the trace messages emitted to stderr. By default, the messages are emitted as lines of text with console colors. You can set this option to `plaintext` to emit the messages without console colors or to `json` to emit the messages as JSON objects. @@ -45,9 +49,11 @@ changes since the last release, see the [diff on GitHub][unreleased]. - Issues: - [#286][#286] - [#227][#227] + - [#226][#226] - PRs: - [#299][#299] - [#303][#303] + - [#305][#305] @@ -531,9 +537,8 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [33]: docs/reference/cli/config/command.md#-p---parameters [34]: docs/reference/cli/config/command.md#-f---parameters_file [35]: docs/reference/cli/config/command.md -[36]: docs/reference/cli/dsc.md#-o---format -[37]: docs/reference/cli/dsc.md#-l---trace-level -[38]: docs/reference/cli/dsc.md#-f---trace-format +[36]: docs/reference/cli/dsc.md#-l---trace-level +[37]: docs/reference/cli/dsc.md#-f---trace-format [#107]: https://github.com/PowerShell/DSC/issues/107 @@ -570,6 +575,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#215]: https://github.com/PowerShell/DSC/issues/215 [#216]: https://github.com/PowerShell/DSC/issues/216 [#217]: https://github.com/PowerShell/DSC/issues/217 +[#226]: https://github.com/PowerShell/DSC/issues/226 [#227]: https://github.com/PowerShell/DSC/issues/227 [#240]: https://github.com/PowerShell/DSC/issues/240 [#241]: https://github.com/PowerShell/DSC/issues/241 @@ -580,6 +586,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#294]: https://github.com/PowerShell/DSC/issues/294 [#299]: https://github.com/PowerShell/DSC/issues/299 [#303]: https://github.com/PowerShell/DSC/issues/303 +[#305]: https://github.com/PowerShell/DSC/issues/305 [#311]: https://github.com/PowerShell/DSC/issues/311 [#45]: https://github.com/PowerShell/DSC/issues/45 [#49]: https://github.com/PowerShell/DSC/issues/49 diff --git a/docs/reference/cli/config/export.md b/docs/reference/cli/config/export.md index b4469d1a..1097cda0 100644 --- a/docs/reference/cli/config/export.md +++ b/docs/reference/cli/config/export.md @@ -13,18 +13,36 @@ Generates a configuration document that defines the existing instances of a set ## Syntax +### Configuration document from stdin + ```sh -dsc config export [Options] + | dsc config export [Options] +``` + +### Configuration document from option string + +```sh +dsc config export [Options] --document +``` + +### Configuration document from file + +```sh +dsc config export [Options] --path ``` ## Description The `export` subcommand generates a configuration document that includes every instance of a set of -resources. This command expects a configuration document formatted as JSON or YAML over stdin. The -input configuration defines the resources to export. DSC ignores any properties specified for the -resources in the input configuration for the operation, but the input document and any properties -for resource instances must still validate against the configuration document and resource instance -schemas. +resources. + +The configuration document must be passed to this command as JSON or YAML over stdin, as a string +with the **document** option, or from a file with the **path** option. + +The input configuration defines the resources to export. DSC ignores any properties specified for +the resources in the input configuration for the operation, but the input document and any +properties for resource instances must still validate against the configuration document and +resource instance schemas. Only specify resources with a resource manifest that defines the [export][01] section in the input configuration. Only define each resource type once. If the configuration document includes any @@ -33,6 +51,36 @@ configuration, DSC raises an error. ## Options +### -d, --document + +Specifies the configuration document to export from as a JSON or YAML object. DSC validates the +document against the configuration document schema. If the validation fails, DSC raises an error. + +This option can't be used with configuration document over stdin or the `--path` option. Choose +whether to pass the configuration document to the command over stdin, from a file with the `--path` +option, or with the `--document` option. + +```yaml +Type: String +Mandatory: false +``` + +### -p, --path + +Defines the path to a configuration document to export instead of piping the document from stdin or +passing it as a string with the `--document` option. 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. + +This option is mutually exclusive with the `--document` option. When you use this option, DSC +ignores any input from stdin. + +```yaml +Type: String +Mandatory: false +``` + ### -f, --format The `--format` option controls the console output format for the command. If the command output is diff --git a/docs/reference/cli/config/get.md b/docs/reference/cli/config/get.md index d92ea4b3..c429d0c6 100644 --- a/docs/reference/cli/config/get.md +++ b/docs/reference/cli/config/get.md @@ -13,8 +13,22 @@ Retrieves the current state of resource instances in a configuration document. ## Syntax +### Configuration document from stdin + +```sh + | dsc config get [Options] +``` + +### Configuration document from option string + +```sh +dsc config get [Options] --document +``` + +### Configuration document from file + ```sh -dsc config get [Options] +dsc config get [Options] --path ``` ## Description @@ -23,7 +37,8 @@ The `get` subcommand returns the current state of the resource instances in a co document. When this command runs, DSC validates the configuration document before invoking the get operation for each resource instance defined in the document. -The configuration document must be passed to this command as JSON or YAML over stdin. +The configuration document must be passed to this command as JSON or YAML over stdin, as a string +with the **document** option, or from a file with the **path** option. ## Examples @@ -60,24 +75,55 @@ cat ./example.dsc.config.yaml | dsc config get ### Example 2 - Passing a file to read as the configuration document -The command uses the [--input-file][01] global option to retrieve the resource instances defined in -the `example.dsc.config.yaml` file. +The command uses the **path** option to retrieve the resource instances defined in the +`example.dsc.config.yaml` file. ```sh -dsc --input-file ./example.dsc.config.yaml config get +dsc config get --path ./example.dsc.config.yaml ``` ### Example 3 - Passing a configuration document as a variable -The command uses the [--input][02] global option to retrieve the resource instances defined in a +The command uses the **document** option to retrieve the resource instances defined in a configuration document stored in the `$desired` variable. ```sh -dsc --input $desired config get +dsc config get --document $desired ``` ## Options +### -d, --document + +Specifies the configuration document to retrieve actual 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 can't be used with configuration document over stdin or the `--path` option. Choose +whether to pass the configuration document to the command over stdin, from a file with the `--path` +option, or with the `--document` option. + +```yaml +Type: String +Mandatory: false +``` + +### -p, --path + +Defines the path to a configuration document to retrieve actual state for instead of piping the +document from stdin or passing it as a string with the `--document` option. 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. + +This option is mutually exclusive with the `--document` option. When you use this option, DSC +ignores any input from stdin. + +```yaml +Type: String +Mandatory: false +``` + ### -f, --format The `--format` option controls the console output format for the command. If the command output is @@ -104,8 +150,6 @@ Mandatory: false This command returns JSON output that includes whether the operation or any resources raised any errors, the collection of messages emitted during the operation, and the get operation results for -every instance. For more information, see [dsc config get result schema][03]. +every instance. For more information, see [dsc config get result schema][01]. -[01]: ../dsc.md#-p---input-file -[02]: ../dsc.md#-i---input -[03]: ../../schemas/outputs/config/get.md +[01]: ../../schemas/outputs/config/get.md diff --git a/docs/reference/cli/config/set.md b/docs/reference/cli/config/set.md index ee21bfb4..5eefc972 100644 --- a/docs/reference/cli/config/set.md +++ b/docs/reference/cli/config/set.md @@ -13,8 +13,22 @@ Enforces the desired state of resource instances in a configuration document. ## Syntax +### Configuration document from stdin + +```sh + | dsc config set [Options] +``` + +### Configuration document from option string + +```sh +dsc config set [Options] --document +``` + +### Configuration document from file + ```sh -dsc config set [Options] +dsc config set [Options] --path ``` ## Description @@ -24,7 +38,8 @@ document. When this command runs, DSC validates the configuration document befor 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 over stdin. +The configuration document must be passed to this command as JSON or YAML over stdin, as a string +with the **document** option, or from a file with the **path** option. ## Examples @@ -61,24 +76,55 @@ cat ./example.dsc.config.yaml | dsc config set ### Example 2 - Passing a file to read as the configuration document -The command uses the [--input-file][01] global option to enforce the configuration defined in -the `example.dsc.config.yaml` file. +The command uses the **path** option to enforce the configuration defined in the +`example.dsc.config.yaml` file. ```sh -dsc --input-file ./example.dsc.config.yaml config set +dsc config set --path ./example.dsc.config.yaml ``` ### Example 3 - Passing a configuration document as a variable -The command uses the [--input][02] global option to enforce the configuration stored in the -`$desired` variable. +The command uses the **document** option to enforce the configuration stored in the `$desired` +variable. ```sh -dsc --input $desired config set +dsc config set --document $desired ``` ## Options +### -d, --document + +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 can't be used with configuration document over stdin or the `--path` option. Choose +whether to pass the configuration document to the command over stdin, from a file with the `--path` +option, or with the `--document` option. + +```yaml +Type: String +Mandatory: false +``` + +### -p, --path + +Defines the path to a configuration document to enforce state for instead of piping the document +from stdin or passing it as a string with the `--document` option. 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. + +This option is mutually exclusive with the `--document` option. When you use this option, DSC +ignores any input from stdin. + +```yaml +Type: String +Mandatory: false +``` + ### -f, --format The `--format` option controls the console output format for the command. If the command output is @@ -105,8 +151,6 @@ Mandatory: false This command returns JSON output 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][03]. +every instance. For more information, see [dsc config get result schema][01]. -[01]: ../dsc.md#-p---input-file -[02]: ../dsc.md#-i---input -[03]: ../../schemas/outputs/config/set.md +[01]: ../../schemas/outputs/config/set.md diff --git a/docs/reference/cli/config/test.md b/docs/reference/cli/config/test.md index aa29a8b9..559d390a 100644 --- a/docs/reference/cli/config/test.md +++ b/docs/reference/cli/config/test.md @@ -13,8 +13,22 @@ Verifies whether the resource instances in a configuration document are in the d ## Syntax +### Configuration document from stdin + +```sh + | dsc config test [Options] +``` + +### Configuration document from option string + +```sh +dsc config test [Options] --document +``` + +### Configuration document from file + ```sh -dsc config test [Options] +dsc config test [Options] --path ``` ## Description @@ -23,7 +37,8 @@ The `test` subcommand verifies whether the resource instances in a configuration the desired state. When this command runs, DSC validates the configuration document before invoking the test operation for each resource instance defined in the document. -The configuration document must be passed to this command as JSON or YAML over stdin. +The configuration document must be passed to this command as JSON or YAML over stdin, as a string +with the **document** option, or from a file with the **path** option. ## Examples @@ -60,24 +75,55 @@ cat ./example.dsc.config.yaml | dsc config test ### Example 2 - Passing a file to read as the configuration document -The command uses the [--input-file][01] global option to validate the configuration defined in -the `example.dsc.config.yaml` file. +The command uses the **path** option to validate the configuration defined in the +`example.dsc.config.yaml` file. ```sh -dsc --input-file ./example.dsc.config.yaml config test +dsc config test --path ./example.dsc.config.yaml ``` ### Example 3 - Passing a configuration document as a variable -The command uses the [--input][02] global option to validate the configuration stored in the -`$desired` variable. +The command uses the **document** option to validate the configuration stored in the `$desired` +variable. ```sh -dsc --input $desired config test +dsc config test --document $desired ``` ## Options +### -d, --document + +Specifies the configuration document to validate 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 can't be used with configuration document over stdin or the `--path` option. Choose +whether to pass the configuration document to the command over stdin, from a file with the `--path` +option, or with the `--document` option. + +```yaml +Type: String +Mandatory: false +``` + +### -p, --path + +Defines the path to a configuration document to validate state for instead of piping the document +from stdin or passing it as a string with the `--document` option. 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. + +This option is mutually exclusive with the `--document` option. When you use this option, DSC +ignores any input from stdin. + +```yaml +Type: String +Mandatory: false +``` + ### -f, --format The `--format` option controls the console output format for the command. If the command output is @@ -104,8 +150,6 @@ Mandatory: false This command returns JSON output that includes whether the operation or any resources raised any errors, the collection of messages emitted during the operation, and the test operation results for -every instance. For more information, see [dsc config test result schema][03]. +every instance. For more information, see [dsc config test result schema][01]. -[01]: ../dsc.md#-p---input-file -[02]: ../dsc.md#-i---input -[03]: ../../schemas/outputs/config/test.md +[01]: ../../schemas/outputs/config/test.md diff --git a/docs/reference/cli/dsc.md b/docs/reference/cli/dsc.md index 2a6c84d2..8ceecb97 100644 --- a/docs/reference/cli/dsc.md +++ b/docs/reference/cli/dsc.md @@ -79,20 +79,6 @@ Type: Boolean Mandatory: false ``` -### -i, --input - -Defines input for the command as a string instead of piping input from stdin. This option is -mutually exclusive with the `--input-file` option. When you use this option, DSC ignores any input -from stdin. - -To pass input for a command or subcommand, specify this option before the command, like -`dsc --input $desired resource test`. - -```yaml -Type: String -Mandatory: false -``` - ### -l, --trace-level Defines the minimum message level DSC should emit during an operation. Messages in DSC are @@ -141,22 +127,6 @@ DefaultValue: default ValidValues: [default, plaintext, json] ``` -### -p, --input-file - -Defines the path to a text file to read as input for the command instead of piping input from -stdin. This option is mutually exclusive with the `--input` option. When you use this option, DSC -ignores any input from stdin. - -To pass a file to read as input for a command or subcommand, specify this option before the -command, like `dsc --input-file web.dsc.config.yaml config set`. - -If the specified file doesn't exist, DSC raises an error. - -```yaml -Type: String -Mandatory: false -``` - ### -V, --version Displays the version of the application. When you specify this option, the application ignores all diff --git a/docs/reference/cli/resource/get.md b/docs/reference/cli/resource/get.md index ac6a6da6..b3fbae47 100644 --- a/docs/reference/cli/resource/get.md +++ b/docs/reference/cli/resource/get.md @@ -13,10 +13,30 @@ Invokes the get operation of a resource. ## Syntax +### Without instance properties + ```sh dsc resource get [Options] --resource ``` +### Instance properties from stdin + +```sh + | dsc resource get [Options] --resource +``` + +### Instance properties from input option + +```sh +dsc resource get --input '' --resource +``` + +### Instance properties from file + +```sh +dsc resource get --path --resource +``` + ## Description The `get` subcommand returns the current state of a resource instance. @@ -25,14 +45,15 @@ By default, this subcommand returns one instance from a specific DSC Resource. T resources, use the `--all` parameter, a resource group, or the [dsc config get][01] command. Any properties the resource requires for retrieving the state of an instance must be passed to this -command as JSON. The JSON can be passed to this command from stdin or with the `--input` option. +command as a JSON or YAML object. The object can be passed to this command from stdin or with the +`--input` option. You can also use the `--path` option to read the object from a JSON or YAML file. ## Examples ### Example 1 - Get resource instance without any input -For resources single-instance resources that don't require any property values to return the actual -state of the resource instance, the JSON input isn't required. +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. ```sh dsc resource get --resource Microsoft/OSInfo @@ -50,7 +71,7 @@ actualState: ### 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 -JSON object can be passed with the **input** option. +instance properties can be passed with the **input** option as either JSON or YAML. ```sh dsc resource get --resource Microsoft.Windows/Registry --input '{ @@ -71,7 +92,7 @@ actualState: ### 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 -JSON object can be passed over stdin. +instance properties can be passed over stdin as either JSON or YAML. ```sh '{ @@ -89,6 +110,33 @@ actualState: 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. + +```sh +cat ./example.yaml +``` + +```yaml +keyPath: HKLM\\Software\\Microsoft\\Windows NT\\CurrentVersion +valueName: SystemRoot +``` + +```sh +dsc resource get --resource Microsoft.Windows/Registry --path ./example.yaml +``` + +```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 @@ -100,8 +148,8 @@ This option is only valid when the Resource is an exportable resource that defin [export][02] 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` option and any JSON sent to the command -from stdin. +When this option is specified, DSC ignores the `--input` and `--path` options and any JSON or YAML +sent to the command from stdin. ```yaml Type: Boolean @@ -126,12 +174,31 @@ Mandatory: true ### -i, --input -Specifies a JSON object with the properties needed for retrieving an instance of the DSC Resource. -DSC validates the JSON against the resource's instance schema. If the validation fails, DSC raises -an error. +Specifies a JSON or YAML object with the properties needed for retrieving an instance of the DSC +Resource. DSC validates the object against the resource's instance schema. If the validation fails, +DSC raises an error. + +This option can't be used with instance properties over stdin or the `--path` option. Choose +whether to pass the instance properties to the command over stdin, from a file with the `--path` +option, or with the `--input` option. + +DSC ignores this option when the `--all` option is specified. + +```yaml +Type: String +Mandatory: false +``` + +### -p, --path + +Defines the path to a text file to read as input for the command instead of piping input from stdin +or passing it as a string with the `--input` option. The specified file must contain JSON or YAML +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. -This option can't be used with JSON over stdin. Choose whether to pass the instance JSON to the -command over stdin or with the `--input` flag. +This option is mutually exclusive with the `--input` option. When you use this option, DSC +ignores any input from stdin. DSC ignores this option when the `--all` option is specified. diff --git a/docs/reference/cli/resource/set.md b/docs/reference/cli/resource/set.md index 678d081a..14559d84 100644 --- a/docs/reference/cli/resource/set.md +++ b/docs/reference/cli/resource/set.md @@ -13,8 +13,22 @@ Invokes the set operation of a resource. ## Syntax +### Instance properties from stdin + +```sh + | dsc resource set [Options] --resource +``` + +### Instance properties from input option + ```sh -dsc resource set [Options] --resource +dsc resource set --input '' --resource +``` + +### Instance properties from file + +```sh +dsc resource set --path --resource ``` ## Description @@ -24,8 +38,10 @@ The `set` subcommand enforces the desired state of a resource instance and retur This subcommand sets one instance of a specific DSC Resource. To set multiple resources, use a resource group or the [dsc config set][01] command. -The desired state of the instance to set must be passed to this command as JSON. The JSON can be -passed to this command from stdin or with the `--input` option. +The desired state of the instance to set must be passed to this command as a JSON or YAML object. +The object properties must be valid properties for the resource. The instance properties can be +passed to this command from stdin, as a string with the `--input` option, or from a saved file with +the `--path` option. This subcommand can only be invoked for command-based DSC Resources that define the `set` section of their resource manifest. If this subcommand is called for a resource that doesn't define a set @@ -67,7 +83,7 @@ resource instance properties as JSON and passes them from stdin. ```sh '{ "keyPath": "HKCU\\Example", - "_ensure": "present" + "_exist": true }' | dsc resource set --resource Microsoft.Windows/Registry ``` @@ -79,10 +95,28 @@ resource instance properties as JSON and passes them with the **input** option. ```sh dsc resource set --resource Microsoft.Windows/Registry --input '{ "keyPath": "HKCU\\Example", - "_ensure": "present" + "_exist": true }' ``` +### Example 3 - Setting a resource with properties from a YAML file + +The command ensures that the `Example` key exists in the current user hive. It specifies the +path to a yaml file defining the resource instance properties with the **path** option. + +```sh +cat ./example.yaml +``` + +```yaml +keyPath: HKCU\\Example +_exist: true +``` + +```sh +dsc resource set --resource Microsoft.Windows/Registry --path ./example.yaml +``` + ## Options ### -r, --resource @@ -103,12 +137,29 @@ Mandatory: true ### -i, --input -Specifies a JSON object with the properties defining the desired state of a DSC Resource instance. -DSC validates the JSON against the resource's instance schema. If the validation fails, DSC raises -an error. +Specifies a JSON or YAML object with the properties defining the desired state of a DSC Resource +instance. DSC validates the object against the resource's instance schema. If the validation fails, +DSC raises an error. + +This option can't be used with instance properties over stdin or the `--path` option. Choose +whether to pass the instance properties to the command over stdin, from a file with the `--path` +option, or with the `--input` option. + +```yaml +Type: String +Mandatory: false +``` + +### -p, --path + +Defines the path to a text file to read as input for the command instead of piping input from stdin +or passing it as a string with the `--input` option. The specified file must contain JSON or YAML +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. -This option can't be used with JSON over stdin. Choose whether to pass the instance JSON to the -command over stdin or with the `--input` flag. +This option is mutually exclusive with the `--input` option. When you use this option, DSC +ignores any input from stdin. ```yaml Type: String diff --git a/docs/reference/cli/resource/test.md b/docs/reference/cli/resource/test.md index 6ee02ad8..f659ff59 100644 --- a/docs/reference/cli/resource/test.md +++ b/docs/reference/cli/resource/test.md @@ -13,8 +13,22 @@ Invokes the test operation of a resource. ## Syntax +### Instance properties from stdin + +```sh + | dsc resource set [Options] --resource +``` + +### Instance properties from input option + ```sh -dsc resource test [Options] --resource +dsc resource set --input '' --resource +``` + +### Instance properties from file + +```sh +dsc resource set --path --resource ``` ## Description @@ -24,8 +38,10 @@ The `test` subcommand validates the actual state of a resource instance against This subcommand tests one instance of a specific DSC Resource. To test multiple resources, use a resource group or the [dsc config test][01] command. -The desired state of the instance to test must be passed to this command as JSON. The JSON can be -passed to this command from stdin or with the `--input` option. +The desired state of the instance to test must be passed to this command as a JSON or YAML object. +The object properties must be valid properties for the resource. The instance properties can be +passed to this command from stdin, as a string with the `--input` option, or from a saved file with +the `--path` option. If this command is invoked for a command-based DSC Resource that doesn't define its own test operation, DSC performs a synthetic test. The synthetic test compares each property for the desired @@ -48,7 +64,7 @@ resource instance properties as JSON and passes them from stdin. ```sh '{ "keyPath": "HKCU\\Example", - "_ensure": "present" + "_exist": true }' | dsc resource test --resource Microsoft.Windows/Registry ``` @@ -60,10 +76,27 @@ resource instance properties as JSON and passes them with the **input** option. ```sh dsc resource test --resource Microsoft.Windows/Registry --input '{ "keyPath": "HKCU\\Example", - "_ensure": "present" + "_exist": true }' ``` +### Example 3 - Testing a resource with properties from a YAML file + +The command tests whether the `Example` key exists in the current user hive. It specifies the +path to a YAML file defining the resource instance properties with the **path** option. + +```sh +``` + +```yaml +keyPath: HKCU\\Example +_exist: true +``` + +```sh +dsc resource test --resource Microsoft.Windows/Registry --path ./example.yaml +``` + ## Options ### -r, --resource @@ -84,12 +117,29 @@ Mandatory: true ### -i, --input -Specifies a JSON object with the properties defining the desired state of a DSC Resource instance. -DSC validates the JSON against the resource's instance schema. If the validation fails, DSC raises -an error. +Specifies a JSON or YAML object with the properties defining the desired state of a DSC Resource +instance. DSC validates the object against the resource's instance schema. If the validation fails, +DSC raises an error. + +This option can't be used with instance properties over stdin or the `--path` option. Choose +whether to pass the instance properties to the command over stdin, from a file with the `--path` +option, or with the `--input` option. + +```yaml +Type: String +Mandatory: false +``` + +### -p, --path + +Defines the path to a text file to read as input for the command instead of piping input from stdin +or passing it as a string with the `--input` option. The specified file must contain JSON or YAML +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. -This option can't be used with JSON over stdin. Choose whether to pass the instance JSON to the -command over stdin or with the `--input` flag. +This option is mutually exclusive with the `--input` option. When you use this option, DSC +ignores any input from stdin. ```yaml Type: String