diff --git a/.vscode/docs.code-snippets b/.vscode/docs.code-snippets index 07bacd93..64e989a9 100644 --- a/.vscode/docs.code-snippets +++ b/.vscode/docs.code-snippets @@ -137,7 +137,7 @@ " - Issues: [#${2:related issue id}][#${2:related issue id}]", " - PRs: [#${3:related pull request id}][#${3:related pull request id}]", "", - "
", + "
", "" ] } @@ -155,7 +155,7 @@ " - PRs:", " - [#${3:related pull request id}][#${3:related pull request id}]", "", - "
", + "
", "" ] } diff --git a/CHANGELOG.md b/CHANGELOG.md index 41573dd4..2a5efa85 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,7 +45,7 @@ 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.5...main +[unreleased]: https://github.com/PowerShell/DSC/compare/v3.0.0-preview.7...main + + +## [v3.0.0-preview.7][release-v3.0.0-preview.7] - 2024-04-22 + +This section includes a summary of changes for the `preview.7` release. For the full list of changes +in this release, see the [diff on GitHub][compare-v3.0.0-preview.7]. + + +[release-v3.0.0-preview.7]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-preview.7 "Link to the DSC v3.0.0-preview.7 release on GitHub" +[compare-v3.0.0-preview.7]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.4...v3.0.0-preview.7 + ### Changed -- The [envvar()][a5.12] function now raises an error when the specified environment variable +- The version segment of the schema URIs for DSC have been updated from `2023/10` to `2024/04` to + accommodate breaking schema changes from the schemas that `alpha.5` used. You can find more + information about the specific changes to the schemas in the following changelog entries: + + - [Renamed 'providers' to 'adapters'](#rename-provider-to-adapter) + - [Added the 'delete' operation for resources](#add-delete-operation) + - [Added the option to specify a required security context for a configuration document](#add-elevation-requirement) + - [Add option to specify a JSON input argument for resource commands](#add-json-input-arg) + - [Add 'kind' property to resource manifests](#add-kind-property) + - [Camel-cased 'SecureObject' and 'SecureString' parameter types](#camel-casing-secure-types) + - [Add 'capabilities' to 'dsc resource list' output](#add-capabilities) + - [Added metadata to config and resource output](#add-metadata-output) + + Update your configuration documents and resource manifests to use the following URIs for the + `$schema` keyword: + + ```yaml + Canonical URI for configuration documents: >- + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + + Bundled URI for configuration documents: >- + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json + + Enhanced Authoring in VS Code URI for configuration documents: >- + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json + + Canonical URI for resource manifests: >- + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json + + Bundled URI for resource manifests: >- + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json + + Enhanced Authoring in VS Code URI for resource manifests: >- + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json + ``` + +
Related work items + + - Issues: _None_. + - PRs: [#397][#397] + +
+ +- In this release, the term `DSC Resource Provider` is + replaced with the more semantically accurate `DSC Resource Adapter`. These resources enable users + to leverage resources that don't define a DSC Resource Manifest with DSC, like PSDSC resources - + they're _adapters_ between DSCv3 and resources defined in a different way. + + Beyond using different terminology in the documentation, this change also renamed the resource + manifest property `provider` to [adapter][p7-01], and the `requires` property in the output for + `dsc resource list` has been renamed to [requireAdapter][p7-02]. + +
Related work items + + - Issues: [#310][#310] + - PRs: + - [#334][#334] + - [#373][#373] + +
+ +- Changed the casing for the [parameter type enums][p7-03] + from `SecureString` to `secureString` and `SecureObject` to `secureObject`, to better match the + type enumerations in ARM. + +
Related work items + + - Issues: _None_. + - PRs: [#364][#364] + +
+ +- The [envvar()][envvar()] function now raises an error when the specified environment variable doesn't exist instead of returning an empty string. This change helps reduce unexpected and difficult to diagnose errors when a configuration expects a value from the environment variable. @@ -81,25 +164,179 @@ changes since the last release, see the [diff on GitHub][unreleased]. - Issues: [#336][#336] - PRs: [#358][#358] -
+
+ +- Renamed the `DscConfigRoot` environment variable to `DSC_CONFIG_ROOT`. DSC now correctly + absolutizes the variable, even when the path to a configuration document is a relative path. DSC + also raises a warning when you define the environment variable outside of DSC before overriding + it. + +
Related work items + + - Issues: + - [#317][#317] + - [#335][#335] + - PRs: [#342][#342] + +
+ +- Updated the default behavior of the [dsc resource list][cmd-rlist] command and added the new + [--adapter][p7-04] option to the command. + + Prior to this release, the command always called the `list` command for any discovered adapters, + even when searching for a non-adapted resource by name. Enumerating the adapted resources can be + a slow process, so the command no longer calls the adapters to list their adapted resources by + default. + + Instead, you can use the `--adapter` option to specify a filter for the adapters you want to list + adapted resources for. Specify the fully qualified type name of an adapter or a string including + wildcards (`*`) to use as a filter for adapter names. You can specify the filter `*` to have DSC + call the `list` operation for every discovered adapter, returning all adapted resources. + + For more information, see [dsc resource list][cmd-rlist]. + +
Related work items + + - Issues: + - [#274][#274] + - [#368][#368] + - PRs: [#377][#377] + +
+ +- Updated the table view for the [dsc resource list][cmd-rlist] command to display the resource + kind and capabilities. The capabilities column in the table uses bit flags for the display to + keep the column width manageable. + + For more information, see the "Output" section of [dsc resource list][cmd-rlist]. + +
Related work items + + - Issues: [#329][#329] + - PRs: [#346][#346] + +
### Added -- Added configuration functions: +- Added the [dsc resource delete][cmd-rdelete] command and the + [delete][p7-05] operation property to the resource manifest. Prior to this release, resources had + to handle deleting resources as part of their `set` operation, and the development guidance was + to use the [_exist][p7-06] standard property to indicate whether a resource should exist. + + Now, resource authors can indicate through the resource manifest whether the resource supports + the `delete` operation with a separate command or as part of the `set` operation. It can be + simpler to implement a separate `delete` operation than to handle deleting instances as part of + `set`. You can implement your resource to have an explicit `delete` command and handle deleting + instances as part of a `set` operation. + + You can also use the `dsc resource delete` command to delete instances one at a time. For this + command, the JSON input defines the filter to pass to the resource for deleting the instance. For + more information, see [dsc resource delete command reference][cmd-rdelete]. + + If your resource handles deleting instances as part of `set`, use the [handlesExist][p7-07] + property to tell DSC so. When this property is `true`, the resource has the + [SetHandlesExist capability][p7-08]. + + If your resource has a separate command for deleting instances, use the [delete][p7-05] property + in your resource manifest to tell DSC and other tools how to invoke the operation. When this + property is defined, the resource has the [Delete capability][p7-09]. + + If your resource handles deleting instances, you should add the `_exist` standard property to the + resource's [instance schema][p7-10]. While you can use any property name for this, DSC is only aware of + deletion operations when you use the `_exist` property. DSC won't know to call the `delete` + operation for resources that don't have the [SetHandlesExist][p7-08] capability. + + For resources that implement `delete` but don't handle `_exist` in the `set` operation, DSC can + now invoke the delete operation as-needed in a configuration whenever it enforces the desired + state for an instance of a resource with the `_exist` property set to `false`. + +
Related work items + + - Issues: [#290][#290] + - PRs: + - [#379][#379] + - [#382][#382] + +
+ +- Added the option to specify whether a configuration + document requires root or elevated permissions. Now, you can define the `securityContext` + metadata property under the `Microsoft.DSC` namespace in a configuration document to specify + which security context to use: + + - `Current` - Any security context. This is the default if you don't specify this property in a + configuration document. + - `Elevated` - Elevated as root or an administrator. + - `Restricted` - Not elevated as root or an administrator. + + For example, the following metadata at the top of a configuration document indicates that DSC + must run as a normal user account, not root or administrator: + + ```yaml + metadata: + Microsoft.DSC: + securityContext: restricted + ``` + + For more information, see [DSC Configuration document metadata schema][p7-11]. + +
Related work items + + - Issues: [#258][#258] + - PRs: [#351][#351] + +
+ +- Added the option to define a JSON input argument for resource + commands. When you define the `args` list for the following commands, you can now define a + special argument that the command expects to receive the compressed JSON data for: + + - [delete][p7-12] + - [export][p7-13] + - [get][p7-14] + - [set][p7-15] + - [test][p7-16] + - [validate][p7-17] + + DSC sends data to these commands in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a + string representing the data as a compressed JSON object to the specified argument. + + If you don't define the `input` property and don't define a JSON input argument, DSC can't pass + the input JSON to the resource. You can only define one JSON input argument for a command. - - New mathematics functions include [add()][ur.01], [div()][ur.02], [max()][ur.03], - [min()][ur.04], [mod()][ur.05], [mul()][ur.06], and [sub()][ur.07]. The mathematics functions + You must define the `input` property, one JSON input argument in the `args` property array, or + both. For more information, see the relevant schema documentation for the command property. + +
Related work items + + - Issues: [#218][#218] + - PRs: [#385][#385] + +
+ +- Added configuration functions: + + - New mathematics functions include [add()][add()], [div()][div()], [max()][max()], + [min()][min()], [mod()][mod()], [mul()][mul()], and [sub()][sub()]. The mathematics functions only operate on integer values. - - The [reference()][ur.08] function enables you to reference the result output for other + - The [reference()][reference()] function enables you to reference the result output for other resources, so you can use properties of one resource instance as values for another. The `reference()` function only works for resources that DSC has already managed in a configuration. You should always add the resource you're referencing with the `reference()` - function to the [dependsOn][ur.09] list for the instance using the reference. + function to the [dependsOn][p7-18] list for the instance using the reference. - - The [createArray()][ur.10] function enables you to create arrays of a given type from values. + - The [createArray()][createArray()] function enables you to create arrays of a given type from + values. - - The [int()][ur.11] function enables you to convert strings and numbers with fractional parts + - The [int()][int()] function enables you to convert strings and numbers with fractional parts into integers.
Related work items @@ -117,20 +354,204 @@ changes since the last release, see the [diff on GitHub][unreleased]. - [#375][#375] - [#376][#376] -
+
- -[ur.01]: ./docs/reference/schemas/config/functions/add.md -[ur.02]: ./docs/reference/schemas/config/functions/div.md -[ur.03]: ./docs/reference/schemas/config/functions/max.md -[ur.04]: ./docs/reference/schemas/config/functions/min.md -[ur.05]: ./docs/reference/schemas/config/functions/mod.md -[ur.06]: ./docs/reference/schemas/config/functions/mul.md -[ur.07]: ./docs/reference/schemas/config/functions/sub.md -[ur.08]: ./docs/reference/schemas/config/functions/reference.md -[ur.09]: ./docs/reference/schemas/config/resource.md#dependsOn -[ur.10]: ./docs/reference/schemas/config/functions/createArray.md -[ur.11]: ./docs/reference/schemas/config/functions/int.md +- Added the [kind][p7-19] property to the resource manifest schema + and the [output][p7-20] for the [dsc resource list][cmd-rlist] command. This property indicates + whether the resource is a [group resource][p7-21] (`Group`), an [adapter resource][p7-22] + (`Adapter`), or neither (`Resource`). For more information, see + [DSC Resource kind schema reference][p7-23]. + + This property is mandatory in the resource manifest for group resources. If your resource + manifest doesn't define the `kind` property, DSC can infer whether the resource is an adapter + resource or not. Microsoft recommends always explicitly defining this property in resource + manifests, because the schema can apply enhanced validation based on the value of the `kind` + property. + +
Related work items + + - Issues: [#139][#139] + - PRs: [#338][#338] + +
+ +- Added the [capabilities][p7-24] property to the output for the + [dsc resource list][cmd-rlist] command. The `capabilities` property indicates how you can use the + DSC Resource and how DSC and other higher order tools should handle it. + +
Related work items + + - Issues: [#356][#356] + - PRs: [#357][#357] + +
+ +- Added the `metadata` property to the outputs for `dsc config` + and `dsc resource` subcommands. This property in the output defines the context DSC was run under + and information about the operation. See the output reference for each command for more + information: + + - [dsc config get][p7-25] + - [dsc config test][p7-26] + - [dsc config set][p7-27] + - [dsc resource get][p7-28] + - [dsc resource test][p7-29] + - [dsc resource set][p7-30] + +
Related work items + + - Issues: [#401][#401] + - PRs: [#405][#405] + +
+ +- Added parsing for [configuration functions][cfuncs] in the [default values][p7-31] of parameters. + Prior to this release, DSC interpreted configuration functions in parameter default values as + literal strings. + +
Related work items + + - Issues: _None_. + - PRs: [#364][#364] + +
+ +- Added type validation for parameter [default values][p7-31]. Prior to this release, DSC didn't + validate that the default value for a parameter was valid for the parameter's [type][p7-32]. + +
Related work items + + - Issues: _None_. + - PRs: [#364] + +
+ +- Added support for resources to send trace information to DSC during command execution. DSC + Resources can emit JSON objects to stderr. If the object has a property in the following list + with a string value, DSC interprets the emitted object as a message of the matching level: + `Error`, `Warning`, `Info`, `Debug`, `Trace`. + + For example, DSC would interpret a resource emitting the following JSON to stderr as a warning: + + ```json + {"Warning":"Unable to access remote store, using cached local package data only"} + ``` + + DSC emits these messages along with its own messages when the specified trace level for the + command is equal to or lower than the message's level. + + For more information about trace levels, see the [--trace-level][p7-33] option for the + [dsc][cmd] root command. + +
Related work items + + - Issues: [#89][#89] + - PRs: [#287][#287] + +
+ +- Added validation to ensure resources return data for their instances that is valid against their + own instance JSON schema. Prior to this release, the return data wasn't validated. + +
Related work items + + - Issues: [#251][#251] + - PRs: [#362][#362] + +
+ +- Added multi-line progress bars for the `dsc resource list` command to provide feedback to + interactive users about the resource discovery process. Prior to this release, the command + executed silently. + +
Related work items + + - Issues: _None_. + - PRs: [#323][#323] + +
+ +- Added functionality to insert metadata for adapter resources to indicate if the incoming data is + for a configuration instead of direct resource invocation. Prior to this release, adapters had no + way of discerning between a single-instance call for a configuration and a direct resource + invocation. + + With this change, DSC inserts the following into the data object sent to the adapter during a + `dsc config` command: + + ```json + "metadata": { + "Microsoft.DSC": { + "context": "Configuration" + } + } + ``` + + Adapters can then check whether this value is set in the input data and handle it as-needed. + +
Related work items + + - Issues: [#253][#253] + - PRs: [#348][#348] + +
+ +- Added the `Microsoft.Windows/RebootPending` resource, which checks whether a Windows machine has + a pending reboot. It can only be used for assertions, not to enforce state. + +
Related work items + + - Issues: [#333][#333] + - PRs: [#344][#344] + +
+ +- Added the `Microsoft.DSC.Transitional/RunCommandOnSet` resource, which runs a specified + executable or script with given arguments during a `set` operation. This resource is intended as + a temporary transitional resource while migrating to DSCv3 and implementing resources for your + needs. + +
Related work items + + - Issues: [#302][#302] + - PRs: [#321][#321] + +
+ + +[p7-01]: ./docs/reference/schemas/resource/manifest/adapter.md +[p7-02]: ./docs/reference/schemas/outputs/resource/list.md#requireadapter +[p7-03]: ./docs/reference/schemas/definitions/parameters/dataTypes.md +[p7-04]: ./docs/reference/cli/resource/list.md#-a---adapter +[p7-05]: ./docs/reference/schemas/resource/manifest/delete.md +[p7-06]: ./docs/reference/schemas/resource/properties/exist.md +[p7-07]: ./docs/reference/schemas/resource/manifest/set.md#handlesexist +[p7-08]: ./docs/reference/schemas/outputs/resource/list.md#capability-sethandlesexist +[p7-09]: ./docs/reference/schemas/outputs/resource/list.md#capability-delete +[p7-10]: ./docs/reference/schemas/resource/manifest/root.md#schema-1 +[p7-11]: ./docs/reference/schemas/config/metadata.md +[p7-12]: ./docs/reference/schemas/resource/manifest/delete.md#json-input-argument +[p7-13]: ./docs/reference/schemas/resource/manifest/export.md#json-input-argument +[p7-14]: ./docs/reference/schemas/resource/manifest/get.md#json-input-argument +[p7-15]: ./docs/reference/schemas/resource/manifest/set.md#json-input-argument +[p7-16]: ./docs/reference/schemas/resource/manifest/test.md#json-input-argument +[p7-17]: ./docs/reference/schemas/resource/manifest/validate.md#json-input-argument +[p7-18]: ./docs/reference/schemas/config/resource.md#dependsOn +[p7-19]: ./docs/reference/schemas/resource/manifest/root.md#kind +[p7-20]: ./docs/reference/schemas/outputs/resource/list.md +[p7-21]: ./docs/reference/schemas/definitions/resourceKind.md#group-resources +[p7-22]: ./docs/reference/schemas/definitions/resourceKind.md#adapter-resources +[p7-23]: ./docs/reference/schemas/definitions/resourceKind.md +[p7-24]: ./docs/reference/schemas/outputs/resource/list.md#capabilities +[p7-25]: ./docs/reference/schemas/outputs/config/get.md#metadata-1 +[p7-26]: ./docs/reference/schemas/outputs/config/test.md#metadata-1 +[p7-27]: ./docs/reference/schemas/outputs/config/set.md#metadata-1 +[p7-28]: ./docs/reference/schemas/outputs/resource/get.md#metadata-1 +[p7-29]: ./docs/reference/schemas/outputs/resource/test.md#metadata-1 +[p7-30]: ./docs/reference/schemas/outputs/resource/set.md#metadata-1 +[p7-31]: ./docs/reference/schemas/config/parameter.md#defaultvalue +[p7-32]: ./docs/reference/schemas/config/parameter.md#type +[p7-33]: ./docs/reference/cli/dsc.md#-l---trace-level ## [v3.0.0-alpha.5][release-v3.0.0-alpha.5] - 2024-02-27 @@ -192,7 +613,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. - [#284][#284] - PRs: [#318][#318] -
+
+
-- Added support for using the [dsc config export][a5.13] and [dsc resource export][a5.14] 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. +- Added support for using the [dsc config export][cmd-cexport] and + [dsc resource export][cmd-rexport] 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 @@ -272,7 +694,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5].
- Added the `methods` column to the default table view for the console output of the - [dsc resource list][a5.15] command. This new column indicates which methods the resource + [dsc resource list][cmd-rlist] 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][a5.16] parameter, capture the command output, or redirect the output, the @@ -320,9 +742,6 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. [a5.10]: docs/reference/schemas/config/functions/concat.md [a5.11]: docs/reference/cli/config/command.md#environment-variables [a5.12]: docs/reference/schemas/config/functions/envvar.md -[a5.13]: docs/reference/cli/config/export.md -[a5.14]: docs/reference/cli/resource/export.md -[a5.15]: docs/reference/cli/resource/list.md [a5.16]: docs/reference/cli/resource/list.md#-f---format ## [v3.0.0-alpha.4][release-v3.0.0-alpha.4] - 2023-11-14 @@ -533,7 +952,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3]. -- The [dsc resource set][a3.03] command no longer tests the resource instance before invoking the +- The [dsc resource set][cmd-rset] command no longer tests the resource instance before invoking the `set` operation. This simplifies the behavior for the command and adheres more accurately to the implied contract for directly invoking a resource with DSC. @@ -570,7 +989,6 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3]. [a3.01]: docs/reference/schemas/resource/manifest/root.md#schema [a3.02]: docs/reference/schemas/resource/manifest/set.md#implementspretest -[a3.03]: docs/reference/cli/resource/set.md [a3.04]: docs/reference/schemas/resource/manifest/get.md#input [a3.05]: docs/reference/schemas/resource/manifest/set.md#input [a3.06]: docs/reference/schemas/resource/manifest/test.md#input @@ -620,9 +1038,9 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2]. -- Added the [dsc config export][a2.03] command to convert an input configuration document defining a - list of resource types into a usable configuration document that defines the current state for - every instance of those resources. +- Added the [dsc config export][cmd-cexport] command to convert an input configuration document + defining a list of resource types into a usable configuration document that defines the current + state for every instance of those resources.
Related work items @@ -631,8 +1049,8 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-- Added the [dsc resource export][a2.04] command to generate a usable configuration document that - defines the current state for every instance of a specified resource. +- Added the [dsc resource export][cmd-rexport] command to generate a usable configuration document + that defines the current state for every instance of a specified resource.
Related work items @@ -641,8 +1059,8 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-- Added the [--all][a2.05] option for the [dsc resource get][a2.06] command, enabling users to retrieve - the current state for every instance of an exportable resource with a single command. +- Added the [--all][a2.05] option for the [dsc resource get][cmd-rget] command, enabling users to + retrieve the current state for every instance of an exportable resource with a single command.
Related work items @@ -746,10 +1164,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2]. [a2.01]: docs/reference/schemas/config/resource.md#dependson [a2.02]: docs/reference/schemas/resource/manifest/export.md -[a2.03]: docs/reference/cli/config/export.md -[a2.04]: docs/reference/cli/resource/export.md [a2.05]: docs/reference/cli/resource/get.md##a---all -[a2.06]: docs/reference/cli/resource/get.md [a2.07]: docs/reference/cli/dsc.md#exit-codes [a2.08]: docs/reference/cli/dsc.md#environment-variables [a2.09]: docs/reference/schemas/config/parameter.md#defaultvalue @@ -770,6 +1185,41 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [release-v3.0.0-alpha.1]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.1 "Link to the DSC v3.0.0-alpha.1 release on GitHub" [compare-v3.0.0-alpha.1]: https://github.com/PowerShell/DSC/compare/6090b1464bbf81fded5453351708482a4db35258...v3.0.0-alpha.1 + +[cmd]: ./docs/reference/cli/dsc.md +[cmd-completion]: ./docs/reference/cli/completer/command.md +[cmd-schema]: ./docs/reference/cli/schema/command.md +[cmd-c]: ./docs/reference/cli/config/command.md +[cmd-cexport]: ./docs/reference/cli/config/export.md +[cmd-cget]: ./docs/reference/cli/config/get.md +[cmd-cset]: ./docs/reference/cli/config/set.md +[cmd-ctest]: ./docs/reference/cli/config/test.md +[cmd-r]: ./docs/reference/cli/resource/command.md +[cmd-rdelete]: ./docs/reference/cli/resource/delete.md +[cmd-rexport]: ./docs/reference/cli/resource/export.md +[cmd-rget]: ./docs/reference/cli/resource/get.md +[cmd-rlist]: ./docs/reference/cli/resource/list.md +[cmd-rschema]: ./docs/reference/cli/resource/schema.md +[cmd-rset]: ./docs/reference/cli/resource/set.md +[cmd-rtest]: ./docs/reference/cli/resource/test.md + +[cfuncs]: ./docs/reference/schemas/config/functions/overview.md +[add()]: ./docs/reference/schemas/config/functions/add.md +[base64()]: ./docs/reference/schemas/config/functions/base64.md +[concat()]: ./docs/reference/schemas/config/functions/concat.md +[createArray()]: ./docs/reference/schemas/config/functions/createArray.md +[div()]: ./docs/reference/schemas/config/functions/div.md +[envvar()]: ./docs/reference/schemas/config/functions/envvar.md +[int()]: ./docs/reference/schemas/config/functions/int.md +[max()]: ./docs/reference/schemas/config/functions/max.md +[min()]: ./docs/reference/schemas/config/functions/min.md +[mod()]: ./docs/reference/schemas/config/functions/mod.md +[mul()]: ./docs/reference/schemas/config/functions/mul.md +[parameters()]: ./docs/reference/schemas/config/functions/parameters.md +[reference()]: ./docs/reference/schemas/config/functions/reference.md +[resourceId()]: ./docs/reference/schemas/config/functions/resourceId.md +[sub()]: ./docs/reference/schemas/config/functions/sub.md + [#107]: https://github.com/PowerShell/DSC/issues/107 [#121]: https://github.com/PowerShell/DSC/issues/121 @@ -777,6 +1227,7 @@ For the full list of changes in this release, see the [diff on GitHub][compare-v [#129]: https://github.com/PowerShell/DSC/issues/129 [#130]: https://github.com/PowerShell/DSC/issues/130 [#133]: https://github.com/PowerShell/DSC/issues/133 +[#139]: https://github.com/PowerShell/DSC/issues/139 [#150]: https://github.com/PowerShell/DSC/issues/150 [#156]: https://github.com/PowerShell/DSC/issues/156 [#158]: https://github.com/PowerShell/DSC/issues/158 @@ -807,45 +1258,81 @@ 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 +[#218]: https://github.com/PowerShell/DSC/issues/218 [#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 +[#251]: https://github.com/PowerShell/DSC/issues/251 [#252]: https://github.com/PowerShell/DSC/issues/252 +[#253]: https://github.com/PowerShell/DSC/issues/253 +[#258]: https://github.com/PowerShell/DSC/issues/258 [#263]: https://github.com/PowerShell/DSC/issues/263 [#266]: https://github.com/PowerShell/DSC/issues/266 [#271]: https://github.com/PowerShell/DSC/issues/271 +[#274]: https://github.com/PowerShell/DSC/issues/274 [#279]: https://github.com/PowerShell/DSC/issues/279 [#284]: https://github.com/PowerShell/DSC/issues/284 [#286]: https://github.com/PowerShell/DSC/issues/286 +[#287]: https://github.com/PowerShell/DSC/issues/287 +[#290]: https://github.com/PowerShell/DSC/issues/290 [#291]: https://github.com/PowerShell/DSC/issues/291 [#294]: https://github.com/PowerShell/DSC/issues/294 [#299]: https://github.com/PowerShell/DSC/issues/299 +[#302]: https://github.com/PowerShell/DSC/issues/302 [#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 +[#310]: https://github.com/PowerShell/DSC/issues/310 [#311]: https://github.com/PowerShell/DSC/issues/311 [#313]: https://github.com/PowerShell/DSC/issues/313 [#314]: https://github.com/PowerShell/DSC/issues/314 +[#317]: https://github.com/PowerShell/DSC/issues/317 [#318]: https://github.com/PowerShell/DSC/issues/318 +[#321]: https://github.com/PowerShell/DSC/issues/321 [#322]: https://github.com/PowerShell/DSC/issues/322 +[#323]: https://github.com/PowerShell/DSC/issues/323 +[#329]: https://github.com/PowerShell/DSC/issues/329 +[#333]: https://github.com/PowerShell/DSC/issues/333 +[#334]: https://github.com/PowerShell/DSC/issues/334 +[#335]: https://github.com/PowerShell/DSC/issues/335 [#336]: https://github.com/PowerShell/DSC/issues/336 +[#338]: https://github.com/PowerShell/DSC/issues/338 +[#342]: https://github.com/PowerShell/DSC/issues/342 +[#344]: https://github.com/PowerShell/DSC/issues/344 +[#346]: https://github.com/PowerShell/DSC/issues/346 [#347]: https://github.com/PowerShell/DSC/issues/347 +[#348]: https://github.com/PowerShell/DSC/issues/348 [#349]: https://github.com/PowerShell/DSC/issues/349 +[#351]: https://github.com/PowerShell/DSC/issues/351 [#352]: https://github.com/PowerShell/DSC/issues/352 [#353]: https://github.com/PowerShell/DSC/issues/353 [#354]: https://github.com/PowerShell/DSC/issues/354 +[#356]: https://github.com/PowerShell/DSC/issues/356 +[#357]: https://github.com/PowerShell/DSC/issues/357 [#358]: https://github.com/PowerShell/DSC/issues/358 [#360]: https://github.com/PowerShell/DSC/issues/360 [#361]: https://github.com/PowerShell/DSC/issues/361 +[#362]: https://github.com/PowerShell/DSC/issues/362 +[#364]: https://github.com/PowerShell/DSC/issues/364 +[#368]: https://github.com/PowerShell/DSC/issues/368 +[#373]: https://github.com/PowerShell/DSC/issues/373 [#375]: https://github.com/PowerShell/DSC/issues/375 [#376]: https://github.com/PowerShell/DSC/issues/376 +[#377]: https://github.com/PowerShell/DSC/issues/377 +[#379]: https://github.com/PowerShell/DSC/issues/379 +[#382]: https://github.com/PowerShell/DSC/issues/382 +[#385]: https://github.com/PowerShell/DSC/issues/385 [#388]: https://github.com/PowerShell/DSC/issues/388 +[#397]: https://github.com/PowerShell/DSC/issues/397 +[#401]: https://github.com/PowerShell/DSC/issues/401 +[#405]: https://github.com/PowerShell/DSC/issues/405 [#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 +[#89]: https://github.com/PowerShell/DSC/issues/89 [#98]: https://github.com/PowerShell/DSC/issues/98 diff --git a/docs/reference/cli/config/command.md b/docs/reference/cli/config/command.md index 376b6204..3b51dd14 100644 --- a/docs/reference/cli/config/command.md +++ b/docs/reference/cli/config/command.md @@ -110,15 +110,14 @@ Mandatory: false ## Environment variables -The `dsc config *` subcommands create the `DSCConfigRoot` environment variable when you call a +The `dsc config *` subcommands create the `DSC_CONFIG_ROOT` 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. +sets the value of the `DSC_CONFIG_ROOT` environment variable to the full path of 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. +> If you define the `DSC_CONFIG_ROOT` variable outside of DSC, DSC raises a warning when it +> overrides the existing environment variable's value for an operation. You can use the [envvar][08] configuration function to reference that folder path for resource instances in the configuration. diff --git a/docs/reference/cli/config/get.md b/docs/reference/cli/config/get.md index c429d0c6..0b584899 100644 --- a/docs/reference/cli/config/get.md +++ b/docs/reference/cli/config/get.md @@ -49,12 +49,12 @@ document saved as `example.dsc.config.yaml`. ```yaml # example.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Windows only type: DSC/AssertionGroup properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo diff --git a/docs/reference/cli/config/set.md b/docs/reference/cli/config/set.md index 5eefc972..b0e6b7ec 100644 --- a/docs/reference/cli/config/set.md +++ b/docs/reference/cli/config/set.md @@ -50,12 +50,12 @@ The command inspects the resource instances defined in the configuration documen ```yaml # example.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Windows only type: DSC/AssertionGroup properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo diff --git a/docs/reference/cli/config/test.md b/docs/reference/cli/config/test.md index 559d390a..f4cc22f4 100644 --- a/docs/reference/cli/config/test.md +++ b/docs/reference/cli/config/test.md @@ -49,12 +49,12 @@ resource instances defined in the configuration document saved as `example.dsc.c ```yaml # example.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Windows only type: DSC/AssertionGroup properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo diff --git a/docs/reference/cli/resource/delete.md b/docs/reference/cli/resource/delete.md new file mode 100644 index 00000000..7636366a --- /dev/null +++ b/docs/reference/cli/resource/delete.md @@ -0,0 +1,158 @@ +--- +description: Command line reference for the 'dsc resource delete' command +ms.date: 05/08/2024 +ms.topic: reference +title: dsc resource delete +--- + +# dsc resource delete + +## Synopsis + +Invokes the delete operation of a resource. + +## Syntax + +### Without instance properties + +```sh +dsc resource delete [Options] --resource +``` + +### Instance properties from stdin + +```sh + | dsc resource delete [Options] --resource +``` + +### Instance properties from input option + +```sh +dsc resource delete --input '' --resource +``` + +### Instance properties from file + +```sh +dsc resource delete --path --resource +``` + +## Description + +The `delete` subcommand removes a resource instance. + +Any properties the resource requires for discerning which instance to delete must be passed to this +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. + +This command returns no output when successful. If it encounters an error, it surfaces the error to +the caller on stderr and exits with a non-zero exit code. + +## Examples + +### Example 1 - delete resource instance with input option + +If a resource requires one or more property values to return the actual state of the instance, the +instance properties can be passed with the **input** option as either JSON or YAML. + +```sh +dsc resource delete --resource Microsoft.Windows/Registry --input '{ + "keyPath": "HKCU\\DSC\\Example" +}' +``` + +### Example 2 - delete resource instance with input from stdin + +If a resource requires one or more property values to return the actual state of the instance, the +instance properties can be passed over stdin as either JSON or YAML. + +```sh +'{ + "keyPath": "HKCU\\DSC\\Example" +}' | dsc resource delete --resource Microsoft.Windows/Registry +``` + +### Example 3 - delete 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.delete.yaml +``` + +```yaml +keyPath: HKCU\\DSC\\Example +``` + +```sh +dsc resource delete --resource Microsoft.Windows/Registry --path ./example.delete.yaml +``` + +## Options + +### -r, --resource + +Specifies the fully qualified type name of the DSC Resource to use, like +`Microsoft.Windows/Registry`. + +The fully qualified type name syntax is: `[.][.]/`, where: + +- The `owner` is the maintaining author or organization for the resource. +- The `group` and `area` are optional name components that enable namespacing for a resource. +- The `name` identifies the component the resource manages. + +```yaml +Type: String +Mandatory: true +``` + +### -i, --input + +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 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 +``` + +### -h, --help + +Displays the help for the current command or subcommand. When you specify this option, the +application ignores all options and arguments after this one. + +```yaml +Type: Boolean +Mandatory: false +``` + +## Output + +This command returns no output when successful. When the resource errors, DSC surfaces the error on +stderr and exits with a non-zero exit code. diff --git a/docs/reference/cli/resource/list.md b/docs/reference/cli/resource/list.md index 22af6528..655ab137 100644 --- a/docs/reference/cli/resource/list.md +++ b/docs/reference/cli/resource/list.md @@ -24,40 +24,46 @@ discovers resources by first searching the `PATH` or `DSC_RESOURCE_PATH` environ `.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. +If any of the discovered resources are resource adapters, DSC calls the `list` operation for those +adapters if the [--adapter](#-a---adapter) option specifies a matching filter. By default, DSC +doesn't return any adapted resources. DSC returns the list of discovered resources with their implementation information and metadata. If the command includes the `RESOURCE_NAME` argument, DSC filters the list of discovered resources before returning them. The **description** and **tags** options filter the results by the -resource descriptions and tags. +resource descriptions and tags. Filters are always applied after resource discovery. ## Examples -### Example 1 - List all resources +### Example 1 - List all non-adapted resources -Without any filters, the command returns every discovered DSC Resource. +Without any filters, the command returns every discovered DSC Resource, but doesn't call the `list` +operation for adapter resources to enumerate any adapted resources. ```sh dsc resource list ``` ```Output -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. +Type Kind Version Caps RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------------------------------------------ +DSC.PackageManagement/Brew Resource 0.1.0 gs---e DSC resource to manage Homebrew packages +Microsoft.DSC.Transitional/RunCommandOnSet Resource 0.1.0 gs---- Takes a single-command line to execute on DSC set operation +Microsoft.DSC/Assertion Group 0.1.0 gs-t-- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs-t-- All resources in the supplied configuration is treated as a group. +Microsoft.DSC/Parallel Group 0.1.0 gs-t-- All resources in the supplied configuration run concurrently. +Microsoft.DSC/PowerShell Adapter 0.1.0 gs-t-e Resource adapter to classic DSC Powershell resources. +Microsoft.Windows/RebootPending Resource 0.1.0 g----- Returns info about pending reboot. +Microsoft.Windows/Registry Resource 0.1.0 gs--d- Manage Windows Registry keys and values +Microsoft.Windows/WindowsPowerShell Adapter 0.1.0 gs-t-- Resource adapter to classic DSC Powershell resources in Windows PowerShell. +Microsoft.Windows/WMI Adapter 0.1.0 g----- Resource adapter to WMI resources. +Microsoft/OSInfo Resource 0.1.0 g----e Returns information about the operating system. +Microsoft/Process Resource 0.1.0 gs-t-e Returns information about running processes. +Test/Delete Resource 0.1.0 g---d- +Test/Echo Resource 0.1.0 gs-t-- +Test/Exist Resource 0.1.0 gsx--- +Test/Sleep Resource 0.1.0 gs-t-- +Test/TestGroup Adapter 0.1.0 g----- ``` ### Example 2 - List a specific resource @@ -66,13 +72,13 @@ When the `RESOURCE_NAME` argument doesn't include a wildcard, the command return with the specified type name. ```sh -dsc resource list DSC/Group +dsc resource list Microsoft.DSC/Group ``` ```Output -Type Version Methods Requires Description ----------------------------------------------------------------------------------------------------------------- -DSC/Group 0.1.0 get, set, test All resources in the supplied configuration is treated as a group. +Type Kind Version Caps RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------- +Microsoft.DSC/Group Group 0.1.0 gs-t-- All resources in the supplied configuration is treated as a group. ``` ### Example 3 - List resources with a matching type name @@ -81,16 +87,16 @@ When the `RESOURCE_NAME` argument includes a wildcard, the command returns every matching type name. ```sh -dsc resource list DSC/* +dsc resource list Microsoft.DSC/* ``` ```Output -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. +Type Kind Version Caps RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------------------- +Microsoft.DSC/Assertion Group 0.1.0 gs-t-- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs-t-- All resources in the supplied configuration is treated as a group. +Microsoft.DSC/Parallel Group 0.1.0 gs-t-- All resources in the supplied configuration run concurrently. +Microsoft.DSC/PowerShell Adapter 0.1.0 gs-t-e Resource adapter to classic DSC Powershell resources. ``` ### Example 4 - List resources with a matching description @@ -103,11 +109,11 @@ dsc resource list --description 'supplied configuration' ``` ```Output -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. +Type Kind Version Caps RequireAdapter Description +---------------------------------------------------------------------------------------------------------------------------------------- +Microsoft.DSC/Assertion Group 0.1.0 gs-t-- `test` will be invoked for all resources in the supplied configuration. +Microsoft.DSC/Group Group 0.1.0 gs-t-- All resources in the supplied configuration is treated as a group. +Microsoft.DSC/Parallel Group 0.1.0 gs-t-- All resources in the supplied configuration run concurrently. ``` ### Example 5 - List resources with matching tags @@ -120,10 +126,54 @@ dsc resource list --tags Windows --tags Linux ``` ```output -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. +Type Kind Version Caps RequireAdapter Description +---------------------------------------------------------------------------------------------------------------------- +Microsoft.Windows/Registry Resource 0.1.0 gs--d- Manage Windows Registry keys and values +Microsoft/OSInfo Resource 0.1.0 g----e Returns information about the operating system. +``` + +### Example 6 - List resources for a specific adapter + +When the command includes the **adapter** option, DSC checks for any discovered resource adapters +with a matching name. If it discovers any, it then calls the `list` operation for the adapter and +adds the returned list of adapted resources to the discovered resource list. DSC applies any +further filters specified with the command after this enumeration. + +```sh +dsc resource list --adapter Microsoft.DSC/PowerShell +``` + +```Output +Type Kind Version Caps RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +PSDscResources/Archive Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/Environment Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/Group Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/MsiPackage Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/Registry Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/Script Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/Service Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/User Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/WindowsFeature Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/WindowsOptionalFeature Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/WindowsPackageCab Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/WindowsProcess Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +``` + +This next command specifies the resource name filter `*Windows*`, limiting the list of returned +resources: + +```sh +dsc resource list --adapter Microsoft.DSC/PowerShell *Windows* +``` + +```Output +Type Kind Version Caps RequireAdapter Description +------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ +PSDscResources/WindowsFeature Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/WindowsOptionalFeature Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/WindowsPackageCab Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. +PSDscResources/WindowsProcess Resource 2.12.0.0 gs-t-- Microsoft.DSC/PowerShell This module contains the standard DSC resources. ``` ## Arguments @@ -147,6 +197,23 @@ Mandatory: false ## Options +### -a, --adapter + +Specifies a filter to define which adapter resources to enumerate adapted resources for. By +default, the command doesn't call the `list` command for adapter resources. When you specify this +option, DSC looks for adapter resources with type names that match the filter. If it discovers any +adapters matching the filter, it calls the `list` command for those adapters and returns the +adapted resources. DSC retrieves adapted resources before applying any other filters for the +command. + +If you specify this option with the filter `*`, DSC calls `list` for every adapter resource it +finds before applying the other filters. + +```yaml +Type: String +Mandatory: false +``` + ### -d, --description Specifies a string to match in a resource's description. When this option is specified, DSC filters @@ -206,16 +273,36 @@ a summary table for the returned resources. The summary table includes the follo displayed in the listed order: - **Type** - The fully qualified type name of the resource. +- **Kind** - Whether the resource is an `Adapter`, `Group`, or typical `Resource`. For more + information, see [DSC Resource kind schema reference][03]. - **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. +- **Caps** - A display of the resource's [capabilities][04] as flags. The capabilities are + displayed in the following order, using a `-` instead of the appropriate letter if the resource + doesn't have a specific capability: + + - `g` indicates that the resource has the [Get capability][05]. + - `s` indicates that the resource has the [Set capability][06] + - `x` indicates that the resource has the [SetHandlesExist capability][07] + - `t` indicates that the resource has the [Test capability][08] + - `d` indicates that the resource has the [Delete capability][09] + - `e` indicates that the resource has the [Export capability][10] + + For example, the `Microsoft.Windows/Registry` resource has the following capabilities: `gs--d-`, indicating it has the `Get`, `Set`, and `Delete` capabilities. +- **RequireAdapter** - The fully qualified type name of the adapter resource that DSC uses to + invoke the returned resource. - **Description** - The short description of the resource's purpose and usage. 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 +[03]: ../../schemas/definitions/resourceKind.md +[04]: ../../schemas/outputs/resource/list.md#capabilities +[05]: ../../schemas/outputs/resource/list.md#capability-get +[06]: ../../schemas/outputs/resource/list.md#capability-set +[07]: ../../schemas/outputs/resource/list.md#capability-sethandlesexist +[08]: ../../schemas/outputs/resource/list.md#capability-test +[09]: ../../schemas/outputs/resource/list.md#capability-delete +[10]: ../../schemas/outputs/resource/list.md#capability-export diff --git a/docs/reference/schemas/config/document.md b/docs/reference/schemas/config/document.md index f04d1cd3..447e51b0 100644 --- a/docs/reference/schemas/config/document.md +++ b/docs/reference/schemas/config/document.md @@ -15,7 +15,7 @@ The YAML or JSON file that defines a DSC Configuration. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json Type: object ``` @@ -57,6 +57,19 @@ The `$schema` property indicates the canonical URL for the version of this schem adheres to. DSC uses this property when validating the configuration document before any configuration operations. +There are currently 3 published versions of the schema, compatible with different versions of DSC: + +- `2024/04` is the latest version of the schema, compatible with DSC version 3.0.0-preview.7 and + later. +- `2023/10` is the previous version of the schema, compatible with DSC versions `3.0.0-alpha.4` and + `3.0.0-alpha.5`. +- `2023/08` is the first version of the schema, compatible with DSC versions `3.0.0-alpha.1` through + `3.0.0-alpha.3`. + +This documentation is for the latest version of the schema. You should update your configuration +documents and resource manifests to the latest version of the schema. Prior versions don't work +with new releases of DSC. The schemas remain published, but won't get any updates. + For every version of the schema, there are three valid urls: - `.../config/document.json` @@ -87,6 +100,9 @@ Type: string Required: true Format: URI ValidValues: [ + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/config/document.vscode.json @@ -126,7 +142,7 @@ For more information about defining parameters in a configuration, see ```yaml Type: object Required: false -ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.parameter.json +ValidPropertySchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json ``` ### variables @@ -162,7 +178,7 @@ For more information about defining a valid resource instance in a configuration Type: array Required: true MinimumItemCount: 1 -ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.resource.json +ValidItemSchema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json ``` diff --git a/docs/reference/schemas/config/functions/add.md b/docs/reference/schemas/config/functions/add.md index 7803f00d..c624cfec 100644 --- a/docs/reference/schemas/config/functions/add.md +++ b/docs/reference/schemas/config/functions/add.md @@ -30,7 +30,7 @@ This example document shows how you can use the `add()` function to return the s ```yaml # add.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Sum of 3 and 5 type: Test/Echo @@ -60,7 +60,7 @@ configuration functions that return integer values. ```yaml # add.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Add nested function outputs type: Test/Echo diff --git a/docs/reference/schemas/config/functions/base64.md b/docs/reference/schemas/config/functions/base64.md index e242a590..13dde543 100644 --- a/docs/reference/schemas/config/functions/base64.md +++ b/docs/reference/schemas/config/functions/base64.md @@ -31,7 +31,7 @@ The configuration converts a basic string value with the `base64()` function. ```yaml # base64.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo 'abc' in base64 type: Test/Echo @@ -61,7 +61,7 @@ strings `a`, `b`, and `c` into `abc` before returning the base64 representation. ```yaml # base64.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo concatenated 'a', 'b', 'c' in base64 type: Test/Echo diff --git a/docs/reference/schemas/config/functions/concat.md b/docs/reference/schemas/config/functions/concat.md index 35695920..4bec08b7 100644 --- a/docs/reference/schemas/config/functions/concat.md +++ b/docs/reference/schemas/config/functions/concat.md @@ -35,7 +35,7 @@ The configuration uses the `concat()` function to join the strings `abc` and `de ```yaml # concat.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo 'abcdef' type: Test/Echo @@ -64,7 +64,7 @@ The configuration uses the `concat()` function to return a combined array of str ```yaml # concat.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo ['a', 'b', 'c', 'd', 'e', 'f'] type: Test/Echo diff --git a/docs/reference/schemas/config/functions/createArray.md b/docs/reference/schemas/config/functions/createArray.md index 095406c6..384de1f3 100644 --- a/docs/reference/schemas/config/functions/createArray.md +++ b/docs/reference/schemas/config/functions/createArray.md @@ -33,7 +33,7 @@ example synopsis ```yaml # createArray.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo array of integers type: Test/Echo @@ -66,7 +66,7 @@ sub-array contains only integers. The second sub-array contains only strings. ```yaml # createArray.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Create array of arrays type: Test/Echo @@ -102,7 +102,7 @@ strings. It uses YAML's folded multiline string syntax to make the function more ```yaml # createArray.example.3.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo flattened array type: Test/Echo diff --git a/docs/reference/schemas/config/functions/div.md b/docs/reference/schemas/config/functions/div.md index 851aa52b..70683061 100644 --- a/docs/reference/schemas/config/functions/div.md +++ b/docs/reference/schemas/config/functions/div.md @@ -32,7 +32,7 @@ integers. ```yaml # div.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Dividing integers type: Test/Echo @@ -63,7 +63,7 @@ full integer value without the remainder. It doesn't round the result up to 3. ```yaml # div.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Dividing nested functions type: Test/Echo diff --git a/docs/reference/schemas/config/functions/envvar.md b/docs/reference/schemas/config/functions/envvar.md index 640a406d..fbbe7b08 100644 --- a/docs/reference/schemas/config/functions/envvar.md +++ b/docs/reference/schemas/config/functions/envvar.md @@ -24,10 +24,10 @@ environment variable doesn't exist, DSC raises an error. ## Examples -### Example 1 - Reference DSCConfigRoot in a configuration +### Example 1 - Reference DSC_CONFIG_ROOT 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 +commands, DSC automatically creates the `DSC_CONFIG_ROOT` environment variable and sets the value to the parent folder of the specified configuration document. For more information, see [dsc config command reference][01]. @@ -35,12 +35,12 @@ 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 +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - - name: Echo 'DSCConfigRoot' in envvar + - name: Echo 'DSC_CONFIG_ROOT' in envvar type: Test/Echo properties: - output: "[envvar('DSCConfigRoot')]" + output: "[envvar('DSC_CONFIG_ROOT')]" ``` ```bash @@ -49,7 +49,7 @@ dsc config get --path ~/dsc/examples/envvar.example.1.dsc.config.yaml ```yaml results: -- name: Echo DSCConfigRoot +- name: Echo DSC_CONFIG_ROOT type: Test/Echo result: actualState: diff --git a/docs/reference/schemas/config/functions/int.md b/docs/reference/schemas/config/functions/int.md index a4020b3b..24bdb6d5 100644 --- a/docs/reference/schemas/config/functions/int.md +++ b/docs/reference/schemas/config/functions/int.md @@ -30,7 +30,7 @@ This configuration returns an integer, converting the string value `'4.7'` to `4 ```yaml # int.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo integer value type: Test/Echo diff --git a/docs/reference/schemas/config/functions/max.md b/docs/reference/schemas/config/functions/max.md index 7d0ef589..b3fe2ec0 100644 --- a/docs/reference/schemas/config/functions/max.md +++ b/docs/reference/schemas/config/functions/max.md @@ -30,7 +30,7 @@ This configuration returns the largest number from a list of integers. ```yaml # max.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo maximum value type: Test/Echo @@ -61,7 +61,7 @@ function more readable. ```yaml # max.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo integer array type: Test/Echo diff --git a/docs/reference/schemas/config/functions/min.md b/docs/reference/schemas/config/functions/min.md index 26530963..4a80b0e0 100644 --- a/docs/reference/schemas/config/functions/min.md +++ b/docs/reference/schemas/config/functions/min.md @@ -30,7 +30,7 @@ This configuration returns the smallest number from a list of integers. ```yaml # min.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo minimum value type: Test/Echo @@ -61,7 +61,7 @@ function more readable. ```yaml # min.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo integer array type: Test/Echo diff --git a/docs/reference/schemas/config/functions/mod.md b/docs/reference/schemas/config/functions/mod.md index 297acf17..d13c536b 100644 --- a/docs/reference/schemas/config/functions/mod.md +++ b/docs/reference/schemas/config/functions/mod.md @@ -30,7 +30,7 @@ division for two integers. ```yaml # mod.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Remainder for integers type: Test/Echo @@ -60,7 +60,7 @@ two other mathematical operations. ```yaml # mod.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Remainder for nested functions type: Test/Echo diff --git a/docs/reference/schemas/config/functions/mul.md b/docs/reference/schemas/config/functions/mul.md index 76a48a2c..c750848b 100644 --- a/docs/reference/schemas/config/functions/mul.md +++ b/docs/reference/schemas/config/functions/mul.md @@ -30,7 +30,7 @@ This example document multiplies two integers to return a product for the output ```yaml # mul.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Multiplying integers type: Test/Echo @@ -59,7 +59,7 @@ This document shows how you can multiply the output of nested configuration func ```yaml # mul.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Multiplying nested function outputs type: Test/Echo diff --git a/docs/reference/schemas/config/functions/overview.md b/docs/reference/schemas/config/functions/overview.md index e6673b9e..4b9e6cc5 100644 --- a/docs/reference/schemas/config/functions/overview.md +++ b/docs/reference/schemas/config/functions/overview.md @@ -78,7 +78,7 @@ the [base64()][base64] function. ```yaml # overview.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Double quoted syntax type: Test/Echo @@ -128,7 +128,7 @@ output of the [concat()][concat] function, combining the strings `a` and `b` int ```yaml # overview.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo the concatenated strings 'a' and 'b' type: Test/Echo @@ -161,7 +161,7 @@ nested functions shown in the third instance to base64. ```yaml # overview.example.3.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Echo the concatenated strings 'a' and 'b' as base64 type: Test/Echo diff --git a/docs/reference/schemas/config/functions/parameters.md b/docs/reference/schemas/config/functions/parameters.md index 0cff8981..7205fa77 100644 --- a/docs/reference/schemas/config/functions/parameters.md +++ b/docs/reference/schemas/config/functions/parameters.md @@ -35,7 +35,7 @@ The configuration uses the `parameters()` function to echo the value of the `mes ```yaml # parameters.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json parameters: message: type: string diff --git a/docs/reference/schemas/config/functions/reference.md b/docs/reference/schemas/config/functions/reference.md index 92259ef3..9d007145 100644 --- a/docs/reference/schemas/config/functions/reference.md +++ b/docs/reference/schemas/config/functions/reference.md @@ -43,7 +43,7 @@ the resource and uses the dot-path notation to access the **bitness** property o ```yaml # reference.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: System type: Microsoft/OSInfo diff --git a/docs/reference/schemas/config/functions/resourceId.md b/docs/reference/schemas/config/functions/resourceId.md index 3e16fa76..7c42a9d1 100644 --- a/docs/reference/schemas/config/functions/resourceId.md +++ b/docs/reference/schemas/config/functions/resourceId.md @@ -37,7 +37,7 @@ The following configuration uses the `resourceId()` function to reference the in ```yaml # resourceId.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Tailspin Key type: Microsoft.Windows/Registry @@ -62,12 +62,12 @@ resource instance named 'IsWindows' as a dependency of the `Example Key` resourc ```yaml # resourceId.example.2.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: IsWindows type: DSC/AssertionGroup properties: - $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: os type: Microsoft/OSInfo diff --git a/docs/reference/schemas/config/functions/sub.md b/docs/reference/schemas/config/functions/sub.md index c408153f..e9cc4f2c 100644 --- a/docs/reference/schemas/config/functions/sub.md +++ b/docs/reference/schemas/config/functions/sub.md @@ -31,7 +31,7 @@ integers. ```yaml # sub.example.1.dsc.config.yaml -$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json resources: - name: Subtract integers type: Test/Echo diff --git a/docs/reference/schemas/config/metadata.md b/docs/reference/schemas/config/metadata.md new file mode 100644 index 00000000..115ea672 --- /dev/null +++ b/docs/reference/schemas/config/metadata.md @@ -0,0 +1,82 @@ +--- +description: JSON schema reference for metadata in a Desired State Configuration document. +ms.date: 01/17/2024 +ms.topic: reference +title: DSC Configuration document metadata schema +--- + +# DSC Configuration document metadata schema + +## Synopsis + +Defines a set of informational key-value pairs for the configuration. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.metadata.json +Type: object +``` + +## Description + +Defines a set of informational key-value pairs for the configuration. Except for the +`Microsoft.DSC` property, this metadata isn't validated. You can pass any data into your +configuration as a property of `metadata`. + +For example, you could define information about the configuration used by your teams or internal +tools: + +```yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/config/document.vscode.json + +metadata: + owner: security.ops@contoso.com + name: WebAppBaseline + purpose: |- + Define a baseline for securing web application servers. +``` + +## Microsoft.DSC + +The `Microsoft.DSC` metadata property contains directives and information that DSC itself uses when +processing a configuration document. Unlike other metadata key-value pairs, DSC validates these +properties. This property is reserved and shouldn't contain any custom user-defined metadata. + +### Properties + +#### securityContext + +This property defines the security context a configuration requires. If you invoke a DSC operation +against the configuration document in a security context that conflicts with this metadata, DSC +raises an error when it validates the configuration document. + +The valid security contexts are: + +- `Current` + + Indicates that the configuration document is usable under any security context. You can invoke + DSC operations against the document when elevated as root or an administrator and as a normal + user or account. +- `Elevated` + + Indicates that the configuration document is usable only in an elevated security context. You can + invoke DSC operations against the document when elevated as root or an administrator. When you + invoke DSC operations against the document as a non-elevated user or account, DSC raises an error + when it validates the configuration document. +- `Restricted` + + Indicates that the configuration document is usable only in a non-elevated security context. You + can invoke DSC operations against the document as a non-elevated user or account. When you invoke + DSC operations against the document as root or an administrator, DSC raises an error when it + validates the configuration document. + +The default security context is `Current`. + +```yaml +Type: object +Required: false +Default: Current +ValidValues: [Current, Elevated, Restricted] +``` diff --git a/docs/reference/schemas/config/parameter.md b/docs/reference/schemas/config/parameter.md index 68848545..b1cee316 100644 --- a/docs/reference/schemas/config/parameter.md +++ b/docs/reference/schemas/config/parameter.md @@ -15,7 +15,7 @@ Defines runtime options for a configuration. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.parameter.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.parameter.json Type: object ``` diff --git a/docs/reference/schemas/config/resource.md b/docs/reference/schemas/config/resource.md index cf010204..a7ef10aa 100644 --- a/docs/reference/schemas/config/resource.md +++ b/docs/reference/schemas/config/resource.md @@ -15,7 +15,7 @@ Defines a DSC Resource instance in a configuration document. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/config/document.resource.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.resource.json Type: object ``` diff --git a/docs/reference/schemas/definitions/message.md b/docs/reference/schemas/definitions/message.md index 77c38470..15c7f334 100644 --- a/docs/reference/schemas/definitions/message.md +++ b/docs/reference/schemas/definitions/message.md @@ -15,7 +15,7 @@ A message emitted by a DSC Resource with associated metadata. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/message.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/message.json Type: object ``` diff --git a/docs/reference/schemas/definitions/parameters/dataTypes.md b/docs/reference/schemas/definitions/parameters/dataTypes.md index 6654bd89..83f88fbb 100644 --- a/docs/reference/schemas/definitions/parameters/dataTypes.md +++ b/docs/reference/schemas/definitions/parameters/dataTypes.md @@ -15,7 +15,7 @@ Defines valid data types for a DSC configuration parameter ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/parameters/dataTypes.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/parameters/dataTypes.json Type: string ValidValues: [array, bool, int, object, string, secureobject, securestring] ``` diff --git a/docs/reference/schemas/definitions/resourceKind.md b/docs/reference/schemas/definitions/resourceKind.md new file mode 100644 index 00000000..6c12fa58 --- /dev/null +++ b/docs/reference/schemas/definitions/resourceKind.md @@ -0,0 +1,361 @@ +--- +description: JSON schema reference for a resource instance type name +ms.date: 04/22/2024 +ms.topic: reference +title: DSC Resource kind schema reference +--- + +# DSC Resource kind schema reference + +## Synopsis + +Identifies whether a resource is an adapter resource, a group resource, or a normal resource. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceKind.json +Type: string +ValidValues: [Resource, Adapter, Group] +``` + +## Description + +DSC supports three kinds of command-based DSC Resources: + +- `Resource` - Indicates that the manifest isn't for a group or adapter resource. +- `Group` - Indicates that the manifest is for a [group resource](#group-resources). +- `Adapter` - Indicates that the manifest is for an [adapter resource](#adapter-resources). + +When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the +`adapter` property is defined in the resource manifest, DSC infers the value of `kind` as +`Adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `Resource`. +DSC can't infer whether a manifest is for a group resource. + +When defining a group resource, always explicitly define the `kind` property in the manifest as +`Group`. + +### Adapter resources + +An adapter resource makes non-command-based resources available to DSC. They always have a +`resources` property that takes an array of nested resource instances. Adapters may provide +additional control over how the adapted resources are processed. + +An adapter resource must always define the [adapter][01] and [validate][02] properties in the +resource manifest. + +For example, the `Microsoft.DSC/PowerShell` adapter enables you to use PowerShell Desired State +Configuration (PSDSC) resources in DSC. PSDSC resources are published as components of PowerShell +modules. They don't define resource manifests. + +### Group resources + +Group resources always operate on nested DSC Resource instances. Group resources can change how the +nested instances are processed, like the `Microsoft.DSC/Assertion` group resource. + +Group resources can also be used to bundle sets of resources together for processing, like the +`Microsoft.DSC/Group` resource. You can use the [dependsOn][03] property for a resource instance in +a configuration to point to a group resource instead of enumerating each resource in the list. + +### Nested resource instances + +The resource instances declared in both adapter and group resources are called _nested resource +instances_. For nested instances, a resource instance is _adjacent_ if it's declared in the same +group or adapter instance. A resource instance is _external_ to a nested instance if it's declared +outside of the group or adapter instance, or nested inside an adjacent group or adapter instance. +For top-level instances, other instances at the top-level are adjacent. All other instances are +external. + +Consider the following configuration snippet. It defines seven resource instances: + +- At the top-level, the configuration defines the `TopLevelEcho`, `TopLevelOSInfo`, and + `TopLevelGroup` instances. +- The `TopLevelGroup` instance defines the nested instances `NestedEcho` and `NestedGroup`. +- The `NestedGroup` instance defines the nested instances `DeeplyNestedEcho` and + `DeeplyNestedOSInfo`. + +```yaml +resources: +- name: TopLevelEcho + type: Test/Echo + properties: { output: 'top level instance' } +- name: TopLevelOSInfo + type: Microsoft/OSInfo + properties: { } +- name: TopLevelGroup + type: Microsoft.DSC/Group + properties: + $schema: + resources: + - name: NestedEcho + type: Test/Echo + properties: { output: 'nested instance' } + - name: NestedGroup + type: Microsoft.DSC/Group + properties: + $schema: + resources: + - name: DeeplyNestedEcho + type: Test/Echo + properties: { output: 'deeply nested instance' } + - name: DeeplyNestedOSInfo + type: Microsoft/OSInfo + properties: { } +``` + +The following matrix defines the relations of each instance in the configuration: + +| | TopLevelEcho | TopLevelOSInfo | TopLevelGroup | NestedEcho | NestedGroup | DeeplyNestedEcho | DeeplyNestedOSInfo | +|------------------------|----------------|----------------|---------------|------------|-------------|------------------|--------------------| +| **TopLevelEcho** | Self | Adjacent | Adjacent | External | External | External | External | +| **TopLevelOSInfo** | Adjacent | Self | Adjacent | External | External | External | External | +| **TopLevelGroup** | Adjacent | Adjacent | Self | External | External | External | External | +| **NestedEcho** | External | External | External | Self | Adjacent | External | External | +| **NestedGroup** | External | External | External | Adjacent | Self | External | External | +| **DeeplyNestedEcho** | External | External | External | External | External | Self | Adjacent | +| **DeeplyNestedOSInfo** | External | External | External | External | External | Adjacent | Self | + +### Referencing nested instances + +Nested resource instances have limitations for the [dependsOn][03] property and the +[reference()][04] configuration function. + +1. You can only reference adjacent instances. You can't reference a nested instance from outside of + the group or adapter that declares it. You can't use a reference to a resource outside of the + group or adapter resource for a nested instance. +1. You can only use the `dependsOn` property for adjacent instances. You must add a dependency on + the group or adapter instance, not a nested instance of the group or adapter. Nested instances + can't depend on external instances. + +The following examples show valid and invalid references and dependencies. The examples use the +`Microsoft.DSC/Group` resource, but the functionality is the same for adapter resources. + +#### Example 1 - Valid references and dependencies + +This example configuration defines several valid references and dependencies. It also defines two +instances of the `Microsoft.DSC/Group` resource, one nested inside the other. + +The top level instance of the `Test/Echo` resource references and depends on the top-level instance +of the `Microsoft/OSInfo` resource. The top-level instances of the `Test/Echo` and +`Microsoft/OSInfo` resources both depend on the top-level instance of the `Microsoft.DSC/Group` +resource. + +```yaml +resources: +# The top level echo references and depends on the top-level OSInfo. +# It also depends on the top-level Group. +- name: Top level echo + type: Test/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Top level OSInfo') + ).actualState] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]" + - "[resourceId('Microsoft.DSC/Group', 'Top level group')]" +# The top level OSInfo depends on the top-level Group. +- name: Top level OSInfo + type: Microsoft/OSInfo + properties: {} + dependsOn: + - "[resourceId('Microsoft.DSC/Group', 'Top level group')]" +- name: Top level group + type: Microsoft.DSC/Group + properties: # snipped for brevity +``` + +The top-level instance of `Microsoft.DSC/Group` defines three nested resource instances: +`Test/Echo`, `Microsoft/OSInfo`, and `Microsoft.DSC/Group`. As at the top-level, the `Test/Echo` +instance references and depends on the adjacent nested`Microsoft/OSInfo` instance and that instance +depends on the adjacent nested `Microsoft.DSC/Group` instance. + +```yaml +# Other top-level instances snipped for brevity +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + resources: + # The nested echo references and depends on the adjacent nested OSInfo. + - name: Nested echo + type: Test/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Nested OSInfo') + ).actualState] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]" + # The nested OSInfo depends on the adjacent nested Group. + - name: Nested OSInfo + type: Microsoft/OSInfo + properties: {} + - name: Nested Group + type: Microsoft.DSC/Group + properties: # snipped for brevity +``` + +Finally, the nested instance of `Microsoft.DSC/Group` defines two nested instances. The deeply +nested instance of `Test/Echo` references and depends on the deeply nested instance of +`Microsoft/OSInfo`. + +```yaml +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + resources: + # Snipped the Test/Echo and Microsoft/OSInfo instances for brevity + - name: Nested Group + type: Microsoft.DSC/Group + properties: + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + resources: + # The deeply nested echo references and depends on the adjacent + # deeply nested OSInfo. + - name: Deeply nested echo + type: Test/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo') + ).actualState] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]" + - name: Deeply nested OSInfo + type: Microsoft.OSInfo + properties: {} +``` + +In every case, the references and dependencies are to adjacent instances in the configuration. +Instances at the top level only depend on or reference other instances at the top level. Instances +nested in the top-level group only depend on or reference other nested instances in the same group. +The deeply nested instances defined in the nested group only depend on or reference other deeply +nested instances in the same group. + +Putting the configuration together, you get this full document: + +```yaml +# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +# The top level echo references and depends on the top-level OSInfo. +- name: Top level echo + type: Test/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Top level OSInfo') + ).actualState] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]" +# The top level OSInfo depends on the top-level Group. +- name: Top level OSInfo + type: Microsoft/OSInfo + properties: {} + dependsOn: + - "[resourceId('Microsoft.DSC/Group', 'Top level group')]" +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + resources: + # The nested echo references and depends on the adjacent nested OSInfo. + - name: Nested echo + type: Test/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Nested OSInfo') + ).actualState] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]" + # The nested OSInfo depends on the adjacent nested Group. + - name: Nested OSInfo + type: Microsoft/OSInfo + properties: {} + - name: Nested Group + type: Microsoft.DSC/Group + properties: + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + resources: + # The deeply nested echo references and depends on the adjacent + # deeply nested OSInfo. + - name: Deeply nested echo + type: Test/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo') + ).actualState] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Deeply nested OSInfo')]" + - name: Deeply nested OSInfo + type: Microsoft.OSInfo + properties: {} +``` + +#### Example 2 - Invalid reference and dependency on a nested instance + +This example configuration is invalid, because the top-level instance of the `Test/Echo` resource +references and depends on the nested `Microsoft/OSInfo` instance. The nested instance is external +to the top-level instance, not adjacent. + +```yaml +# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Top level echo + type: Test/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Nested OSInfo') + ).actualState] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Nested OSInfo')]" +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + resources: + - name: Nested OSInfo + type: Microsoft/OSInfo + properties: {} +``` + +#### Example 3 - Invalid reference and dependency on an external instance + +This example configuration is invalid, because the nested instance of the `Test/Echo` resource +references and depends on the top-level `Microsoft/OSInfo` instance. The top-level instance is +external to the nested instance, not adjacent. + +```yaml +# yaml-language-server: $schema=https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Top level OSInfo + type: Microsoft/OSInfo + properties: {} +- name: Top level group + type: Microsoft.DSC/Group + properties: + $schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json + resources: + - name: Nested echo + type: Test/Echo + properties: + output: >- + [reference( + resourceId('Microsoft/OSInfo', 'Top level OSInfo') + ).actualState] + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'Top level OSInfo')]" +``` + +[01]: ../resource/manifest/adapter.md +[02]: ../resource/manifest/validate.md +[03]: ../config/resource.md#dependson +[04]: ../config/functions/reference.md diff --git a/docs/reference/schemas/definitions/resourceType.md b/docs/reference/schemas/definitions/resourceType.md index bb285bd6..4c45d941 100644 --- a/docs/reference/schemas/definitions/resourceType.md +++ b/docs/reference/schemas/definitions/resourceType.md @@ -15,7 +15,7 @@ Identifies a DSC Resource. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/definitions/resourceType.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/definitions/resourceType.json Type: string Pattern: ^\w+(\.\w+){0,2}\/\w+$ ``` diff --git a/docs/reference/schemas/metadata/Microsoft.DSC/properties.md b/docs/reference/schemas/metadata/Microsoft.DSC/properties.md new file mode 100644 index 00000000..30e12b46 --- /dev/null +++ b/docs/reference/schemas/metadata/Microsoft.DSC/properties.md @@ -0,0 +1,114 @@ +--- +description: JSON schema reference for the metadata field Microsoft.DSC +ms.date: 05/07/2024 +ms.topic: reference +title: Microsoft.DSC metadata property schema reference +--- + +# Microsoft.DSC metadata property schema reference + +## Synopsis + +Metadata properties used and returned by DSC for configuration and resource operations. + +## Description + +Blah + +## Properties + +### duration + +Defines the duration of a DSC operation against a configuration document or resource instance as a +string following the format defined in [ISO8601 ABNF for `duration`][01]. + +For example, `PT0.611216S` represents a duration of about `0.61` seconds. + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/duration.json +Type: string +Format: duration +``` + +### endDateTime + +Defines the end date and time for the DSC operation as a timestamp following the format defined in +[RFC3339, section 5.6 (see `date-time`)][02]. + +For example: `2024-04-14T08:49:51.395686600-07:00` + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/endDateTime.json +Type: string +Format: date-time +``` + +### executionType + +Defines whether DSC actually applied an operation to the configuration or was run in `WhatIf` mode. +This property is always `Actual` for `Get`, `Test`, and `Export` operations. For `Set` operations, +this value is `WhatIf` when DSC is invoked with the `--whatIf` argument. + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/executionType.json +Type: string +ValidValues: [Actual, WhatIf] +``` + +### operation + +Defines the operation that DSC applied to the configuration document: `Get`, `Set`, `Test`, or +`Export`. + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/operation.json +Type: string +ValidValues: [Get, Set, Test, Export] +``` + +### securityContext + +Defines the security context that DSC was run under. If the value for this metadata property is +`Elevated`, DSC was run as `root` (non-Windows) or an elevated session with Administrator +privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user or account in a +non-elevated session. + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/securityContext.json +Type: string +ValidValues: [Current, Elevated, Restricted] +``` + +### startDatetime + +Defines the start date and time for the DSC operation as a timestamp following the format defined +in [RFC3339, section 5.6 (see `date-time`)][02]. + +For example: `2024-04-14T08:49:51.395686600-07:00` + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/startDatetime.json +Type: string +Format: date-time +``` + +### version + +Defines the version of DSC that ran the command. This value is always the semantic version of the +DSC command, like `3.0.0-preview.7`. + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/metadata/Microsoft.DSC/version.json +Type: object +``` + + +[01]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A +[02]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 diff --git a/docs/reference/schemas/outputs/config/get.md b/docs/reference/schemas/outputs/config/get.md index f605cb0e..2fe5859e 100644 --- a/docs/reference/schemas/outputs/config/get.md +++ b/docs/reference/schemas/outputs/config/get.md @@ -15,7 +15,7 @@ The result output from the `dsc config get` command. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/config/get.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/get.json Type: object ``` @@ -28,12 +28,49 @@ in the configuration document. The output always includes these properties: +- [metadata](#metadata-1) - [results](#results) - [messages](#messages) - [hadErrors](#haderrors) ## Properties +### metadata + +Defines metadata DSC returns for a configuration operation. The properties under the +`Microsoft.DSC` property describe the context of the operation. + +```yaml +Type: object +Required: true +``` + +#### Microsoft.DSC + +The metadata under this property describes the context of the overall operation: + +- [version][01] defines the version of DSC that ran the command. This value is always the semantic + version of the DSC command, like `3.0.0-preview.7`. +- [operation][02] defines the operation that DSC applied to the configuration document: `Get`, + `Set`, `Test`, or `Export`. +- [executionType][03] defines whether DSC actually applied an operation to the configuration or was + run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` + operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` + argument. +- [startDatetime][04] defines the start date and time for the DSC operation as a timestamp + following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like + `2024-04-14T08:49:51.395686600-07:00`. +- [endDatetime][06] defines the end date and time for the DSC operation as a timestamp + following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like + `2024-04-14T08:49:51.395686600-07:00`. +- [duration][07] defines the duration of a DSC operation against a configuration document or + resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][08]. + For example, `PT0.611216S` represents a duration of about `0.61` seconds. +- [securityContext][09] defines the security context that DSC was run under. If the value for this + metadata property is `Elevated`, DSC was run as `root` (non-Windows) or an elevated session with + Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user + or account in a non-elevated session. + ### results Defines the list of results for the `get` operation invoked against every instance in the @@ -50,7 +87,7 @@ ItemsType: object An item's `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]. +[DSC Resource fully qualified type name schema reference][10]. ```yaml Type: string @@ -71,12 +108,12 @@ Required: true 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 get` command. For more -information, see [dsc resource get result schema reference][02]. +information, see [dsc resource get result schema reference][11]. ### messages Defines the list of structured messages emitted by resources during the get operation. For more -information, see [Structured message schema reference][03]. +information, see [Structured message schema reference][12]. ```yaml Type: array @@ -93,6 +130,16 @@ Type: boolean Required: true ``` -[01]: ../../definitions/resourceType.md -[02]: ../resource/get.md -[03]: ../../definitions/message.md + +[01]: ../../metadata/Microsoft.DSC/properties.md#version +[02]: ../../metadata/Microsoft.DSC/properties.md#operation +[03]: ../../metadata/Microsoft.DSC/properties.md#executiontype +[04]: ../../metadata/Microsoft.DSC/properties.md#startdatetime +[05]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 +[06]: ../../metadata/Microsoft.DSC/properties.md#enddatetime +[07]: ../../metadata/Microsoft.DSC/properties.md#duration +[08]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A +[09]: ../../metadata/Microsoft.DSC/properties.md#securitycontext +[10]: ../../definitions/resourceType.md +[11]: ../resource/get.md +[12]: ../../definitions/message.md diff --git a/docs/reference/schemas/outputs/config/set.md b/docs/reference/schemas/outputs/config/set.md index d902f4e0..87d98e83 100644 --- a/docs/reference/schemas/outputs/config/set.md +++ b/docs/reference/schemas/outputs/config/set.md @@ -15,7 +15,7 @@ The result output from the `dsc config set` command. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/config/set.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/set.json Type: object ``` @@ -29,12 +29,49 @@ for each instance. The output always includes these properties: +- [metadata](#metadata-1) - [results](#results) - [messages](#messages) - [hadErrors](#haderrors) ## Properties +### metadata + +Defines metadata DSC returns for a configuration operation. The properties under the +`Microsoft.DSC` property describe the context of the operation. + +```yaml +Type: object +Required: true +``` + +#### Microsoft.DSC + +The metadata under this property describes the context of the overall operation: + +- [version][01] defines the version of DSC that ran the command. This value is always the semantic + version of the DSC command, like `3.0.0-preview.7`. +- [operation][02] defines the operation that DSC applied to the configuration document: `Get`, + `Set`, `Test`, or `Export`. +- [executionType][03] defines whether DSC actually applied an operation to the configuration or was + run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` + operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` + argument. +- [startDatetime][04] defines the start date and time for the DSC operation as a timestamp + following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like + `2024-04-14T08:49:51.395686600-07:00`. +- [endDatetime][06] defines the end date and time for the DSC operation as a timestamp + following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like + `2024-04-14T08:49:51.395686600-07:00`. +- [duration][07] defines the duration of a DSC operation against a configuration document or + resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][08]. + For example, `PT0.611216S` represents a duration of about `0.61` seconds. +- [securityContext][09] defines the security context that DSC was run under. If the value for this + metadata property is `Elevated`, DSC was run as `root` (non-Windows) or an elevated session with + Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user + or account in a non-elevated session. + ### results Defines the list of results for the `set` operation invoked against every instance in the @@ -51,7 +88,7 @@ ItemsType: object An item's `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]. +[DSC Resource fully qualified type name schema reference][10]. ```yaml Type: string @@ -72,12 +109,12 @@ Required: true 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]. +information, see [dsc resource set result schema reference][11]. ### messages Defines the list of structured messages emitted by resources during the set operation. For more -information, see [Structured message schema reference][03]. +information, see [Structured message schema reference][12]. ```yaml Type: array @@ -94,6 +131,16 @@ Type: boolean Required: true ``` -[01]: ../../definitions/resourceType.md -[02]: ../resource/set.md -[03]: ../../definitions/message.md + +[01]: ../../metadata/Microsoft.DSC/properties.md#version +[02]: ../../metadata/Microsoft.DSC/properties.md#operation +[03]: ../../metadata/Microsoft.DSC/properties.md#executiontype +[04]: ../../metadata/Microsoft.DSC/properties.md#startdatetime +[05]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 +[06]: ../../metadata/Microsoft.DSC/properties.md#enddatetime +[07]: ../../metadata/Microsoft.DSC/properties.md#duration +[08]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A +[09]: ../../metadata/Microsoft.DSC/properties.md#securitycontext +[10]: ../../definitions/resourceType.md +[11]: ../resource/set.md +[12]: ../../definitions/message.md diff --git a/docs/reference/schemas/outputs/config/test.md b/docs/reference/schemas/outputs/config/test.md index 2a81a1bd..deb411f5 100644 --- a/docs/reference/schemas/outputs/config/test.md +++ b/docs/reference/schemas/outputs/config/test.md @@ -15,7 +15,7 @@ The result output from the `dsc config test` command. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/config/test.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/config/test.json Type: object ``` @@ -29,12 +29,49 @@ for each instance. The output always includes these properties: +- [metadata](#metadata-1) - [results](#results) - [messages](#messages) - [hadErrors](#haderrors) ## Properties +### metadata + +Defines metadata DSC returns for a configuration operation. The properties under the +`Microsoft.DSC` property describe the context of the operation. + +```yaml +Type: object +Required: true +``` + +#### Microsoft.DSC + +The metadata under this property describes the context of the overall operation: + +- [version][01] defines the version of DSC that ran the command. This value is always the semantic + version of the DSC command, like `3.0.0-preview.7`. +- [operation][02] defines the operation that DSC applied to the configuration document: `Get`, + `Set`, `Test`, or `Export`. +- [executionType][03] defines whether DSC actually applied an operation to the configuration or was + run in `WhatIf` mode. This property is always `Actual` for `Get`, `Test`, and `Export` + operations. For `Set` operations, this value is `WhatIf` when DSC is invoked with the `--whatIf` + argument. +- [startDatetime][04] defines the start date and time for the DSC operation as a timestamp + following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like + `2024-04-14T08:49:51.395686600-07:00`. +- [endDatetime][06] defines the end date and time for the DSC operation as a timestamp + following the format defined in [RFC3339, section 5.6 (see `date-time`)][05], like + `2024-04-14T08:49:51.395686600-07:00`. +- [duration][07] defines the duration of a DSC operation against a configuration document or + resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][08]. + For example, `PT0.611216S` represents a duration of about `0.61` seconds. +- [securityContext][09] defines the security context that DSC was run under. If the value for this + metadata property is `Elevated`, DSC was run as `root` (non-Windows) or an elevated session with + Administrator privileges (on Windows). If the value is `Restricted`, DSC was run as a normal user + or account in a non-elevated session. + ### results Defines the list of results for the `test` operation invoked against every instance in the @@ -51,7 +88,7 @@ ItemsType: object An item's `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]. +[DSC Resource fully qualified type name schema reference][10]. ```yaml Type: string @@ -72,12 +109,12 @@ Required: true 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]. +more information, see [dsc resource test result schema reference][11]. ### messages Defines the list of structured messages emitted by resources during the test operation. For more -information, see [Structured message schema reference][03]. +information, see [Structured message schema reference][12]. ```yaml Type: array @@ -94,6 +131,16 @@ Type: boolean Required: true ``` -[01]: ../../definitions/resourceType.md -[02]: ../resource/test.md -[03]: ../../definitions/message.md + +[01]: ../../metadata/Microsoft.DSC/properties.md#version +[02]: ../../metadata/Microsoft.DSC/properties.md#operation +[03]: ../../metadata/Microsoft.DSC/properties.md#executiontype +[04]: ../../metadata/Microsoft.DSC/properties.md#startdatetime +[05]: https://datatracker.ietf.org/doc/html/rfc3339#section-5.6 +[06]: ../../metadata/Microsoft.DSC/properties.md#enddatetime +[07]: ../../metadata/Microsoft.DSC/properties.md#duration +[08]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A +[09]: ../../metadata/Microsoft.DSC/properties.md#securitycontext +[10]: ../../definitions/resourceType.md +[11]: ../resource/test.md +[12]: ../../definitions/message.md diff --git a/docs/reference/schemas/outputs/resource/get.md b/docs/reference/schemas/outputs/resource/get.md index 34624493..42fb08e6 100644 --- a/docs/reference/schemas/outputs/resource/get.md +++ b/docs/reference/schemas/outputs/resource/get.md @@ -15,7 +15,7 @@ The result output from the `dsc resource get` command. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/get.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/get.json Type: object ``` @@ -68,17 +68,32 @@ data is returned: ### Required properties +- [metadata](#metadata-1) - [name](#name) - [type](#type) - [result](#result) ### Properties +#### metadata + +Defines metadata DSC returns for a configuration operation. The properties under the +`Microsoft.DSC` property describe the context of the operation. + +- [duration][01] defines the duration of a DSC operation against a configuration document or + resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][02]. + For example, `PT0.611216S` represents a duration of about `0.61` seconds. + +```yaml +Type: object +Required: true +``` + #### 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]. +[DSC Resource fully qualified type name schema reference][03]. ```yaml Type: string @@ -108,4 +123,7 @@ Type: [object, array] Required: true ``` -[01]: ../../definitions/resourceType.md + +[01]: ../../metadata/Microsoft.DSC/properties.md#duration +[02]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A +[03]: ../../definitions/resourceType.md diff --git a/docs/reference/schemas/outputs/resource/list.md b/docs/reference/schemas/outputs/resource/list.md index 984b9935..42069bfa 100644 --- a/docs/reference/schemas/outputs/resource/list.md +++ b/docs/reference/schemas/outputs/resource/list.md @@ -15,7 +15,7 @@ The result output from the `dsc resource list` command. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/list.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/list.json Type: object ``` @@ -36,7 +36,7 @@ Each resource in the output always includes these properties: - [implementedAs](#implementedas) - [author](#author) - [properties](#properties) -- [requires](#requires) +- [requireAdapter](#requireadapter) - [manifest](#manifest) ## Properties @@ -54,6 +54,18 @@ Required: true Pattern: ^\w+(\.\w+){0,2}\/\w+$ ``` +### kind + +Identifies whether a resource is an [adapter resource][03], a [group resource][04], or neither. +This value is either defined in the [resource manifest][05] or inferred by DSC. For more +information about resource kinds, see [DSC Resource kind schema reference][06]. + +```yaml +Type: string +Required: true +ValidValues: [Resource, Adapter, Group] +``` + ### version Represents the current version of the resource as a valid semantic version (semver) string. The @@ -65,6 +77,62 @@ Required: true Pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$ ``` +### capabilities + +Defines the operations and behaviors the resource is implemented to support. This property is an +array of capabilities. Resources always have the `Get` capability, but the other capabilities are +optional and depend on the resource. + +The following list describes the available capabilities for a resource: + +- `Get` - The resource supports retrieving the current state of an + instance. All DSC Resources must have this capability. A resource has this capability when it + defines the mandatory [get][07] property in its resource manifest. +- `Set` - The resource supports enforcing the desired state of an + instance. A resource has this capability when it defines the [set][08] property in its resource + manifest. Resources without this capability can't be used with the [dsc resource set][09] or + [dsc config set][10] commands unless they're in a [Microsoft.DSC/Assertion][11] group as a nested + instance. +- `SetHandlesExist` - The resource supports the + [_exist property][12] directly. A resource has this capability when it defines the + [handlesExist][13] property as `true` in the definition of the [set][08] command property in its + resource manifest. + + When a resource has this capability, the `_exist` property is part of the resource's instance + schema and the resource handles deleting instances of the resource in its `set` command. + + When a resource doesn't have this capability, when DSC finds an instance of the resource with + `_exist` set to `false`, it handles calling the [delete][14] operation for the resource. + + If the resource doesn't have this capability or the `Delete` capability, DSC raises an error when + an instance defines `_exist` as `false`. +- `Test` - The resource supports validating the desired state of an + instance against the current state of the instance. A resource has this capability when it + defines the [test][15] property in its resource manifest. + + If a resource doesn't have the `Test` capability, DSC uses a synthetic test for instances of the + resource. The synthetic test compares each property for the desired state of an instance against + the actual state. The synthetic test uses strict, case-sensitive equivalence. If the desired + state for a property and the actual state aren't the same, DSC marks the property as out of the + desired state. +- `Delete` - The resource supports removing an instance. A resource + has this capability when it defines the [delete][14] property in its resource manifest. This + capability isn't mutually exclusive with the `SetHandlesExist` property. A resource can handle + the `_exist` property in set operations and be called directly with [dsc resource delete][16] to + remove an instance. +- `Export` - The resource supports enumerating every instance of the + resource. A resource has this capability when it defines the [export][17] property in its resource + manifest. Only resources with this capability are usable with the [dsc resource export][18] and + [dsc config export][19] commands. + +```yaml +Type: array +Required: true +ItemsMustBeUnique: true +ItemsType: string +ItemsValidValues: [Get, Set, SetHandlesExist, Test, Delete, Export] +``` + ### description Defines a synopsis for the resource's purpose as a short string. If the resource doesn't have a @@ -77,8 +145,8 @@ Required: true ### path -Represents the path to the resource's manifest on the machine. For resources made available through -a provider, this property identifies the path to the file that defines the resource instead. +Represents the path to the resource's manifest on the machine. For adapted resources, this property +identifies the path to the file that defines the resource instead. ```yaml Type: string @@ -87,9 +155,9 @@ Required: true ### directory -Represents the path to the folder containing the resource's manifest on the machine. For resources -made available through a provider, this property identifies the path to the folder containing the -file that defines the resource instead. +Represents the path to the folder containing the resource's manifest on the machine. For adapted +resources, this property identifies the path to the folder containing the file that defines the +resource instead. ```yaml Type: string @@ -111,11 +179,6 @@ Indicates how the DSC Resource was implemented. For command-based resources, thi Indicates the name of the person or organization that developed and maintains the DSC Resource. If this property is `null`, the author is unknown. - - ```yaml Type: [string, 'null'] Required: true @@ -123,14 +186,8 @@ Required: true ### properties -Defines the property names for resources made available through a provider resource. For other -resources, this property is an empty array. - - +Defines the property names for adapted resources. For non-adapted resources, this property is an +empty array. ```yaml Type: array @@ -139,10 +196,11 @@ ItemsType: string ItemsPattern: ^\w+$ ``` -### requires +### requireAdapter -Defines the fully qualified type name of the provider resource that this resource is made available -through. +Defines the fully qualified type name of the DSC Resource Adapter that this resource is made +available through. This value is only defined for adapted resources. For non-adapted resources, +this value is always `null`. ```yaml Type: [string, 'null'] @@ -153,13 +211,31 @@ Required: true Represents the values defined in the resource's manifest. This value is `null` for resources that aren't command-based. For more information on the value for this property, see -[Command-based DSC Resource manifest schema reference][03]. +[Command-based DSC Resource manifest schema reference][20]. ```yaml Type: [object, 'null'] Required: true ``` + [01]: https://jsonlines.org/ [02]: ../../definitions/resourceType.md -[03]: ../../resource/manifest/root.md +[03]: ../../definitions/resourceKind.md#adapter-resources +[04]: ../../definitions/resourceKind.md#group-resources +[05]: ../../resource/manifest/root.md#kind +[06]: ../../definitions/resourceKind.md +[07]: ../../resource/manifest/get.md +[08]: ../../resource/manifest/set.md +[09]: ../../../cli/resource/set.md +[10]: ../../../cli/config/set.md +[11]: ../../../microsoft.dsc/Assertion/resource.md +[12]: ../../resource/properties/exist.md +[13]: ../../resource/manifest/set.md#handlesexist +[14]: ../../resource/manifest/delete.md +[15]: ../../resource/manifest/test.md +[16]: ../../../cli/resource/delete.md +[17]: ../../resource/manifest/export.md +[18]: ../../../cli/resource/export.md +[19]: ../../../cli/config/export.md +[20]: ../../resource/manifest/root.md diff --git a/docs/reference/schemas/outputs/resource/set.md b/docs/reference/schemas/outputs/resource/set.md index 5448938f..77ca082d 100644 --- a/docs/reference/schemas/outputs/resource/set.md +++ b/docs/reference/schemas/outputs/resource/set.md @@ -15,7 +15,7 @@ The result output from the `dsc resource set` command. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/set.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/set.json Type: object ``` @@ -91,17 +91,32 @@ data is returned: ### Required properties +- [metadata](#metadata-1) - [name](#name) - [type](#type) - [result](#result) ### Properties +#### metadata + +Defines metadata DSC returns for a configuration operation. The properties under the +`Microsoft.DSC` property describe the context of the operation. + +- [duration][01] defines the duration of a DSC operation against a configuration document or + resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][02]. + For example, `PT0.611216S` represents a duration of about `0.61` seconds. + +```yaml +Type: object +Required: true +``` + #### 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]. +[DSC Resource fully qualified type name schema reference][03]. ```yaml Type: string @@ -131,4 +146,7 @@ Type: [object, array] Required: true ``` -[01]: ../../definitions/resourceType.md + +[01]: ../../metadata/Microsoft.DSC/properties.md#duration +[02]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A +[03]: ../../definitions/resourceType.md diff --git a/docs/reference/schemas/outputs/resource/test.md b/docs/reference/schemas/outputs/resource/test.md index 2ef67f5f..d1e0e7b1 100644 --- a/docs/reference/schemas/outputs/resource/test.md +++ b/docs/reference/schemas/outputs/resource/test.md @@ -15,7 +15,7 @@ The result output from the `dsc resource test` command. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/outputs/resource/test.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/outputs/resource/test.json Type: object ``` @@ -94,17 +94,32 @@ data is returned: ### Required properties +- [metadata](#metadata-1) - [name](#name) - [type](#type) - [result](#result) ### Properties +#### metadata + +Defines metadata DSC returns for a configuration operation. The properties under the +`Microsoft.DSC` property describe the context of the operation. + +- [duration][01] defines the duration of a DSC operation against a configuration document or + resource instance as a string following the format defined in [ISO8601 ABNF for `duration`][02]. + For example, `PT0.611216S` represents a duration of about `0.61` seconds. + +```yaml +Type: object +Required: true +``` + #### 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]. +[DSC Resource fully qualified type name schema reference][03]. ```yaml Type: string @@ -134,4 +149,7 @@ Type: [object, array] Required: true ``` -[01]: ../../definitions/resourceType.md + +[01]: ../../metadata/Microsoft.DSC/properties.md#duration +[02]: https://datatracker.ietf.org/doc/html/rfc3339#appendix-A +[03]: ../../definitions/resourceType.md diff --git a/docs/reference/schemas/resource/manifest/adapter.md b/docs/reference/schemas/resource/manifest/adapter.md new file mode 100644 index 00000000..41f157a0 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/adapter.md @@ -0,0 +1,126 @@ +--- +description: JSON schema reference for the 'adapter' property in a DSC Resource manifest +ms.date: 01/17/2024 +ms.topic: reference +title: DSC Resource manifest adapter property schema reference +--- + +# DSC Resource manifest adapter property schema reference + +## Synopsis + +Defines a DSC Resource as a DSC Resource Adapter. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.adapter.json +Type: object +``` + +## Description + +DSC Resource Adapters must define the `adapter` property in their manifest. This property +identifies the resource as an adapter and defines how DSC can call the adapter to get the resources +the adapter supports and how to pass resource instances to the adapter. + +## Examples + +### Example 1 - Microsoft.DSC/PowerShell + +This example is from the `Microsoft.DSC/PowerShell` DSC Resource Adapter. + +```json +"adapter": { + "list": { + "executable": "pwsh", + "args": [ + "-NoLogo", + "-NonInteractive", + "-NoProfile", + "-Command", + "./powershell.resource.ps1 List" + ] + }, + "config": "full" +}, +``` + +The manifest sets `config` to `full`, indicating that the adapter expects a JSON blob representing +the full and unprocessed configuration from `stdin`. + +It defines `list.executable` as `pwsh`. The arguments defined in `list.args` ensure that DSC runs +PowerShell: + +- Without the logo banner +- In non-interactive mode +- Without loading any profile scripts +- To invoke the `powershell.resource.ps1` script in the same folder as the `dsc` command and + pass the `List` argument. + +With this definition, DSC calls the `list` method for this adapter by running: + +```sh +pwsh -NoLogo -NonInteractive -NoProfile -Command "./powershellgroup.resource.ps1 List" +``` + +## Required Properties + +The `adapter` definition must include these properties: + +- [config](#config) +- [list](#list) + +## Properties + +### config + +The `config` property defines how the adapter expects to receive resource configurations. The +value must be one of the following options: + +- `full` - Indicates that the adapter expects a JSON blob containing the full and unprocessed + configuration as a single JSON blob over `stdin`. +- `sequence` - Indicates that the adapter expects each resource's configuration as a + [JSON Line][01] over `stdin`. + +```yaml +Type: string +ValidValues: [full, sequence] +``` + +### list + +The `list` property defines how to call the adapter to list the resources it supports. The value +of this property must be an object and define the `executable` sub-property. + +```yaml +Type: object +Required: true +RequiredProperties: [executable] +``` + +#### executable + +The `executable` sub-property defines the name of the command to run. The value must be the name of +a command discoverable in the system's `PATH` environment variable or the full path to the command. +A file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +#### args + +The `args` sub-property defines an array of strings to pass as arguments to the command. DSC passes +the arguments to the command in the order they're specified. + +```yaml +Type: array +Required: false +Default: [] +``` + +[01]: https://jsonlines.org/ diff --git a/docs/reference/schemas/resource/manifest/delete.md b/docs/reference/schemas/resource/manifest/delete.md new file mode 100644 index 00000000..ac4a1b69 --- /dev/null +++ b/docs/reference/schemas/resource/manifest/delete.md @@ -0,0 +1,166 @@ +--- +description: JSON schema reference for the 'delete' property in a DSC Resource manifest +ms.date: 01/17/2024 +ms.topic: reference +title: DSC Resource manifest delete property schema reference +--- + +# DSC Resource manifest delete property schema reference + +## Synopsis + +Indicates how to call the resource to delete a specific instance. + +## Metadata + +```yaml +SchemaDialect: https://json-schema.org/draft/2020-12/schema +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.delete.json +Type: object +``` + +## Description + +Defines how DSC must call the DSC Resource to delete an instance. Define this method for resources +as an alternative to handling the [`_exist`][01] property in a `set` operation, which can lead to +highly complex code. If the `set` method for the resource is able to handle deleting an instance +when `_exist` is `false`, set the [`handlesExist`][02] property of the set method definition to +`true` instead. + +If you define the delete method in a resource manifest, ensure that you also define the +[`_exist`][01] property in the [JSON schema for the resource's properties][03]. + +DSC sends data to the command in three ways: + +1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. +1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. +1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. You can only define one JSON input argument for a command. + +You must define the `input` property, one JSON input argument in the `args` property array, or +both. + +## Examples + +## Required properties + +The `delete` definition must include these properties: + +- [executable](#executable) + +## Properties + +### executable + +The `executable` property defines the name of the command to run. The value must be the name of a +command discoverable in the system's `PATH` environment variable or the full path to the command. A +file extension is only required when the command isn't recognizable by the operating system as an +executable. + +```yaml +Type: string +Required: true +``` + +### args + +The `args` property defines the list of arguments to pass to the command. The arguments can be any +number of strings. If you want to pass the JSON object representing the property bag for the +resource to an argument, you can define a single item in the array as a [JSON object], indicating the +name of the argument with the `jsonInputArg` string property and whether the argument is mandatory +for the command with the `mandatory` boolean property. + +```yaml +Type: array +Required: false +Default: [] +Type: [string, object(JSON Input Argument)] +``` + +#### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `config` or `--format`. + +```yaml +Type: string +``` + +#### JSON input argument + +Defines an argument for the command that accepts the JSON input object as a string. DSC passes the +JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: + +- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. +- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, + even when there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. + +You can only define one JSON input argument per arguments array. + +If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON data both +ways: + +- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable for + each property in the JSON input and passes the JSON input object as a string to the defined + argument. +- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over stdin + and as a string to the defined argument. +- If you define a JSON input argument without defining the `input` property, DSC only passes the + JSON input as a string to the defined argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. This makes the manifest invalid. You must define the `input` property, +a JSON input argument in the `args` property array, or both. + +```yaml +Type: object +RequiredProperties: [jsonInputArg] +``` + +### input + +The `input` property defines how to pass input to the resource. If this property isn't defined and +the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any +input to the resource when invoking the `delete` operation. + +The value of this property must be one of the following strings: + +- `env` - Indicates that the resource expects the properties of an instance to be specified as + environment variables with the same names and casing. + + This option only supports the following data types for instance properties: + + - `boolean` + - `integer` + - `number` + - `string` + - `array` of `integer` values + - `array` of `number` values + - `array` of `string` values + + For non-array values, DSC sets the environment variable to the specified value as-is. When the + data type is an array of values, DSC sets the environment variable as a comma-delimited string. + For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` environment + variable as `"1,2,3"`. + + If the resource needs to support complex properties with an `object` value or multi-type arrays, + set this to `stdin` instead. +- `stdin` - Indicates that the resource expects a JSON blob representing an instance from `stdin`. + The JSON must adhere to the instance schema for the resource. + +```yaml +Type: string +Required: false +ValidValues: [env, stdin] +``` + + +[01]: ../properties/exist.md +[02]: set.md#handlesexist +[03]: schema/property.md diff --git a/docs/reference/schemas/resource/manifest/export.md b/docs/reference/schemas/resource/manifest/export.md index 004e65e5..8587bbbe 100644 --- a/docs/reference/schemas/resource/manifest/export.md +++ b/docs/reference/schemas/resource/manifest/export.md @@ -15,7 +15,7 @@ Defines how to retrieve the current state of every instance for a DSC Resource. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.export.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.export.json Type: object ``` @@ -36,6 +36,21 @@ When the DSC calls the command defined by this property, the resource must retur of every instance as [JSON lines][05]. Each JSON Line should be an object representing the instance and validate against the [defined resource instance schema][06]. +DSC sends data to this command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a + string representing the data as a compressed JSON object to the specified argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. You can only define one JSON input argument for a command. + +You must define the `input` property, one JSON input argument in the `args` property array, or +both. + ## Required Properties The `export` definition must include these properties: @@ -58,13 +73,95 @@ Required: true ### args -The `args` property defines an array of strings to pass as arguments to the command. DSC passes the -arguments to the command in the order they're specified. +The `args` property defines the list of arguments to pass to the command. The arguments can be any +number of strings. If you want to pass the JSON object representing the property bag for the +resource to an argument, you can define a single item in the array as a [JSON object], indicating the +name of the argument with the `jsonInputArg` string property and whether the argument is mandatory +for the command with the `mandatory` boolean property. ```yaml Type: array Required: false Default: [] +Type: [string, object(JSON Input Argument)] +``` + +#### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `config` or `--format`. + +```yaml +Type: string +``` + +#### JSON input argument + +Defines an argument for the command that accepts the JSON input object as a string. DSC passes the +JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: + +- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. +- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, + even when there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. + +You can only define one JSON input argument per arguments array. + +If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON data both +ways: + +- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable for + each property in the JSON input and passes the JSON input object as a string to the defined + argument. +- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over stdin + and as a string to the defined argument. +- If you define a JSON input argument without defining the `input` property, DSC only passes the + JSON input as a string to the defined argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. This makes the manifest invalid. You must define the `input` property, +a JSON input argument in the `args` property array, or both. + +```yaml +Type: object +RequiredProperties: [jsonInputArg] +``` + +### input + +The `input` property defines how to pass input to the resource. If this property isn't defined and +the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any +input to the resource when invoking the `export` operation. + +The value of this property must be one of the following strings: + +- `env` - Indicates that the resource expects the properties of an instance to be specified as + environment variables with the same names and casing. + + This option only supports the following data types for instance properties: + + - `boolean` + - `integer` + - `number` + - `string` + - `array` of `integer` values + - `array` of `number` values + - `array` of `string` values + + For non-array values, DSC sets the environment variable to the specified value as-is. When the + data type is an array of values, DSC sets the environment variable as a comma-delimited string. + For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` environment + variable as `"1,2,3"`. + + If the resource needs to support complex properties with an `object` value or multi-type arrays, + set this to `stdin` instead. +- `stdin` - Indicates that the resource expects a JSON blob representing an instance from `stdin`. + The JSON must adhere to the instance schema for the resource. + +```yaml +Type: string +Required: false +ValidValues: [env, stdin] ``` [01]: ../../../cli/config/export.md diff --git a/docs/reference/schemas/resource/manifest/get.md b/docs/reference/schemas/resource/manifest/get.md index 857b41ba..2bab66ba 100644 --- a/docs/reference/schemas/resource/manifest/get.md +++ b/docs/reference/schemas/resource/manifest/get.md @@ -15,7 +15,7 @@ Defines how to retrieve a DSC Resource instance. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.get.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.get.json Type: object ``` @@ -24,11 +24,20 @@ Type: object Every command-based DSC Resource must define the `get` property in its manifest. This property defines how DSC can get the current state of a resource instance. -When defining this property, be sure to define a value for [input](#input). Even though it isn't -required, most resources need to receive input to enforce the desired state. When this property -isn't defined, DSC doesn't send any input to the resource for `get` operations. The only resources -that usually don't require any input for `get` are resources that only describe a single instance, -like the operating system information or timezone. +DSC sends data to the command in three ways: + +1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. +1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. +1. When the `args` array includes a JSON input argument definition, DSC sends the data as a string + representing the data as a compressed JSON object to the specified argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. You can only define one JSON input argument for a command. + +You must define the `input` property, one JSON input argument in the `args` property array, or +both. ## Examples @@ -52,7 +61,7 @@ With this definition, DSC calls the `get` method for this resource by running: { ... } | osinfo ``` -### Example 2 - Full definition +### Example 2 - Input from stdin This example is from the `Microsoft.Windows/Registry` DSC Resource. @@ -77,6 +86,35 @@ method for this resource by running: { ... } | registry config get ``` +### Example 3 - JSON input argument + +This example uses a JSON input argument to send the data to the command. + +```json +"get": { + "executable": "tstoy", + "args": [ + "config", + "get", + { "jsonInputArg": "--input", "mandatory": true } + ], +} +``` + +It defines the executable as `tstoy`. It defines two [string arguments](#string-arguments) and one [JSON input argument](#json-input-argument). When DSC invokes the `get` operation for this resource, it passes the JSON data to the resource as a compressed JSON string to the `--input` argument. + +The combined call for this operation is: + +```sh +tstoy config get --input "{ ... }" +``` + +Where `{ ... }` represents the compressed JSON for the resource instance. + +Because the `mandatory` option for the JSON input argument is set to `true`, DSC passes an empty +string to the argument when there's no data to send to the command. If the property wasn't defined, +or was defined as `false`, DSC would omit the argument entirely when there's no data to send. + ## Required Properties The `get` definition must include these properties: @@ -99,19 +137,65 @@ Required: true ### args -The `args` property defines an array of strings to pass as arguments to the command. DSC passes the -arguments to the command in the order they're specified. +The `args` property defines the list of arguments to pass to the command. The arguments can be any +number of strings. If you want to pass the JSON object representing the property bag for the +resource to an argument, you can define a single item in the array as a [JSON object], indicating the +name of the argument with the `jsonInputArg` string property and whether the argument is mandatory +for the command with the `mandatory` boolean property. ```yaml Type: array Required: false Default: [] +Type: [string, object(JSON Input Argument)] +``` + +#### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `config` or `--format`. + +```yaml +Type: string +``` + +#### JSON input argument + +Defines an argument for the command that accepts the JSON input object as a string. DSC passes the +JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: + +- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. +- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, + even when there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. + +You can only define one JSON input argument per arguments array. + +If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON data both +ways: + +- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable for + each property in the JSON input and passes the JSON input object as a string to the defined + argument. +- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over stdin + and as a string to the defined argument. +- If you define a JSON input argument without defining the `input` property, DSC only passes the + JSON input as a string to the defined argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. This makes the manifest invalid. You must define the `input` property, +a JSON input argument in the `args` property array, or both. + +```yaml +Type: object +RequiredProperties: [jsonInputArg] ``` ### input -The `input` property defines how to pass input to the resource. If this property isn't defined, DSC -doesn't send any input to the resource when invoking the `get` operation. +The `input` property defines how to pass input to the resource. If this property isn't defined and +the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any +input to the resource when invoking the `get` operation. The value of this property must be one of the following strings: diff --git a/docs/reference/schemas/resource/manifest/provider.md b/docs/reference/schemas/resource/manifest/provider.md deleted file mode 100644 index e3134e4c..00000000 --- a/docs/reference/schemas/resource/manifest/provider.md +++ /dev/null @@ -1,126 +0,0 @@ ---- -description: JSON schema reference for the 'provider' property in a DSC Resource manifest -ms.date: 01/17/2024 -ms.topic: reference -title: DSC Resource manifest provider property schema reference ---- - -# DSC Resource manifest provider property schema reference - -## Synopsis - -Defines a DSC Resource as a DSC Resource Provider. - -## Metadata - -```yaml -SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.provider.json -Type: object -``` - -## Description - -DSC Resource Providers must define the `provider` property in their manifest. This property -identifies the resource as a provider and defines how DSC can call the provider to get the -resources the provider supports and how to pass resource instances to the provider. - -## Examples - -### Example 1 - DSC/PowerShellGroup - -This example is from the `DSC/PowerShellGroup` DSC Resource Provider. - -```json -"provider": { - "config": "full", - "list": { - "executable": "pwsh", - "args": [ - "-NoLogo" - "-NonInteractive" - "-NoProfile" - "-Command" - "./powershellgroup.resource.ps1 List" - ] - } -} -``` - -The manifest sets `config` to `full`, indicating that the provider expects a JSON blob representing -the full and unprocessed configuration from `stdin`. - -It defines `list.executable` as `pwsh`. The arguments defined in `list.args` ensure that DSC runs -PowerShell: - -- Without the logo banner -- In non-interactive mode -- Without loading any profile scripts -- To invoke the `powershellgroup.resource.ps1` script in the same folder as the `dsc` command and - pass the `List` argument. - -With this definition, DSC calls the `list` method for this provider by running: - -```sh -pwsh -NoLogo -NonInteractive -NoProfile -Command "./powershellgroup.resource.ps1 List" -``` - -## Required Properties - -The `provider` definition must include these properties: - -- [config](#config) -- [list](#list) - -## Properties - -### config - -The `config` property defines how the provider expects to receive resource configurations. The -value must be one of the following options: - -- `full` - Indicates that the provider expects a JSON blob containing the full and - unprocessed configuration as a single JSON blob over `stdin`. -- `sequence` - Indicates that the provider expects each resource's configuration as - a [JSON Line][01] over `stdin`. - -```yaml -Type: string -ValidValues: [full, sequence] -``` - -### list - -The `list` property defines how to call the provider to list the resources it supports. The value -of this property must be an object and define the `executable` subproperty. - -```yaml -Type: object -Required: true -RequiredProperties: [executable] -``` - -#### executable - -The `executable` subproperty defines the name of the command to run. The value must be the name of -a command discoverable in the system's `PATH` environment variable or the full path to the command. -A file extension is only required when the command isn't recognizable by the operating system as an -executable. - -```yaml -Type: string -Required: true -``` - -#### args - -The `args` subproperty defines an array of strings to pass as arguments to the command. DSC passes -the arguments to the command in the order they're specified. - -```yaml -Type: array -Required: false -Default: [] -``` - -[01]: https://jsonlines.org/ diff --git a/docs/reference/schemas/resource/manifest/root.md b/docs/reference/schemas/resource/manifest/root.md index e24df4fe..7e218956 100644 --- a/docs/reference/schemas/resource/manifest/root.md +++ b/docs/reference/schemas/resource/manifest/root.md @@ -15,7 +15,7 @@ The data file that defines a command-based DSC Resource. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json Type: object ``` @@ -78,6 +78,9 @@ Type: string Required: true Format: URI ValidValues: [ + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.json + https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/bundled/resource/manifest.vscode.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.json https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/bundled/resource/manifest.vscode.json @@ -121,6 +124,27 @@ Type: string Required: false ``` +### kind + +The `kind` property defines how DSC should handle the resource. DSC supports three kinds of +command-based DSC Resources: `Resource`, `Group`, and `Adapter`. + +When `kind` isn't defined in the resource manifest, DSC infers the value for the property. If the +`adapter` property is defined in the resource manifest, DSC infers the value of `kind` as +`Adapter`. If the `adapter` property isn't defined, DSC infers the value of `kind` as `Resource`. +DSC can't infer whether a manifest is for a group resource. + +When defining a group resource, always explicitly define the `kind` property in the manifest as +`Group`. + +For more information, see [DSC Resource kind schema reference][02]. + +```yaml +Type: string +Required: false +ValidValues: [Resource, Adapter, Group] +``` + ### tags The `tags` property defines a list of searchable terms for the resource. The value of this @@ -140,16 +164,16 @@ ItemsPattern: ^\w+$ The `export` property defines how to call the resource to get the current state of every instance. When this property is defined, users can: -- Specify an instance of the resource in the input configuration for the [dsc config export][02] +- Specify an instance of the resource in the input configuration for the [dsc config export][03] command to generate an usable configuration document. -- Specify the resource with the [dsc resource export][03] command to generate a configuration +- Specify the resource with the [dsc resource export][04] command to generate a configuration document that defines every instance of the resource. -- Specify the resource with the [dsc resource get][04] command and the [--all][05] option to return +- Specify the resource with the [dsc resource get][05] command and the [--all][06] option to return the current state for every instance of the resource. The value of this property must be an object. The object's `executable` property, defining the name of the command to call, is mandatory. The `args` property is optional. For more -information, see [DSC Resource manifest export property schema reference][06]. +information, see [DSC Resource manifest export property schema reference][07]. ```yaml Type: object @@ -163,7 +187,7 @@ property is mandatory for all resources. The value of this property must be an object. The object's `executable` property, defining the name of the command to call, is mandatory. The `args` and `input` properties are optional. For more -information, see [DSC Resource manifest get property schema reference][07]. +information, see [DSC Resource manifest get property schema reference][08]. ```yaml Type: object @@ -179,7 +203,7 @@ test whether the instance is in the desired state. The value of this property must be an object. The `executable` property, defining the name of the command to call, is mandatory. The `args` `input`, `implementsPretest`, and `returns` properties -are optional. For more information, see [DSC Resource manifest set property schema reference][08]. +are optional. For more information, see [DSC Resource manifest set property schema reference][09]. ```yaml Type: object @@ -194,7 +218,7 @@ property isn't defined, DSC performs a basic synthetic test for instances of the The value of this property must be an object. The object's `executable` property, defining the name of the command to call, is mandatory. The `args` `input`, and `returns` properties are optional. -For more information, see [DSC Resource manifest test property schema reference][09]. +For more information, see [DSC Resource manifest test property schema reference][10]. ```yaml Type: object @@ -208,7 +232,7 @@ property is mandatory for DSC Group Resources. DSC ignores this property for all The value of this property must be an object. The object's `executable` property, defining the name of the command to call, is mandatory. The `args` property is optional. For more information, see -[DSC Resource manifest validate property schema reference][10]. +[DSC Resource manifest validate property schema reference][11]. ```yaml Type: object @@ -222,7 +246,7 @@ When specified, the `provider` property defines the resource as a DSC Resource P The value of this property must be an object. The object's `list` and `config` properties are mandatory. The `list` property defines how to call the provider to return the resources that the provider can manage. The `config` property defines how the provider expects input. For more -information, see the [DSC Resource manifest provider property schema reference][11]. +information, see the [DSC Resource manifest provider property schema reference][12]. ### exitCodes @@ -267,7 +291,7 @@ resource. This property must always be an object that defines one of the followi - `embedded` - When you specify the `embedded` property, DSC uses the defined value as the JSON schema. -For more information, see [DSC Resource manifest schema property reference][12]. +For more information, see [DSC Resource manifest schema property reference][13]. ```yaml Type: object @@ -275,14 +299,15 @@ Required: true ``` [01]: ../../definitions/resourceType.md -[02]: ../../../cli/config/export.md -[03]: ../../../cli/resource/export.md -[04]: ../../../cli/resource/get.md -[05]: ../../../cli/resource/get.md#-a---all -[06]: export.md -[07]: get.md -[08]: set.md -[09]: test.md -[10]: validate.md -[11]: provider.md -[12]: schema/property.md +[02]: ../../definitions/resourceKind.md +[03]: ../../../cli/config/export.md +[04]: ../../../cli/resource/export.md +[05]: ../../../cli/resource/get.md +[06]: ../../../cli/resource/get.md#-a---all +[07]: export.md +[08]: get.md +[09]: set.md +[10]: test.md +[11]: validate.md +[12]: provider.md +[13]: schema/property.md diff --git a/docs/reference/schemas/resource/manifest/schema/embedded.md b/docs/reference/schemas/resource/manifest/schema/embedded.md index 48d03d1b..95687e60 100644 --- a/docs/reference/schemas/resource/manifest/schema/embedded.md +++ b/docs/reference/schemas/resource/manifest/schema/embedded.md @@ -15,7 +15,7 @@ Defines a JSON Schema that validates a DSC Resource instance. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.schema.json#/properties/embedded +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json#/properties/embedded Type: object ``` @@ -107,7 +107,7 @@ If defined, this property must be a reference to the schema for the well-known p ```json "_exist": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/exist.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json" } ``` @@ -123,7 +123,7 @@ If defined, this property must be a reference to the schema for the well-known p ```json "_inDesiredState": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/inDesiredState.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/inDesiredState.json" } ``` @@ -139,7 +139,7 @@ If defined, this property must be a reference to the schema for the well-known p ```json "_inDesiredState": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/purge.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json" } ``` @@ -155,7 +155,7 @@ If defined, this property must be a reference to the schema for the well-known p ```json "_rebootRequested": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/rebootRequested.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/rebootRequested.json" } ``` diff --git a/docs/reference/schemas/resource/manifest/schema/property.md b/docs/reference/schemas/resource/manifest/schema/property.md index 3bcbbd8f..fc925472 100644 --- a/docs/reference/schemas/resource/manifest/schema/property.md +++ b/docs/reference/schemas/resource/manifest/schema/property.md @@ -15,7 +15,7 @@ Defines how to retrieve the JSON Schema that validates a DSC Resource instance. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.schema.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.schema.json Type: object ``` diff --git a/docs/reference/schemas/resource/manifest/set.md b/docs/reference/schemas/resource/manifest/set.md index 6977734c..4b09fdae 100644 --- a/docs/reference/schemas/resource/manifest/set.md +++ b/docs/reference/schemas/resource/manifest/set.md @@ -15,7 +15,7 @@ Defines how to enforce state for a DSC Resource instance. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.set.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.set.json Type: object ``` @@ -27,6 +27,21 @@ property defines how DSC can enforce the current state of an instance. When this property isn't defined, DSC can only get the current state of instances and test whether they're in the desired state. DSC can't enforce desired state for the resource. +DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a + string representing the data as a compressed JSON object to the specified argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. You can only define one JSON input argument for a command. + +You must define the `input` property, one JSON input argument in the `args` property array, or +both. + ## Examples ### Example 1 - Full definition @@ -89,19 +104,65 @@ Required: true ### args -The `args` property defines an array of strings to pass as arguments to the command. DSC passes the -arguments to the command in the order they're specified. +The `args` property defines the list of arguments to pass to the command. The arguments can be any +number of strings. If you want to pass the JSON object representing the property bag for the +resource to an argument, you can define a single item in the array as a [JSON object], indicating the +name of the argument with the `jsonInputArg` string property and whether the argument is mandatory +for the command with the `mandatory` boolean property. ```yaml Type: array Required: false Default: [] +Type: [string, object(JSON Input Argument)] +``` + +#### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `config` or `--format`. + +```yaml +Type: string +``` + +#### JSON input argument + +Defines an argument for the command that accepts the JSON input object as a string. DSC passes the +JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: + +- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. +- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, + even when there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. + +You can only define one JSON input argument per arguments array. + +If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON data both +ways: + +- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable for + each property in the JSON input and passes the JSON input object as a string to the defined + argument. +- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over stdin + and as a string to the defined argument. +- If you define a JSON input argument without defining the `input` property, DSC only passes the + JSON input as a string to the defined argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. This makes the manifest invalid. You must define the `input` property, +a JSON input argument in the `args` property array, or both. + +```yaml +Type: object +RequiredProperties: [jsonInputArg] ``` ### input -The `input` property defines how to pass input to the resource. If this property isn't defined, DSC -doesn't send any input to the resource when invoking the `set` operation. +The `input` property defines how to pass input to the resource. If this property isn't defined and +the definition doesn't define a [JSON input argument](#json-input-argument), DSC doesn't send any +input to the resource when invoking the `set` operation. The value of this property must be one of the following strings: @@ -152,6 +213,27 @@ Required: false Default: false ``` +### handlesExist + +The `handlesExist` property defines whether the resource has built-in handling for the +[_exist][01] property in the `set` operation. The default value is `false`. + +Set this property to `true` when the resource meets the following implementation requirements: + +- The resource's [instance schema][02] defines the `_exist` property as a valid instance property. +- The resource's `set` command handles creating, updating, and deleting an instance based on the + current state of the instance and the value of the `_exist` property in the desired state. + +When this property is set to `true`, the resource indicates that it has the [SetHandlesExist][03] +[capability][04]. When processing resources with the `SetHandlesExist` capability in a +configuration, DSC calls the `set` operation for the resource when an instance defines `_exist` as +`false`. Without this capability, a resource must define the [delete][05] operation to support +removing instances of the resource. + +If a resource manifest doesn't define this property as `true` and doesn't define the `delete` +operation, DSC raises an error when it encounters an instance of the resource with `_exist` set to +`false`. + ### return The `return` property defines how DSC should process the output for this method. The value of this @@ -170,3 +252,10 @@ Required: false Default: state ValidValues: [state, stateAndDiff] ``` + + +[01]: ../properties/exist.md +[02]: ./root.md#schema-1 +[03]: ../../outputs/resource/list.md#capability-sethandlesexist +[04]: ../../outputs/resource/list.md#capabilities +[05]: ./delete.md diff --git a/docs/reference/schemas/resource/manifest/test.md b/docs/reference/schemas/resource/manifest/test.md index e2f7dc9f..e46b0a90 100644 --- a/docs/reference/schemas/resource/manifest/test.md +++ b/docs/reference/schemas/resource/manifest/test.md @@ -15,7 +15,7 @@ Defines how to test whether a DSC Resource instance is in the desired state. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.test.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.test.json Type: object ``` @@ -42,6 +42,21 @@ package. For resources with properties that can't be evaluated by equivalency alone, always define the `test` property in the manifest. +DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a + string representing the data as a compressed JSON object to the specified argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. You can only define one JSON input argument for a command. + +You must define the `input` property, one JSON input argument in the `args` property array, or +both. + ## Examples ### Example 1 - Full definition @@ -97,13 +112,58 @@ Required: true ### args -The `args` property defines an array of strings to pass as arguments to the command. DSC passes the -arguments to the command in the order they're specified. +The `args` property defines the list of arguments to pass to the command. The arguments can be any +number of strings. If you want to pass the JSON object representing the property bag for the +resource to an argument, you can define a single item in the array as a [JSON object], indicating the +name of the argument with the `jsonInputArg` string property and whether the argument is mandatory +for the command with the `mandatory` boolean property. ```yaml Type: array Required: false Default: [] +Type: [string, object(JSON Input Argument)] +``` + +#### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `config` or `--format`. + +```yaml +Type: string +``` + +#### JSON input argument + +Defines an argument for the command that accepts the JSON input object as a string. DSC passes the +JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: + +- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. +- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, + even when there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. + +You can only define one JSON input argument per arguments array. + +If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON data both +ways: + +- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable for + each property in the JSON input and passes the JSON input object as a string to the defined + argument. +- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over stdin + and as a string to the defined argument. +- If you define a JSON input argument without defining the `input` property, DSC only passes the + JSON input as a string to the defined argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. This makes the manifest invalid. You must define the `input` property, +a JSON input argument in the `args` property array, or both. + +```yaml +Type: object +RequiredProperties: [jsonInputArg] ``` ### input diff --git a/docs/reference/schemas/resource/manifest/validate.md b/docs/reference/schemas/resource/manifest/validate.md index c1824704..16b5c834 100644 --- a/docs/reference/schemas/resource/manifest/validate.md +++ b/docs/reference/schemas/resource/manifest/validate.md @@ -9,13 +9,13 @@ title: DSC Resource manifest validate property schema reference ## Synopsis -This property +Indicates how to call a group resource to test whether nested instances are valid. ## Metadata ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/manifest.validate.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/manifest.validate.json Type: object ``` @@ -27,6 +27,21 @@ have valid definitions. Always define the `validate` property for group resources in the DSC Resource manifest. +DSC sends data to the command in three ways: + + 1. When `input` is `stdin`, DSC sends the data as a string representing the data as a compressed + JSON object without spaces or newlines between the object properties. + 1. When `input` is `env`, DSC sends the data as environment variables. It creates an environment + variable for each property in the input data object, using the name and value of the property. + 1. When the `args` array includes a JSON input argument definition, DSC sends the data as a + string representing the data as a compressed JSON object to the specified argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. You can only define one JSON input argument for a command. + +You must define the `input` property, one JSON input argument in the `args` property array, or +both. + ## Examples ### Example 1 - Full definition @@ -74,11 +89,92 @@ Required: true ### args -The `args` property defines an array of strings to pass as arguments to the command. DSC passes the -arguments to the command in the order they're specified. +The `args` property defines the list of arguments to pass to the command. The arguments can be any +number of strings. If you want to pass the JSON object representing the property bag for the +resource to an argument, you can define a single item in the array as a [JSON object], indicating the +name of the argument with the `jsonInputArg` string property and whether the argument is mandatory +for the command with the `mandatory` boolean property. ```yaml Type: array Required: false Default: [] +Type: [string, object(JSON Input Argument)] +``` + +#### String arguments + +Any item in the argument array can be a string representing a static argument to pass to the +command, like `config` or `--format`. + +```yaml +Type: string +``` + +#### JSON input argument + +Defines an argument for the command that accepts the JSON input object as a string. DSC passes the +JSON input to the named argument when available. A JSON input argument is defined as a JSON object with the following properties: + +- `jsonInputArg` (required) - the argument to pass the JSON data to for the command, like `--input`. +- `mandatory` (optional) - Indicate whether DSC should always pass the argument to the command, + even when there's no JSON input for the command. In that case, DSC passes an empty string to the + JSON input argument. + +You can only define one JSON input argument per arguments array. + +If you define a JSON input argument and an `input` kind for a command, DSC sends the JSON data both +ways: + +- If you define `input` as `env` and a JSON input argument, DSC sets an environment variable for + each property in the JSON input and passes the JSON input object as a string to the defined + argument. +- If you define `input` as `stdin` and a JSON input argument, DSC passes the JSON input over stdin + and as a string to the defined argument. +- If you define a JSON input argument without defining the `input` property, DSC only passes the + JSON input as a string to the defined argument. + +If you don't define the `input` property and don't define a JSON input argument, DSC can't pass the +input JSON to the resource. This makes the manifest invalid. You must define the `input` property, +a JSON input argument in the `args` property array, or both. + +```yaml +Type: object +RequiredProperties: [jsonInputArg] +``` + +### input + +The `input` property defines how to pass input to the resource. If this property isn't defined, DSC +doesn't send any input to the resource when invoking the `validate` operation. + +The value of this property must be one of the following strings: + +- `env` - Indicates that the resource expects the properties of an instance to be specified as + environment variables with the same names and casing. + + This option only supports the following data types for instance properties: + + - `boolean` + - `integer` + - `number` + - `string` + - `array` of `integer` values + - `array` of `number` values + - `array` of `string` values + + For non-array values, DSC sets the environment variable to the specified value as-is. When the + data type is an array of values, DSC sets the environment variable as a comma-delimited string. + For example, the property `foo` with a value of `[1, 2, 3]` is saved in the `foo` environment + variable as `"1,2,3"`. + + If the resource needs to support complex properties with an `object` value or multi-type arrays, + set this to `stdin` instead. +- `stdin` - Indicates that the resource expects a JSON blob representing an instance from `stdin`. + The JSON must adhere to the instance schema for the resource. + +```yaml +Type: string +Required: false +ValidValues: [env, stdin] ``` diff --git a/docs/reference/schemas/resource/properties/exist.md b/docs/reference/schemas/resource/properties/exist.md index 4e75c8bf..2803a412 100644 --- a/docs/reference/schemas/resource/properties/exist.md +++ b/docs/reference/schemas/resource/properties/exist.md @@ -15,7 +15,7 @@ Indicates whether an instance should exist. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/exist.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json Type: boolean DefaultValue: true ``` @@ -44,6 +44,6 @@ snippet: ```json "_exist": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/exist.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/exist.json" } ``` diff --git a/docs/reference/schemas/resource/properties/inDesiredState.md b/docs/reference/schemas/resource/properties/inDesiredState.md index a32f29dc..d2f892e6 100644 --- a/docs/reference/schemas/resource/properties/inDesiredState.md +++ b/docs/reference/schemas/resource/properties/inDesiredState.md @@ -15,7 +15,7 @@ Indicates whether an instance is in the desired state. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/inDesiredState.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/inDesiredState.json Type: [boolean, 'null'] ReadOnly: true ``` @@ -43,7 +43,7 @@ snippet: ```json "_inDesiredState": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/inDesiredState.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/inDesiredState.json" } ``` diff --git a/docs/reference/schemas/resource/properties/purge.md b/docs/reference/schemas/resource/properties/purge.md index 16249795..e8440004 100644 --- a/docs/reference/schemas/resource/properties/purge.md +++ b/docs/reference/schemas/resource/properties/purge.md @@ -15,7 +15,7 @@ Indicates that the resource should treat non-defined entries in a list as invali ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/purge.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json Type: [boolean, 'null'] WriteOnly: true ``` @@ -44,6 +44,6 @@ snippet: ```json "_inDesiredState": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/purge.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/purge.json" } ``` diff --git a/docs/reference/schemas/resource/properties/rebootRequested.md b/docs/reference/schemas/resource/properties/rebootRequested.md index fd6f1394..2ce8d38c 100644 --- a/docs/reference/schemas/resource/properties/rebootRequested.md +++ b/docs/reference/schemas/resource/properties/rebootRequested.md @@ -15,7 +15,7 @@ Indicates whether an instance is in the desired state. ```yaml SchemaDialect: https://json-schema.org/draft/2020-12/schema -SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/rebootRequested.json +SchemaID: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/rebootRequested.json Type: [boolean, 'null'] ReadOnly: true ``` @@ -43,6 +43,6 @@ snippet: ```json "_rebootRequested": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/rebootRequested.json" + "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/resource/properties/rebootRequested.json" } ```