diff --git a/dsc/docs-conceptual/dsc-3.0/changelog.md b/dsc/docs-conceptual/dsc-3.0/changelog.md index 4131d4f..f592abb 100644 --- a/dsc/docs-conceptual/dsc-3.0/changelog.md +++ b/dsc/docs-conceptual/dsc-3.0/changelog.md @@ -2,7 +2,7 @@ title: "Desired State Configuration changelog" description: >- A log of the changes for releases of DSCv3. -ms.date: 01/17/2024 +ms.date: 03/06/2024 --- # Changelog @@ -22,10 +22,179 @@ This section includes a summary of user-facing changes since the last release. F changes since the last release, see the [diff on GitHub][unreleased]. -[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...main +[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.5...main +## [v3.0.0-alpha.5][release-v3.0.0-alpha.5] - 2024-02-27 + +This section includes a summary of changes for the `alpha.5` release. For the full list of changes +in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. + + +[release-v3.0.0-alpha.5]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.5 "Link to the DSC v3.0.0-alpha.5 release on GitHub" +[compare-v3.0.0-alpha.5]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...v3.0.0-alpha.5 + +### Changed + +- Updated the options for the `dsc` root command: + + - 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. + - 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][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. + +
Related work items + + - Issues: + - [#286][#286] + - [#227][#227] + - [#226][#226] + - PRs: + - [#299][#299] + - [#303][#303] + - [#305][#305] + +
+ +- Updated the JSON schemas for the [get][38], [set][39], and [test][40] output data. This change + corrects an issue with how DSC surfaced information about instances nested inside group and + adapter resources. Now when you review the output, you'll be able to see the results for each + nested instance instead of a confusing object that loses the nested instance type and name + information. + + This schema change is backwards compatible. + +
Related work items + + - Issues: + - [#165][#165] + - [#266][#266] + - [#284][#284] + - PRs: [#318][#318] + +
+ +- Changed the [concat][41] configuration function to match the behavior of the ARM template + function. The `concat()` function now only accepts strings or arrays of strings as input values. + It raises an error if the input values aren't of the same type. + +
Related work items + + - Issues: [#271][#271] + - PRs: [#322][#322] + +
+ +### Added + +- Implemented support for referencing parameters in a configuration with the [parameters()][32] + configuration function. This enables you to take advantage of parameterized configurations. Until + this release, you could define but not reference parameters. + + Now, you can use the [--parameters][33] and [--parameters-file][34] options with the + [dsc config][35] commands to pass values for any parameter defined in the configuration document. + +
Related work items + + - Issues: [#49][#49] + - PRs: + - [#291][#291] + - [#294][#294] + +
+ +- Added support for authoring DSC Resource manifests in YAML. DSC now recognizes resource manifests + that use the `.dsc.resource.yml` or `.dsc.resource.yaml` file extension instead of only + `.dsc.resource.json`. + +
Related work Items + + - Issues: [#129][#129] + - PRs: [#311][#311] + +
+ +- Added the [DSCConfigRoot][42] environment variable and the [envvar() configuration function][43] + to enable users to reference files and folders relative to the folder containing the + configuration document. DSC automatically creates the `DSCConfigRoot` environment variable when + you use the `--path` option to specify the configuration document instead of passing the document + as a string from stdin or with the `--document` option. + + > [!NOTE] + > In this release, DSC doesn't expand the specified path to an absolute path. You should always + > specify the full path to the configuration document if you want to reference the + > `DSCConfigRoot` variable in your configuration. Further, DSC always sets the value for this + > environment variable when you use the `--path` option. If the environment variable is already + > set, it overrides it silently. + > + > In a future release, the variable will be renamed to `DSC_CONFIG_ROOT` and DSC will + > automatically expand relative paths into absolute paths when setting the environment variable. + > It will also emit a warning when it overrides the variable. + +
Related work Items + + - Issues: [#75][#75] + - PRs: [#313][#313] + +
+ +- Added support for using the [dsc config export][44] and [dsc resource export][45] commands with + the PowerShell adapter resource. PSDSC resources can now participate in the `export` command if + they define a static method that returns an array of the PSDSC resource class. + +
Related work Items + + - Issues: [#183][#183] + - PRs: [#307][#307] + +
+ +- Added the `methods` column to the default table view for the console output of the + [dsc resource list][46] command. This new column indicates which methods the resource explicitly + implements. Valid values include `get`, `set`, `test`, and `export`. This information is only + available in the table view. It isn't part of the output object for the command. If you use the + [--format][47] parameter, capture the command output, or redirect the output, the `methods` + information isn't included. + + Resources that don't implement `test` rely on DSC's synthetic test behavior instead. They can + still be used for test and set operations. + + Resources that don't implement `export` can't be used with the `dsc config export` or + `dsc resource export` commands. + + Resources that don't implement `set` can be used for auditing, but not `dsc resource set`. They + can be used with the `dsc config set` command, but only if they're nested inside a + `DSC/AssertionGroup` instance. + +
Related work Items + + - Issues: [#309][#309] + - PRs: [#314][#314] + +
+ +- Added an prototype for a WMI resource adapter to enable users to query WMI. The adapter is + disabled by default, as enumerating the WMI resources can have a performance impact. To enable + it, rename the resource manifest from `wmigroup.dsc.resource.json.optout` to + `wmigroup.dsc.resource.json`. + +
Related work Items + + - Issues: [#263][#263] + - PRs: [#279][#279] + +
+ ## [v3.0.0-alpha.4][release-v3.0.0-alpha.4] - 2023-11-14 This section includes a summary of changes for the `alpha.4` release. For the full list of changes @@ -78,7 +247,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4]. ### Added -- Added the [--input][24] and [--input-file][25] global options to the root `dsc` command. Now, you +- Added the `--input` and `--input-file` global options to the root `dsc` command. Now, you can pass input to DSC from a variable or file instead of piping from stdin.
Related work items @@ -111,7 +280,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4]. - DSC now emits log messages to the stderr stream. This can make it easier to understand what DSC is doing. This doesn't affect the data output. By default, DSC emits errors, warnings, and informational messages, but not debug or trace messaging. You can control the level of the - logging with the new [--logging-level][27] option on the root `dsc` command. + logging with the new `--logging-level` option on the root `dsc` command.
Related work items @@ -463,19 +632,35 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [21]: reference/schemas/config/document.md#schema [22]: reference/schemas/resource/manifest/root.md#schema [23]: reference/schemas/resource/properties/exist.md -[24]: reference/cli/dsc.md#-i---input -[25]: reference/cli/dsc.md#-p---input-file [26]: reference/cli/completer/command.md -[27]: reference/cli/dsc.md#-l---logging-level [28]: reference/schemas/config/functions/overview.md [29]: reference/schemas/config/functions/base64.md [30]: reference/schemas/config/functions/concat.md [31]: reference/schemas/config/functions/resourceId.md + +[32]: reference/schemas/config/functions/parameters.md +[33]: reference/cli/config/command.md#-p---parameters +[34]: reference/cli/config/command.md#-f---parameters_file +[35]: reference/cli/config/command.md +[36]: reference/cli/dsc.md#-l---trace-level +[37]: reference/cli/dsc.md#-f---trace-format +[38]: reference/schemas/outputs/resource/get.md +[39]: reference/schemas/outputs/resource/set.md +[40]: reference/schemas/outputs/resource/test.md +[41]: reference/schemas/config/functions/concat.md +[42]: reference/cli/config/command.md#environment-variables +[43]: reference/schemas/config/functions/envvar.md +[44]: reference/cli/config/export.md +[45]: reference/cli/resource/export.md +[46]: reference/cli/resource/list.md +[47]: reference/cli/resource/list.md#-f---format + [#107]: https://github.com/PowerShell/DSC/issues/107 [#121]: https://github.com/PowerShell/DSC/issues/121 [#127]: https://github.com/PowerShell/DSC/issues/127 +[#129]: https://github.com/PowerShell/DSC/issues/129 [#130]: https://github.com/PowerShell/DSC/issues/130 [#133]: https://github.com/PowerShell/DSC/issues/133 [#150]: https://github.com/PowerShell/DSC/issues/150 @@ -484,6 +669,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#159]: https://github.com/PowerShell/DSC/issues/159 [#162]: https://github.com/PowerShell/DSC/issues/162 [#163]: https://github.com/PowerShell/DSC/issues/163 +[#165]: https://github.com/PowerShell/DSC/issues/165 [#168]: https://github.com/PowerShell/DSC/issues/168 [#171]: https://github.com/PowerShell/DSC/issues/171 [#172]: https://github.com/PowerShell/DSC/issues/172 @@ -494,6 +680,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#177]: https://github.com/PowerShell/DSC/issues/177 [#181]: https://github.com/PowerShell/DSC/issues/181 [#182]: https://github.com/PowerShell/DSC/issues/182 +[#183]: https://github.com/PowerShell/DSC/issues/183 [#186]: https://github.com/PowerShell/DSC/issues/186 [#197]: https://github.com/PowerShell/DSC/issues/197 [#198]: https://github.com/PowerShell/DSC/issues/198 @@ -506,11 +693,33 @@ 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 [#248]: https://github.com/PowerShell/DSC/issues/248 [#252]: https://github.com/PowerShell/DSC/issues/252 +[#263]: https://github.com/PowerShell/DSC/issues/263 +[#266]: https://github.com/PowerShell/DSC/issues/266 +[#271]: https://github.com/PowerShell/DSC/issues/271 +[#279]: https://github.com/PowerShell/DSC/issues/279 +[#284]: https://github.com/PowerShell/DSC/issues/284 +[#286]: https://github.com/PowerShell/DSC/issues/286 +[#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 +[#305]: https://github.com/PowerShell/DSC/issues/305 +[#307]: https://github.com/PowerShell/DSC/issues/307 +[#309]: https://github.com/PowerShell/DSC/issues/309 +[#311]: https://github.com/PowerShell/DSC/issues/311 +[#313]: https://github.com/PowerShell/DSC/issues/313 +[#314]: https://github.com/PowerShell/DSC/issues/314 +[#318]: https://github.com/PowerShell/DSC/issues/318 +[#322]: https://github.com/PowerShell/DSC/issues/322 [#45]: https://github.com/PowerShell/DSC/issues/45 +[#49]: https://github.com/PowerShell/DSC/issues/49 [#57]: https://github.com/PowerShell/DSC/issues/57 [#73]: https://github.com/PowerShell/DSC/issues/73 +[#75]: https://github.com/PowerShell/DSC/issues/75 [#98]: https://github.com/PowerShell/DSC/issues/98 diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md index 6ad9604..376b620 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config' command -ms.date: 09/06/2023 +ms.date: 02/05/2024 ms.topic: reference title: dsc config --- @@ -62,6 +62,42 @@ information. For example, `dsc config --help` or `dsc config set --help`. ## Options +### -f, --parameters_file + +Specifies the path to a data file containing the parameters to pass to the configuration as JSON or +YAML. When you specify this option, DSC interprets the keys in the data file as parameters and uses +the specified values. The values in the data file override any defaults defined in the +configuration itself. + +The data file must contain an object with the `parameters` key. The value of the `parameters` key +must be an object where each key is the name of a defined parameter and each value is a valid value +for that parameter. + +This option can't be used with the `--parameters` option. Choose whether to pass the parameters as +a data string with the `--parameters` option or in a data file with the `--parameters_file` option. + +For more information about defining parameters in a configuration document, see +[DSC Configuration document parameter schema][06]. For more information about using parameters in +configuration document, see the [parameters function reference][07]. + +### -p, --parameters + +Specifies the parameters to pass to the configuration as a JSON or YAML string. When you specify +this option, DSC interprets the keys in the data string as parameters and uses the specified +values. The values in the data string override any defaults defined in the configuration itself. + +The data string must contain an object with the `parameters` key. The value of the `parameters` key +must be an object where each key is the name of a defined parameter and each value is a valid value +for that parameter. + +This option can't be used with the `--parameters_file` option. Choose whether to pass the +parameters as a data string with the `--parameters` option or in a data file with the +`--parameters_file` option. + +For more information about defining parameters in a configuration document, see +[DSC Configuration document parameter schema][06]. For more information about using parameters in +configuration document, see the [parameters function reference][07]. + ### -h, --help Displays the help for the current command or subcommand. When you specify this option, the @@ -72,8 +108,26 @@ Type: Boolean Mandatory: false ``` +## Environment variables + +The `dsc config *` subcommands create the `DSCConfigRoot` environment variable when you call a +command with the `--path` option to specify the configuration document to use for the command. DSC +sets the value of the `DSCConfigRoot` environment variable to the folder containing the specified +configuration document. + +> [!NOTE] +> If you use a relative path, DSC doesn't expand the value into a full path before setting the +> environment variable. Always specify the full path to the configuration document when you want to +> use the `DSCConfigRoot` environment variable. + +You can use the [envvar][08] configuration function to reference that folder path for resource +instances in the configuration. + [01]: ../resource/command.md [02]: export.md [03]: get.md [04]: set.md [05]: test.md +[06]: ../../schemas/config/parameter.md +[07]: ../../schemas/config/functions/parameters.md +[08]: ../../schemas/config/functions/envvar.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/export.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/export.md index c4e2016..3611688 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/export.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/export.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config export' command -ms.date: 09/06/2023 +ms.date: 03/06/2024 ms.topic: reference title: dsc config export --- @@ -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] +``` + +### Configuration document from option string + ```sh -dsc config export [Options] +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,48 @@ 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 +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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md index 36e4755..e306375 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config get' command -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: dsc config get --- @@ -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,67 @@ 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 +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 @@ -92,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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md index 77e63d1..e6dd3da 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config set' command -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: dsc config set --- @@ -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,67 @@ 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 +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 @@ -93,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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md index 995d6eb..51b5e8a 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config test' command -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: dsc config test --- @@ -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,67 @@ 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 +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 @@ -92,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/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md index 8f0b622..5703da4 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/dsc.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc' command -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: dsc --- @@ -69,21 +69,6 @@ example, `dsc config --help` or `dsc config set --help`. ## 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. - -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 @@ -94,59 +79,52 @@ 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. +### -l, --trace-level -To pass input for a command or subcommand, specify this option before the command, like -`dsc --input $desired resource test`. +Defines the minimum message level DSC should emit during an operation. Messages in DSC are +categorized by their level. -```yaml -Type: String -Mandatory: false -``` - -### -l, --logging-level - -Defines the minimum log level DSC should emit during an operation. Messages in DSC are categorized -by their log level. - -The following list shows the valid log levels from highest to lowest level. When this option is +The following list shows the valid message levels from highest to lowest level. When this option is set to any value in the list, DSC emits messages at that level and above. -- `Error` -- `Warning` -- `Info` (default) -- `Debug` -- `Trace` +- `error` +- `warning` (default) +- `info` +- `debug` +- `trace` -For example, when the log level is `Debug`, DSC emits messages for every log level except `Trace`. -Dsc emits only error messages when the log level is `Error`. DSC ignores every message with a lower -log level. +> [!WARNING] +> The `trace` level output emits all JSON input/output that DSC processes during execution. DSC +> doesn't sanitize the JSON before emitting it. This trace level is only intended for developer +> use. Never redirect `trace` level output to storage as it may contain sensitive information. + +For example, when the log level is `debug`, DSC emits messages for every log level except `trace`. +When the log level is `error`, DSC only emits error messages. DSC ignores every message with a +lower log level. ```yaml -Type: String -Mandatory: false -DefaultValue: Info -ValidValues: [Error, Warning, Info, Debug, Trace] +Type: String +Mandatory: false +DefaultValue: warning +ValidValues: [error, warning, info, debug, trace] ``` -### -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. +### -f, --trace-format -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`. +Defines the output format to use when emitting trace messages on stderr. DSC supports the following +formats: -If the specified file doesn't exist, DSC raises an error. +- `default` - Emits the message with ANSI console coloring for the timestamp, message level, and + line number. +- `plaintext` - As `default` but without any console colors. +- `json` - Emits each message as a compressed JSON object with the timestamp, level, message, and + line number as properties. ```yaml -Type: String -Mandatory: false +Type: String +Mandatory: false +DefaultValue: default +ValidValues: [default, plaintext, json] ``` ### -V, --version diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/export.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/export.md index 952d668..f399dd9 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/export.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/export.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource export' command -ms.date: 09/06/2023 +ms.date: 03/06/2024 ms.topic: reference title: dsc resource export --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/get.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/get.md index 318925d..c5c18da 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/get.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource get' command -ms.date: 09/06/2023 +ms.date: 03/06/2024 ms.topic: reference title: dsc resource get --- @@ -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,13 @@ 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 JSON over stdin. Choose whether to pass the instance JSON to the -command over stdin or with the `--input` flag. +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. @@ -140,6 +189,36 @@ 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 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. + +```yaml +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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md index 2c44ae1..fb9b1b6 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource list' command -ms.date: 08/04/2023 +ms.date: 03/06/2024 ms.topic: reference title: dsc resource list --- @@ -21,8 +21,8 @@ dsc resource list [Options] 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` files. For more information about the environment variables DSC uses, see -[Environment variables][01] +`.dsc.resource.json`, `.dsc.resource.yml`, and `dsc.resource.yaml` files. For more information +about the environment variables DSC uses, see [Environment variables][01] If any of the discovered resources are resource providers, DSC then calls the providers to list their resources, too. @@ -43,17 +43,21 @@ dsc resource list ``` ```Output -type version tags description ----- ------- ---- ----------- -Test/TestGroup 0.1.0 -Microsoft/OSInfo 0.1.0 {os, linux, windows, macos} Returns information about the operating system. -Microsoft.Windows/Registry 0.1.0 {Windows, NT} Registry configuration provider for the Windows Registry - This is a test resource. -DSC/PowerShellGroup 0.1.0 {PowerShell} Resource provider to classic DSC Powershell resources. -DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration. -DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently. - This is a test resource. -DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +Type Version Methods Requires Description +---------------------------------------------------------------------------------------------------------------------------------------------------- +DSC.PackageManagement/Brew 0.1.0 get, set, export DSC resource to manage Homebrew packages +DSC/AssertionGroup 0.1.0 get, set, test `test` will be invoked for all resources in the supplied configuration. +DSC/Group 0.1.0 get, set, test All resources in the supplied configuration is treated as a group. +DSC/ParallelGroup 0.1.0 get, set, test All resources in the supplied configuration run concurrently. +DSC/PowerShellGroup 0.1.0 get, set, test, export Resource provider to classic DSC Powershell resources. +Microsoft.Windows/Registry 0.1.0 get, set, test Registry configuration provider for the Windows Registry +Microsoft/OSInfo 0.1.0 get, export Returns information about the operating system. +Microsoft/Process 0.1.0 get, set, test, export Returns information about running processes. +Test/Echo 0.1.0 get, set, test +Test/Sleep 0.1.0 get, set, test +Test/TestGroup 0.1.0 get +Test/TestResource1 1.0.0 get Test/TestGroup This is a test resource. +Test/TestResource2 1.0.1 get Test/TestGroup This is a test resource. ``` ### Example 2 - List a specific resource @@ -66,9 +70,9 @@ dsc resource list DSC/Group ``` ```Output -Type Version Requires Description ------------------------------------------------------------------------------------------------- -DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +Type Version Methods Requires Description +---------------------------------------------------------------------------------------------------------------- +DSC/Group 0.1.0 get, set, test All resources in the supplied configuration is treated as a group. ``` ### Example 3 - List resources with a matching type name @@ -81,12 +85,12 @@ dsc resource list DSC/* ``` ```Output -Type Version Requires Description ---------------------------------------------------------------------------------------------------------------- -DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. -DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently. -DSC/PowerShellGroup 0.1.0 Resource provider to classic DSC Powershell resources. -DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration. +Type Version Methods Requires Description +--------------------------------------------------------------------------------------------------------------------------------------- +DSC/AssertionGroup 0.1.0 get, set, test `test` will be invoked for all resources in the supplied configuration. +DSC/Group 0.1.0 get, set, test All resources in the supplied configuration is treated as a group. +DSC/ParallelGroup 0.1.0 get, set, test All resources in the supplied configuration run concurrently. +DSC/PowerShellGroup 0.1.0 get, set, test, export Resource provider to classic DSC Powershell resources. ``` ### Example 4 - List resources with a matching description @@ -99,11 +103,11 @@ dsc resource list --description 'supplied configuration' ``` ```Output -Type Version Requires Description --------------------------------------------------------------------------------------------------------------- -DSC/ParallelGroup 0.1.0 All resources in the supplied configuration run concurrently. -DSC/AssertionGroup 0.1.0 `test` will be invoked for all resources in the supplied configuration. -DSC/Group 0.1.0 All resources in the supplied configuration is treated as a group. +Type Version Methods Requires Description +------------------------------------------------------------------------------------------------------------------------------ +DSC/AssertionGroup 0.1.0 get, set, test `test` will be invoked for all resources in the supplied configuration. +DSC/Group 0.1.0 get, set, test All resources in the supplied configuration is treated as a group. +DSC/ParallelGroup 0.1.0 get, set, test All resources in the supplied configuration run concurrently. ``` ### Example 5 - List resources with matching tags @@ -116,10 +120,10 @@ dsc resource list --tags Windows --tags Linux ``` ```output -Type Version Requires Description -------------------------------------------------------------------------------------------------------- -Microsoft.Windows/Registry 0.1.0 Registry configuration provider for the Windows Registry -Microsoft/OSInfo 0.1.0 Returns information about the operating system. +Type Version Methods Requires Description +----------------------------------------------------------------------------------------------------------------------- +Microsoft.Windows/Registry 0.1.0 get, set, test Registry configuration provider for the Windows Registry +Microsoft/OSInfo 0.1.0 get, export Returns information about the operating system. ``` ## Arguments @@ -167,6 +171,20 @@ 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 a series of JSON Lines representing each +returned resource. When this option isn't specified, the output for the command shows a table +representing a summary of the returned resources. For more information, see [Output](#output). + +```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 @@ -183,5 +201,21 @@ This command returns a JSON object for each resource that includes the resource' manifest settings, and other metadata. For more information, see [dsc resource list result schema][02]. +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. +- **Version** - The semantic version of the resource. +- **Methods** - A comma-separated list of the implemented methods for the resource. Valid methods + are `get`, `set`, `test`, and `export`. Resources that don't implement `test` rely on DSC's + synthetic test functionality. +- **Requires** - The fully qualified type name of the provider resource that DSC uses to invoke the + returned resource. +- **Description** - The short description of the resource's purpose and usage. + +To display the output objects as either JSON or YAML objects in the console, use the +[--format](#-f---format) option. + [01]: ../dsc.md#environment-variables [02]: ../../schemas/outputs/resource/list.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md index 9ae0e6a..282ce3a 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/schema.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource schema' command -ms.date: 08/04/2023 +ms.date: 03/06/2024 ms.topic: reference title: dsc resource schema --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/set.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/set.md index 691a7e2..215244c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/set.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource set' command -ms.date: 09/27/2023 +ms.date: 03/06/2024 ms.topic: reference title: dsc resource set --- @@ -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 --input '' --resource +``` + +### Instance properties from file + ```sh -dsc resource set [Options] --resource +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,18 +137,47 @@ 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 JSON over stdin. Choose whether to pass the instance JSON to the -command over stdin or with the `--input` flag. +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 is mutually exclusive with the `--input` 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 +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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/test.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/test.md index 0b309bc..6832651 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/test.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource test' command -ms.date: 08/04/2023 +ms.date: 03/06/2024 ms.topic: reference title: dsc resource test --- @@ -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 set --input '' --resource +``` + +### Instance properties from file + ```sh -dsc resource test [Options] --resource +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,18 +117,47 @@ 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 JSON over stdin. Choose whether to pass the instance JSON to the -command over stdin or with the `--input` flag. +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 is mutually exclusive with the `--input` 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 +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/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md index efce718..5bdb0a5 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/schema/command.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc schema' command -ms.date: 08/04/2023 +ms.date: 03/06/2024 ms.topic: reference title: dsc schema --- @@ -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 diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md index 8218480..9b132e4 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md @@ -1,6 +1,6 @@ --- description: Reference for the 'concat' DSC configuration document function -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: concat --- @@ -24,22 +24,23 @@ string. Separate each value with a comma. The `concat()` function is variadic. Y least two values to the function. The function can accept any number of arguments. The function concatenates the input values without any joining character. It accepts only strings -and integers as input values. +or arrays of strings as input values. The input values must be of the same type. If you pass a +string and an array to the same function, the function raises an error. ## Examples ### Example 1 - Concatenate strings -The configuration uses the `concat()` function to join the string `abc` and the integer `123` +The configuration uses the `concat()` function to join the strings `abc` and `def` ```yaml # concat.example.1.dsc.config.yaml $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json resources: - - name: Echo 'abc123' + - name: Echo 'abcdef' type: Test/Echo properties: - text: "[concat('abc', 123)]" + output: "[concat('abc', 'def')]" ``` ```bash @@ -48,11 +49,11 @@ dsc --input-file concat.example.1.dsc.config.yaml config get ```yaml results: -- name: Echo 'abc123' +- name: Echo 'abcdef' type: Test/Echo result: actualState: - text: abc123 + output: abcdef messages: [] hadErrors: false ``` @@ -61,11 +62,11 @@ hadErrors: false ### inputValue -A value to concatenate. Each value must be either a string or an integer. The values are added to -the output string in the same order you pass them to the function. +A value to concatenate. Each value must be either a string or an array of strings. The strings are +are added to the output string in the same order you pass them to the function. ```yaml -Type: [string, integer] +Type: [string, array] Required: true MinimumCount: 2 MaximumCount: 18446744073709551615 diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md new file mode 100644 index 0000000..9d42b34 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md @@ -0,0 +1,85 @@ +--- +description: Reference for the 'envvar' DSC configuration document function +ms.date: 03/06/2024 +ms.topic: reference +title: envvar +--- + +# envvar + +## Synopsis + +Returns the value of an environment variable. + +## Syntax + +```Syntax +envvar() +``` + +## Description + +The `envvar()` function returns the value of an environment variable as a string. If the +environment variable doesn't exist, the function returns an empty string. + +## Examples + +### Example 1 - Reference DSCConfigRoot in a configuration + +When you use the `--path` option to specify a configuration document for any of the `dsc config *` +commands, DSC automatically creates the `DSCConfigRoot` environment variable and sets the value to +the parent folder of the specified configuration document. For more information, see +[dsc config command reference][01]. + +This configuration echoes that folder with the `Test/Echo` resource. + +```yaml +# ./examples/envvar.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +resources: + - name: Echo 'DSCConfigRoot' in envvar + type: Test/Echo + properties: + output: "[envvar('DSCConfigRoot')]" +``` + +```bash +dsc config get --path ~/dsc/examples/envvar.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Echo DSCConfigRoot + type: Test/Echo + result: + actualState: + output: ~/dsc/examples +messages: [] +hadErrors: false +``` + +## Parameters + +### variableName + +The value must be a single string representing the name of the environment variable to use. If +the value isn't a string, DSC raises an error when validating the configuration document. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The output of the function is the value of the environment variable specified with the +**variableName** parameter. If the environment variable doesn't exist, the function returns an +empty string. + +```yaml +Type: string +``` + +[01]: ../../../cli/config/command.md#environment-variables diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md new file mode 100644 index 0000000..e25706e --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md @@ -0,0 +1,112 @@ +--- +description: Reference for the 'parameters' DSC configuration document function +ms.date: 03/06/2024 +ms.topic: reference +title: parameters +--- + +# parameters + +## Synopsis + +Returns the value of a configuration parameter. + +## Syntax + +```Syntax +parameters('') +``` + +## Description + +The `parameters()` function returns the value of a specific parameter. You must pass the name of +a valid parameter. When using this function for a resource instance, DSC validates the instance +properties after this function runs and before calling the resource for the current operation. If +the referenced parameter value is invalid for the property, DSC raises a validation error. + +For more information about defining parameters in a configuration document, see +[DSC Configuration document parameter schema][01]. + +## Examples + +### Example 1 - Use a parameter as a resource instance property value + +The configuration uses the `parameters()` function to echo the value of the `message` parameter. + +```yaml +# parameters.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +parameters: + message: + type: string + defaultValue: Hello, world! +resources: + - name: Echo message parameter + type: Test/Echo + properties: + text: "[parameters('message')]" +``` + +First, get the current state of the configuration without overriding the parameters with the +[--parameters][02] or [`--parameters_file`][03] options. The output shows the default value for the +`message` parameter. + +```bash +config_file=parameters.example.1.dsc.config.yaml +cat $config_file | dsc config get +``` + +```yaml +results: +- name: Echo message parameter + type: Test/Echo + result: + actualState: + text: Hello, world! +messages: [] +hadErrors: false +``` + +Next, override the `message` parameter with the `--parameters` option. + +```bash +params='{"parameters": {"message": "Hi, override."}}' +cat $config_file | dsc config --parameters $params get +``` + +```yaml +results: +- name: Echo message parameter + type: Test/Echo + result: + actualState: + text: Hi, override. +messages: [] +hadErrors: false +``` + +## Parameters + +### name + +The name of the parameter to return. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The output of the function is the value of the specified parameter. + +```yaml +Type: [string, int, bool, object, array] +``` + + +[01]: ../parameter.md +[02]: ../../../cli/config/command.md#-p---parameters +[03]: ../../../cli/config/command.md#-f---parameters_file diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md index 81b9eff..23238e8 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc config set' command. -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: dsc config set result schema reference --- @@ -70,8 +70,8 @@ Required: true #### result -An item's `result` property includes the actual state for the resource instance. The value for this -property adheres to the same schema as the output for the `dsc resource set` command. For more +An item's `result` property includes the enforced state for the resource instance. The value for +this property adheres to the same schema as the output for the `dsc resource set` command. For more information, see [dsc resource set result schema reference][02]. ### messages diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md index 0faa28e..f828978 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc config test' command. -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: dsc config test result schema reference --- @@ -70,9 +70,9 @@ Required: true #### result -An item's `result` property includes the actual state for the resource instance. The value for this -property adheres to the same schema as the output for the `dsc resource test` command. For more -information, see [dsc resource test result schema reference][02]. +An item's `result` property includes the validation state for the resource instance. The value for +this property adheres to the same schema as the output for the `dsc resource test` command. For +more information, see [dsc resource test result schema reference][02]. ### messages diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md index 552d49b..d4ef6e5 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource get' command. -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: dsc resource get result schema reference --- @@ -21,18 +21,33 @@ Type: object ## Description -The output from the `dsc resource get` command includes the actual state for the specified resource -instance. +Describes the return data for a DSC Resource instance from the `dsc resource get` command. The +return data is either a single object that describes the actual state of a non-nested instance or +an array of objects that describe the actual state of the nested instances for a group or adapter +resource. -## Required properties +DSC returns a [simple get response](#simple-get-response) when the instance isn't a group resource, +adapter resource, or nested inside a group or adapter resource. + +When the retrieved instance is for group resource, adapter resource, or nested inside a group or +adapter resource, DSC returns a [full get result](#full-get-result), which also includes the +resource type and instance name. + +## Simple get response + +Describes the return data for a single DSC Resource instance from the `dsc resource get` command. +This data is returned for instances that aren't group resources, adapter resources, or nested +inside a group or adapter resource. + +### Required properties The output always includes these properties: - [actualState](#actualstate) -## Properties +### Properties -### actualState +#### actualState The `actualState` property always includes the state of the instance returned when DSC invokes the resource's get operation. DSC validates this property's value against the resource's instance @@ -42,3 +57,55 @@ schema. Type: object Required: true ``` + +## Full get result + +Describes the return data for the full result of the `get` operation for a resource instance. This +data is returned: + +- For every instance in a configuration document when you use the `dsc config get` command. +- For nested instances of a group or adapter resource when you use the `dsc resource get` command. + +### Required properties + +- [name](#name) +- [type](#type) +- [result](#result) + +### Properties + +#### type + +The `type` property identifies the instance's DSC Resource by its fully qualified type name. +For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +The `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +The `result` property includes the actual state for the resource. This value is either: + +- The [simple get response](#simple-get-response) for the instance +- An array of full get result objects for each nested instance, if the resource is a group or + adapter resource. + +```yaml +Type: [object, array] +Required: true +``` + +[01]: ../../definitions/resourceType.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md index c7ab0cf..951304b 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource set' command. -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: dsc resource set result schema reference --- @@ -21,10 +21,26 @@ Type: object ## Description -The output from the `dsc resource set` command includes the state of the resource instance before -and after the set operation, and the list of properties the operation changed. +Describes the return data for a DSC Resource instance from the `dsc resource set` command. The +return data is either a single object that describes the enforced state of a non-nested instance or +an array of objects that describe the enforced state of the nested instances for a group or adapter +resource. -## Required properties +DSC returns a [simple set response](#simple-set-response) when the instance isn't a group resource, +adapter resource, or nested inside a group or adapter resource. + +When the retrieved instance is for group resource, adapter resource, or nested inside a group or +adapter resource, DSC returns a [full set result](#full-set-result), which also includes the +resource type and instance name. + +## Simple set response + +Describes the return data for a DSC Resource instance from the `dsc resource set` command. The +return data is either a single object that describes the enforced state of a non-nested instance or +an array of objects that describe the enforced state of the nested instances for a group or adapter +resource. + +### Required properties The output always includes these properties: @@ -32,9 +48,9 @@ The output always includes these properties: - [afterState](#afterstate) - [changedProperties](#changedproperties) -## Properties +### Properties -### beforeState +#### beforeState Represents the state of the instance returned before the set operation. DSC validates this property's value against the resource's instance schema. @@ -44,7 +60,7 @@ Type: object Required: true ``` -### afterState +#### afterState Represents the state of the instance returned after the set operation. DSC validates this property's value against the resource's instance schema. @@ -54,7 +70,7 @@ Type: object Required: true ``` -### changedProperties +#### changedProperties Defines the names of the properties the set operation enforced. If this value is an empty array, the resource made no changes during the set operation. @@ -64,3 +80,55 @@ Type: array Required: true ItemsType: string ``` + +## Full set result + +Describes the return data for the full result of the `set` operation for a resource instance. This +data is returned: + +- For every instance in a configuration document when you use the `dsc config set` command. +- For nested instances of a group or adapter resource when you use the `dsc resource set` command. + +### Required properties + +- [name](#name) +- [type](#type) +- [result](#result) + +### Properties + +#### type + +The `type` property identifies the instance's DSC Resource by its fully qualified type name. +For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +The `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +The `result` property includes the enforced state for the resource. This value is either: + +- The [simple set response](#simple-set-response) for the instance +- An array of full set result objects for each nested instance, if the resource is a group or + adapter resource. + +```yaml +Type: [object, array] +Required: true +``` + +[01]: ../../definitions/resourceType.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md index 4df6739..0bafeb5 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource test' command. -ms.date: 01/17/2024 +ms.date: 03/06/2024 ms.topic: reference title: dsc resource test result schema reference --- @@ -21,18 +21,29 @@ Type: object ## Description -The output from the `dsc resource test` command includes the actual state for the specified -resource instance. +Describes the return data for a DSC Resource instance from the `dsc resource get` command. The +return data is either a single object that describes the tested state of a non-nested instance or +an array of objects that describe the tested state of the nested instances for a group or adapter +resource. -## Required properties +DSC returns a [simple test response](#simple-test-response) when the instance isn't a group +resource, adapter resource, or nested inside a group or adapter resource. + +When the retrieved instance is for group resource, adapter resource, or nested inside a group or +adapter resource, DSC returns a [full test result](#full-test-result), which also includes the +resource type and instance name. + +## Simple test response + +### Required properties The output always includes these properties: - [desiredState](#desiredstate) -## Properties +### Properties -### desiredState +#### desiredState Represents the desired state of the resource instance. DSC validates this property's value against the resource's instance schema. @@ -42,7 +53,7 @@ Type: object Required: true ``` -### actualState +#### actualState Represents the actual state of the resource instance. DSC validates this property's value against the resource's instance schema. @@ -52,7 +63,7 @@ Type: object Required: true ``` -### inDesiredState +#### inDesiredState Indicates whether the resource instance's properties are in the desired state. This value is `true` if every property is in the desired state and otherwise `false`. @@ -62,7 +73,7 @@ Type: boolean Required: true ``` -### differingProperties +#### differingProperties Defines the names of the properties that aren't in the desired state. If this value is an empty array, the instance's properties are in the desired state. @@ -72,3 +83,55 @@ Type: array Required: true ItemsType: string ``` + +## Full test result + +Describes the return data for the full result of the `test` operation for a resource instance. This +data is returned: + +- For every instance in a configuration document when you use the `dsc config test` command. +- For nested instances of a group or adapter resource when you use the `dsc resource test` command. + +### Required properties + +- [name](#name) +- [type](#type) +- [result](#result) + +### Properties + +#### type + +The `type` property identifies the instance's DSC Resource by its fully qualified type name. +For more information about type names, see +[DSC Resource fully qualified type name schema reference][01]. + +```yaml +Type: string +Required: true +Pattern: ^\w+(\.\w+){0,2}\/\w+$ +``` + +#### name + +The `name` property identifies the instance by its short, unique, human-readable name. + +```yaml +Type: string +Required: true +``` + +#### result + +The `result` property includes the validation state for the resource. This value is either: + +- The [simple test response](#simple-test-response) for the instance +- An array of full get result objects for each nested instance, if the resource is a group or + adapter resource. + +```yaml +Type: [object, array] +Required: true +``` + +[01]: ../../definitions/resourceType.md