diff --git a/.openpublishing.redirection.json b/.openpublishing.redirection.json index 0a6057e..56e14be 100644 --- a/.openpublishing.redirection.json +++ b/.openpublishing.redirection.json @@ -39,6 +39,11 @@ "source_path": "dsc/docs-conceptual/dsc-2.0/concepts/terminology.md", "redirect_url": "/powershell/dsc/concepts/glossary?view=dsc-2.0", "redirect_document_id": true + }, + { + "source_path": "dsc/dsc-3.0/docs-conceptual/reference/schemas/resource/manifest/provider.md", + "redirect_url": "/powershell/dsc/reference/schemas/resource/manifest/adapter?view=dsc-3.0", + "redirect_document_id": true } ] } \ No newline at end of file diff --git a/dsc/docs-conceptual/dsc-3.0/changelog.md b/dsc/docs-conceptual/dsc-3.0/changelog.md index 851b230..815552d 100644 --- a/dsc/docs-conceptual/dsc-3.0/changelog.md +++ b/dsc/docs-conceptual/dsc-3.0/changelog.md @@ -3,13 +3,35 @@ title: "Desired State Configuration changelog" description: >- A log of the changes for releases of DSCv3. ms.topic: whats-new -ms.date: 03/06/2024 ---- +ms.date: 05/09/2024 # Changelog + + All notable changes to DSCv3 are documented in this file. The format is based on [Keep a Changelog][m1], and DSCv3 adheres to [Semantic Versioning][m2]. @@ -22,10 +44,514 @@ All notable changes to DSCv3 are documented in this file. The format is based on This section includes a summary of user-facing changes since the last release. For the full list of 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 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. + +
Related work items + + - 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 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. + + 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()][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][p7-18] list for the instance using the reference. + + - The [createArray()][createArray()] function enables you to create arrays of a given type from + values. + + - The [int()][int()] function enables you to convert strings and numbers with fractional parts + into integers. + +
Related work items + + - Issues: + - [#57][#57] + - PRs: + - [#347][#347] + - [#349][#349] + - [#352][#352] + - [#353][#353] + - [#354][#354] + - [#360][#360] + - [#361][#361] + - [#375][#375] + - [#376][#376] + +
+ +- 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]: reference/schemas/resource/manifest/adapter.md +[p7-02]: reference/schemas/outputs/resource/list.md#requireadapter +[p7-03]: reference/schemas/definitions/parameters/dataTypes.md +[p7-04]: reference/cli/resource/list.md#-a---adapter +[p7-05]: reference/schemas/resource/manifest/delete.md +[p7-06]: reference/schemas/resource/properties/exist.md +[p7-07]: reference/schemas/resource/manifest/set.md#handlesexist +[p7-08]: reference/schemas/outputs/resource/list.md#capability-sethandlesexist +[p7-09]: reference/schemas/outputs/resource/list.md#capability-delete +[p7-10]: reference/schemas/resource/manifest/root.md#schema-1 +[p7-11]: reference/schemas/config/metadata.md +[p7-12]: reference/schemas/resource/manifest/delete.md#json-input-argument +[p7-13]: reference/schemas/resource/manifest/export.md#json-input-argument +[p7-14]: reference/schemas/resource/manifest/get.md#json-input-argument +[p7-15]: reference/schemas/resource/manifest/set.md#json-input-argument +[p7-16]: reference/schemas/resource/manifest/test.md#json-input-argument +[p7-17]: reference/schemas/resource/manifest/validate.md#json-input-argument +[p7-18]: reference/schemas/config/resource.md#dependsOn +[p7-19]: reference/schemas/resource/manifest/root.md#kind +[p7-20]: reference/schemas/outputs/resource/list.md +[p7-21]: reference/schemas/definitions/resourceKind.md#group-resources +[p7-22]: reference/schemas/definitions/resourceKind.md#adapter-resources +[p7-23]: reference/schemas/definitions/resourceKind.md +[p7-24]: reference/schemas/outputs/resource/list.md#capabilities +[p7-25]: reference/schemas/outputs/config/get.md#metadata-1 +[p7-26]: reference/schemas/outputs/config/test.md#metadata-1 +[p7-27]: reference/schemas/outputs/config/set.md#metadata-1 +[p7-28]: reference/schemas/outputs/resource/get.md#metadata-1 +[p7-29]: reference/schemas/outputs/resource/test.md#metadata-1 +[p7-30]: reference/schemas/outputs/resource/set.md#metadata-1 +[p7-31]: reference/schemas/config/parameter.md#defaultvalue +[p7-32]: reference/schemas/config/parameter.md#type +[p7-33]: reference/cli/dsc.md#-l---trace-level ## [v3.0.0-alpha.5][release-v3.0.0-alpha.5] - 2024-02-27 @@ -47,13 +573,16 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. `--document` and `--path` options for specifying the configuration document as a string or from a file. The relevant `resource` subcommands have the `--input` and `--path` options for specifying the instance properties as a string or from a file. - - The `--logging-level` option is renamed to [--trace-level][36] with the short name `-l`. The + - The `--logging-level` option is renamed to [--trace-level][a5.05] with the short name `-l`. The default trace level is now `warning` instead of `info`. - - Added the [--trace-format][37] option with the `-f` short name. This option enables you to + - Added the [--trace-format][a5.06] option with the `-f` short name. This option enables you to choose the format for the trace messages emitted to stderr. By default, the messages are emitted as lines of text with console colors. You can set this option to `plaintext` to emit the messages without console colors or to `json` to emit the messages as JSON objects. + The trace messaging is also updated to only emit source files and line numbers for the `debug` + and `trace` levels. +
Related work items - Issues: @@ -64,12 +593,13 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. - [#299][#299] - [#303][#303] - [#305][#305] + - [#388][#388]
-- Updated the JSON schemas for the [get][38], [set][39], and [test][40] output data. This change - corrects an issue with how DSC surfaced information about instances nested inside group and - adapter resources. Now when you review the output, you'll be able to see the results for each +- Updated the JSON schemas for the [get][a5.07], [set][a5.08], and [test][a5.09] output data. This + change corrects an issue with how DSC surfaced information about instances nested inside group + and adapter resources. Now when you review the output, you'll be able to see the results for each nested instance instead of a confusing object that loses the nested instance type and name information. @@ -83,27 +613,28 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. - [#284][#284] - PRs: [#318][#318] -
+
Related work items - Issues: [#271][#271] - PRs: [#322][#322] -
+
Related work items @@ -125,11 +656,12 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. -- Added the [DSCConfigRoot][42] environment variable and the [envvar() configuration function][43] - to enable users to reference files and folders relative to the folder containing the - configuration document. DSC automatically creates the `DSCConfigRoot` environment variable when - you use the `--path` option to specify the configuration document instead of passing the document - as a string from stdin or with the `--document` option. +- Added the [DSCConfigRoot][a5.11] environment variable and the + [envvar() configuration function][a5.12] to enable users to reference files and folders relative + to the folder containing the configuration document. DSC automatically and only creates the + `DSCConfigRoot` environment variable when you use the `--path` option to specify the + configuration document instead of passing the document as a string from stdin or with the + `--document` option. > [!NOTE] > In this release, DSC doesn't expand the specified path to an absolute path. You should always @@ -149,9 +681,10 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. -- Added support for using the [dsc config export][44] and [dsc resource export][45] commands with - the PowerShell adapter resource. PSDSC resources can now participate in the `export` command if - they define a static method that returns an array of the PSDSC resource class. +- 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 @@ -161,11 +694,11 @@ 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][46] command. This new column indicates which methods the resource explicitly - implements. Valid values include `get`, `set`, `test`, and `export`. This information is only - available in the table view. It isn't part of the output object for the command. If you use the - [--format][47] parameter, capture the command output, or redirect the output, the `methods` - information isn't included. + [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 + `methods` information isn't included. Resources that don't implement `test` rely on DSC's synthetic test behavior instead. They can still be used for test and set operations. @@ -196,6 +729,21 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.5]. + +[a5.01]: docs/reference/schemas/config/functions/parameters.md +[a5.02]: docs/reference/cli/config/command.md#-p---parameters +[a5.03]: docs/reference/cli/config/command.md#-f---parameters_file +[a5.04]: docs/reference/cli/config/command.md +[a5.05]: docs/reference/cli/dsc.md#-l---trace-level +[a5.06]: docs/reference/cli/dsc.md#-f---trace-format +[a5.07]: docs/reference/schemas/outputs/resource/get.md +[a5.08]: docs/reference/schemas/outputs/resource/set.md +[a5.09]: docs/reference/schemas/outputs/resource/test.md +[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.16]: docs/reference/cli/resource/list.md#-f---format + ## [v3.0.0-alpha.4][release-v3.0.0-alpha.4] - 2023-11-14 This section includes a summary of changes for the `alpha.4` release. For the full list of changes @@ -210,14 +758,14 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4]. - Updated the canonical version of the schema URIs from `2023/08` to `2023/10`, as this release includes breaking changes for the schemas. - As part of this change, the `$schema` keyword for both [configuration documents][21] and - [resource manifests][22] accepts any valid URI for the schemas, instead of only one. Now, you + As part of this change, the `$schema` keyword for both [configuration documents][a4.01] and + [resource manifests][a4.02] accepts any valid URI for the schemas, instead of only one. Now, you can set the value for the keyword to the unbundled schema, the bundled schema, or the enhanced authoring schema for any supported version. -- Replaced the `_ensure` well-known property with the boolean [_exist][23] property. This improves - the semantics for users and simplifies implementation for resources, replacing the string enum - values `Present` and `Absent` with `true` and `false` respectively. +- Replaced the `_ensure` well-known property with the boolean [_exist][a4.03] property. This + improves the semantics for users and simplifies implementation for resources, replacing the + string enum values `Present` and `Absent` with `true` and `false` respectively.
Related work items @@ -268,7 +816,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4].
-- Added the new [completer][26] command enables users to add shell completions for DSC to their +- Added the new [completer][a4.04] command enables users to add shell completions for DSC to their shell. The command supports completions for Bash, Elvish, fish, PowerShell, and ZSH.
Related work items @@ -305,8 +853,9 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4].
-- Added initial [configuration document functions][28] to DSC. You can now use the [base64()][29], - [concat()][30], and [resourceId()][31] functions in the configuration document. +- Added initial [configuration document functions][a4.05] to DSC. You can now use the + [base64()][a4.06], [concat()][a4.07], and [resourceId()][a4.08] functions in the configuration + document. > [!NOTE] > The `resourceId` function has been reimplemented as a document function instead of a special @@ -362,6 +911,16 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.4]. + +[a4.01]: docs/reference/schemas/config/document.md#schema +[a4.02]: docs/reference/schemas/resource/manifest/root.md#schema +[a4.03]: docs/reference/schemas/resource/properties/exist.md +[a4.04]: docs/reference/cli/completer/command.md +[a4.05]: docs/reference/schemas/config/functions/overview.md +[a4.06]: docs/reference/schemas/config/functions/base64.md +[a4.07]: docs/reference/schemas/config/functions/concat.md +[a4.08]: docs/reference/schemas/config/functions/resourceId.md + ## [v3.0.0-alpha.3][release-v3.0.0-alpha.3] - 2023-09-26 This section includes a summary of changes for the `alpha.3` release. For the full list of changes @@ -373,7 +932,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3]. ### Changed -- Replaced the `manifestVersion` property for resource manifests with [$schema][15]. Instead of +- Replaced the `manifestVersion` property for resource manifests with [$schema][a3.01]. Instead of specifying a semantic version, resources need to indicate which canonical schema DSC should use to validate and process the manifest. @@ -385,7 +944,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3]. - Updated the `preTest` property for the `set` command in resource manifests to - [implementsPretest][16] to more make the manifest easier to read and understand. + [implementsPretest][a3.02] to more make the manifest easier to read and understand.
Related work items @@ -393,7 +952,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3].
-- The [dsc resource set][17] 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. @@ -405,7 +964,8 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3]. - Replaced the `args` option with `env` for defining how a command-based resource expects to - receive input for the [get][18], [set][19], and [test][20] commands in the resource manifest. + receive input for the [get][a3.04], [set][a3.05], and [test][a3.06] commands in the resource + manifest. The `args` option was never implemented. Instead, resource authors can set the `input` property to `env` to indicate that the resource expects input as environmental variables. @@ -416,7 +976,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.3]. -- The `input` property for the [get][18] command in a resource manifest no longer has a default +- The `input` property for the [get][a3.04] command in a resource manifest no longer has a default value. Instead, when a resource doesn't define `input` for the `get` command, DSC doesn't send any input to the resource for that command. @@ -426,6 +986,13 @@ 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.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 + ## [v3.0.0-alpha.2][release-v3.0.0-alpha.2] - 2023-09-05 This section includes a summary of changes for the `alpha.2` release. For the full list of changes @@ -435,11 +1002,23 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2]. [release-v3.0.0-alpha.2]: https://github.com/PowerShell/DSC/releases/tag/v3.0.0-alpha.2 "Link to the DSC v3.0.0-alpha.2 release on GitHub" [compare-v3.0.0-alpha.2]: https://github.com/PowerShell/DSC/compare/v3.0.0-alpha.1...v3.0.0-alpha.2 +### Changed + +- The [$schema][a2.14] value for configuration documents now points to the canonical published + schema URI, + `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json`. + +
Related work items + + - PRs: [#156][#156] + +
+ ### Added -- Implemented functionality for the [dependsOn property of resource instances][01] in configuration - documents, enabling resource instances to depend on the successful processing of one or more - other instances in the document. +- Implemented functionality for the [dependsOn property of resource instances][a2.01] in + configuration documents, enabling resource instances to depend on the successful processing of + one or more other instances in the document.
Related work items @@ -448,8 +1027,8 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-- Added the [export][02] property to the resource manifest schema, indicating that the resource is - exportable and defining how DSC can retrieve the current state for every instance of the +- Added the [export][a2.02] property to the resource manifest schema, indicating that the resource + is exportable and defining how DSC can retrieve the current state for every instance of the resource.
Related work items @@ -459,9 +1038,9 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-- Added the [dsc config export][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 @@ -470,8 +1049,8 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-- Added the [dsc resource export][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 @@ -480,8 +1059,8 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-- Added the [--all][05] option for the [dsc resource get][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 @@ -494,7 +1073,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2]. - Added handling for the Ctrl+C key combination to cancel a DSC operation. When `dsc` cancels an operation due to this key-press, it indicates that the operation was - cancelled with [exit code 6][07]. + cancelled with [exit code 6][a2.07].
Related work items @@ -503,7 +1082,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-- Added support for using the [DSC_RESOURCE_PATH environment variable][08] to define a list of +- Added support for using the [DSC_RESOURCE_PATH environment variable][a2.08] to define a list of folders to search for command-based DSC Resource manifests. When `DSC_RESOURCE_PATH` is defined, DSC searches those folders for resources and ignores the `PATH` variable for resource discovery. @@ -516,7 +1095,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2]. - The `DSC/AssertionGroup`, `DSC/Group`, and `DSC/ParallelGroup` resources now define semantic exit codes in their manifests. These resources now indicate that they use the same - [exit codes as the dsc command][08]. + [exit codes as the dsc command][a2.08].
Related work items @@ -525,10 +1104,10 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-- Added type validation in the schema for the [defaultValue][09] and [allowedValues][10] properties - of [configuration document parameters][11] to improve the authoring experience. Now, when a - parameter defines values for these properties that are incompatible with the defined data type, - validation raises an error indicating that the values are invalid and why. +- Added type validation in the schema for the [defaultValue][a2.09] and [allowedValues][a2.10] + properties of [configuration document parameters][a2.11] to improve the authoring experience. + Now, when a parameter defines values for these properties that are incompatible with the defined + data type, validation raises an error indicating that the values are invalid and why.
Related work items @@ -544,7 +1123,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2]. - Define default snippets to autocomplete values. These schemas are non-canonical and should only be used for authoring. For more information, see - [Authoring with enhanced schemas][12]. + [Authoring with enhanced schemas][a2.12].
Related work items @@ -552,7 +1131,7 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-- Documentation to the [Microsoft/OSInfo][13] resource instance schema and command-line tool to +- Documentation to the [Microsoft/OSInfo][a2.13] resource instance schema and command-line tool to provide contextual help about the properties the resource can validate.
Related work items @@ -561,23 +1140,11 @@ in this release, see the [diff on GitHub][compare-v3.0.0-alpha.2].
-### Changed - -- The [$schema][14] value for configuration documents now points to the canonical published schema - URI, - `https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json`. - -
Related work items - - - PRs: [#156][#156] - -
- ### Fixed -- The data-type conditionals for the [configuration parameters][11] schema so that the `min*` and - `max*` keywords apply to the correct data types. Previously, the logic prevented them from ever - applying. +- The data-type conditionals for the [configuration parameters][a2.11] schema so that the `min*` + and `max*` keywords apply to the correct data types. Previously, the logic prevented them from + ever applying.
Related work items @@ -594,6 +1161,19 @@ 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.05]: docs/reference/cli/resource/get.md##a---all +[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 +[a2.10]: docs/reference/schemas/config/parameter.md#allowedvalues +[a2.11]: docs/reference/schemas/config/parameter.md +[a2.12]: /powershell/dsc/concepts/enhanced-authoring?view=dsc-3.0&preserve-view=true +[a2.13]: /powershell/dsc/reference/microsoft/osinfo/resource?view=dsc-3.0&preserve-view=true +[a2.14]: docs/reference/schemas/config/document.md#schema + ## [v3.0.0-alpha.1][release-v3.0.0-alpha.1] - 2023-08-04 This is the first public release of DSC v3. Consider this release alpha quality. Use it only for @@ -605,57 +1185,40 @@ 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 - -[01]: reference/schemas/config/resource.md#dependson -[02]: reference/schemas/resource/manifest/export.md -[03]: reference/cli/config/export.md -[04]: reference/cli/resource/export.md -[05]: reference/cli/resource/get.md#-a---all -[06]: reference/cli/resource/get.md -[07]: reference/cli/dsc.md#exit-codes -[08]: reference/cli/dsc.md#environment-variables -[09]: reference/schemas/config/parameter.md#defaultvalue -[10]: reference/schemas/config/parameter.md#allowedvalues -[11]: reference/schemas/config/parameter.md -[12]: /powershell/dsc/concepts/enhanced-authoring?view=dsc-3.0&preserve-view=true -[13]: /powershell/dsc/reference/microsoft/osinfo/resource?view=dsc-3.0&preserve-view=true -[14]: reference/schemas/config/document.md#schema - - -[15]: reference/schemas/resource/manifest/root.md#schema -[16]: reference/schemas/resource/manifest/set.md#implementspretest -[17]: reference/cli/resource/set.md -[18]: reference/schemas/resource/manifest/get.md#input -[19]: reference/schemas/resource/manifest/set.md#input -[20]: reference/schemas/resource/manifest/test.md#input - - -[21]: reference/schemas/config/document.md#schema -[22]: reference/schemas/resource/manifest/root.md#schema -[23]: reference/schemas/resource/properties/exist.md -[26]: reference/cli/completer/command.md -[28]: reference/schemas/config/functions/overview.md -[29]: reference/schemas/config/functions/base64.md -[30]: reference/schemas/config/functions/concat.md -[31]: reference/schemas/config/functions/resourceId.md - - -[32]: reference/schemas/config/functions/parameters.md -[33]: reference/cli/config/command.md#-p---parameters -[34]: reference/cli/config/command.md#-f---parameters_file -[35]: reference/cli/config/command.md -[36]: reference/cli/dsc.md#-l---trace-level -[37]: reference/cli/dsc.md#-f---trace-format -[38]: reference/schemas/outputs/resource/get.md -[39]: reference/schemas/outputs/resource/set.md -[40]: reference/schemas/outputs/resource/test.md -[41]: reference/schemas/config/functions/concat.md -[42]: reference/cli/config/command.md#environment-variables -[43]: reference/schemas/config/functions/envvar.md -[44]: reference/cli/config/export.md -[45]: reference/cli/resource/export.md -[46]: reference/cli/resource/list.md -[47]: reference/cli/resource/list.md#-f---format + +[cmd]: reference/cli/dsc.md +[cmd-completion]: reference/cli/completer/command.md +[cmd-schema]: reference/cli/schema/command.md +[cmd-c]: reference/cli/config/command.md +[cmd-cexport]: reference/cli/config/export.md +[cmd-cget]: reference/cli/config/get.md +[cmd-cset]: reference/cli/config/set.md +[cmd-ctest]: reference/cli/config/test.md +[cmd-r]: reference/cli/resource/command.md +[cmd-rdelete]: reference/cli/resource/delete.md +[cmd-rexport]: reference/cli/resource/export.md +[cmd-rget]: reference/cli/resource/get.md +[cmd-rlist]: reference/cli/resource/list.md +[cmd-rschema]: reference/cli/resource/schema.md +[cmd-rset]: reference/cli/resource/set.md +[cmd-rtest]: reference/cli/resource/test.md + +[cfuncs]: reference/schemas/config/functions/overview.md +[add()]: reference/schemas/config/functions/add.md +[base64()]: reference/schemas/config/functions/base64.md +[concat()]: reference/schemas/config/functions/concat.md +[createArray()]: reference/schemas/config/functions/createArray.md +[div()]: reference/schemas/config/functions/div.md +[envvar()]: reference/schemas/config/functions/envvar.md +[int()]: reference/schemas/config/functions/int.md +[max()]: reference/schemas/config/functions/max.md +[min()]: reference/schemas/config/functions/min.md +[mod()]: reference/schemas/config/functions/mod.md +[mul()]: reference/schemas/config/functions/mul.md +[parameters()]: reference/schemas/config/functions/parameters.md +[reference()]: reference/schemas/config/functions/reference.md +[resourceId()]: reference/schemas/config/functions/resourceId.md +[sub()]: reference/schemas/config/functions/sub.md [#107]: https://github.com/PowerShell/DSC/issues/107 @@ -664,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 @@ -694,33 +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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md index 376b620..6b97de6 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/command.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config' command -ms.date: 02/05/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc config --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md index e306375..06f18dd 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/get.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config get' command -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc config get --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md index e6dd3da..af63c1c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/set.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config set' command -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc config set --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md index 51b5e8a..537a556 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/config/test.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc config test' command -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc config test --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/delete.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/delete.md new file mode 100644 index 0000000..3ddb751 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/delete.md @@ -0,0 +1,158 @@ +--- +description: Command line reference for the 'dsc resource delete' command +ms.date: 05/09/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/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md index fb9b1b6..72a51bc 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/cli/resource/list.md @@ -1,6 +1,6 @@ --- description: Command line reference for the 'dsc resource list' command -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc resource list --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md index 3665b2e..5ed2199 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/document.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a Desired State Configuration document. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Configuration document schema reference --- @@ -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 ``` @@ -29,7 +29,7 @@ A configuration document can be defined as either YAML or JSON. For ease of auth recommends drafting configuration documents in YAML. For DSC's authoring tools to recognize a file as a DSC Configuration document, the filename must -end with `.dsc.config.json` or `.dsc.config.yaml`. +end with `.dsc.config.json`, `.dsc.config.yml`, or `.dsc.config.yaml`. You can use configuration document functions to dynamically determine values in the document at runtime. For more information, see [DSC Configuration document functions reference][01] @@ -53,10 +53,23 @@ Every configuration document must include these properties: ### $schema -The `$schema` property indicates the canonical URL for the version of this schema that the document +The `$schema` property indicates the canonical URL of the version of this schema that the document 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/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/add.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/add.md new file mode 100644 index 0000000..2d1b36b --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/add.md @@ -0,0 +1,109 @@ +--- +description: Reference for the 'add' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: add +--- + +# add + +## Synopsis + +Adds two integers, returning their sum. + +## Syntax + +```Syntax +add() +``` + +## Description + +The `add()` function returns the sum of two integers. It adds the second operand to the first +operand. You can nest calls to `add()` to sum more than two integers. + +## Examples + +### Example 1 - Add two integers + +This example document shows how you can use the `add()` function to return the sum of two integers. + +```yaml +# add.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Sum of 3 and 5 + type: Test/Echo + properties: + output: "[add(3, 5)]" +``` + +```bash +dsc config get --document add.example.1.dsc.config.yaml +``` + +```yaml +results: +- name: Sum of 3 and 5 + type: Test/Echo + result: + actualState: + output: 8 +messages: [] +hadErrors: false +``` + +### Example 2 - Add output of nested functions + +This example document shows how you can use the `add()` function to return the sum of nested +configuration functions that return integer values. + +```yaml +# add.example.2.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Add nested function outputs + type: Test/Echo + properties: + output: "[add(mul(2,3), div(6,3))]" +``` + +```bash +dsc config get --document add.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Add nested function outputs + type: Test/Echo + result: + actualState: + output: 8 +messages: [] +hadErrors: false +``` + +## Parameters + +### operands + +The `add()` function expects exactly two integers as input. The **operands** can be either an +integer or the output of any configuration function that returns an integer. Separate the +**operands** with a comma (`,`). + +```yaml +Type: integer +Required: true +MinimumCount: 2 +MaximumCount: 2 +``` + +## Output + +The `add()` function returns an integer representing the sum of the **operands**. + +```yaml +Type: integer +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md index 573e025..46b8ef9 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/base64.md @@ -1,6 +1,6 @@ --- description: Reference for the 'base64' DSC configuration document function -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: base64 --- @@ -31,12 +31,12 @@ 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 properties: - text: "[base64('abc')]" + output: "[base64('abc')]" ``` ```bash @@ -49,7 +49,7 @@ results: type: Test/Echo result: actualState: - text: YWJj + output: YWJj messages: [] hadErrors: false ``` @@ -61,12 +61,12 @@ 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 properties: - text: "[base64(concat('a', 'b', 'c'))]" + output: "[base64(concat('a', 'b', 'c'))]" ``` ```bash @@ -79,7 +79,7 @@ results: type: Test/Echo result: actualState: - text: YWJj + output: YWJj messages: [] hadErrors: false ``` @@ -88,8 +88,9 @@ hadErrors: false ### inputString -The value must be a single string. The function converts the value into a base64 representation. If -the value isn't a string, DSC raises an error when validating the configuration document. +The `base64()` function expects a single string as input. The function converts the value into a +base64 representation. If the value isn't a string, DSC raises an error when validating the +configuration document. ```yaml Type: string @@ -100,7 +101,7 @@ MaximumCount: 1 ## Output -The output of the function is the base64 representation of the **inputString** value. +The `base64()` function returns the base64 representation of the **inputString** value. ```yaml Type: string diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md index 9b132e4..27a1048 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/concat.md @@ -1,6 +1,6 @@ --- description: Reference for the 'concat' DSC configuration document function -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: concat --- @@ -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 @@ -58,15 +58,56 @@ messages: [] hadErrors: false ``` +### Example 2 - Concatenate arrays of strings + +The configuration uses the `concat()` function to return a combined array of strings from two arrays of strings. It uses YAML's folded multiline syntax to make the function more readable. + +```yaml +# concat.example.2.dsc.config.yaml +$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 + properties: + output: >- + [concat( + createArray('a', 'b', 'c'), + createArray('d', 'e', 'f') + )] +``` + +```bash +dsc config get --document concat.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo ['a', 'b', 'c', 'd', 'e', 'f'] + type: Test/Echo + result: + actualState: + output: + - a + - b + - c + - d + - e + - f +messages: [] +hadErrors: false +``` + ## Parameters ### inputValue -A value to concatenate. Each value must be either a string or an array of strings. The strings are -are added to the output string in the same order you pass them to the function. +The `concat()` function expects two or more input values of the same type to concatenate. Each +value must be either a string or an array of strings. If one value is a string and the other an +array, or either value isn't a string or array of strings, DSC raises an error when validating the +configuration document. ```yaml -Type: [string, array] +Type: [string, array(string)] Required: true MinimumCount: 2 MaximumCount: 18446744073709551615 @@ -74,10 +115,12 @@ MaximumCount: 18446744073709551615 ## Output -The output of the function is a single string with every **inputValue** concatenated together. +When every **inputValue** is a string, `concat()`returns a single string with every **inputValue** +concatenated together. When every **inputValue** is an array of strings, `concat()` returns a +flattened array containing the strings from each input array. ```yaml -Type: string +Type: [string, array] ``` diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createArray.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createArray.md new file mode 100644 index 0000000..95cef2d --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/createArray.md @@ -0,0 +1,165 @@ +--- +description: Reference for the 'createArray' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: createArray +--- + +# createArray + +## Synopsis + +Returns an array of values from input. + +## Syntax + +```Syntax +createArray() +``` + +## Description + +The `createArray()` function returns an array of values from the input values. You can use this +function to create arrays of any type. The input values must be of the same type - numbers, +strings, objects, or arrays. When the input values are objects or arrays, they do not need be +objects with the same properties or arrays of the same type. When the input values are arrays, the +function returns an array of arrays. + +## Examples + +### Example 1 - Create an array of integers + +example synopsis + +```yaml +# createArray.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Echo array of integers + type: Test/Echo + properties: + output: "[createArray(1, 3, 5)]" +``` + +```bash +dsc config get --document createArray.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Echo array of integers + type: Test/Echo + result: + actualState: + output: + - 1 + - 3 + - 5 +messages: [] +hadErrors: false +``` + +### Example 2 - Create an array of arrays + +This configuration returns an array where the items in the array are also arrays. The first +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/2024/04/config/document.json +resources: +- name: Create array of arrays + type: Test/Echo + properties: + output: "[createArray(createArray(1,3,5), createArray('a', 'b', 'c'))]" +``` + +```bash +dsc config get --document createArray.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Create array of arrays + type: Test/Echo + result: + actualState: + output: + - - 1 + - 3 + - 5 + - - a + - b + - c +messages: [] +hadErrors: false +``` + +### Example 3 - Create a flattened array of strings + +This configuration uses the [concat()][01] function to concatenate two newly created arrays of +strings. It uses YAML's folded multiline string syntax to make the function more readable. + +```yaml +# createArray.example.3.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Echo flattened array + type: Test/Echo + properties: + output: >- + [concat( + createArray('a', 'b', 'c'), + createArray('d', 'e', 'f') + )] +``` + +```bash +dsc config get --document createArray.example.3.dsc.config.yaml +``` + +```yaml +results: +- name: Echo flattened array + type: Test/Echo + result: + actualState: + output: + - a + - b + - c + - d + - e + - f +messages: [] +hadErrors: false +``` + +## Parameters + +### inputValue + +The `createArray()` function expects zero or more input values of the same type. Separate each +value with a comma. If the type of any input value is different from the first value, DSC returns +an error for the function. + +```yaml +Type: [integer, string, number, object, array] +Required: false +MinimumCount: 0 +MaximumCount: 18446744073709551615 +``` + +## Output + +The `createArray()` function returns an array of values. When the input values are arrays, the +returned value is an array of arrays, not a flattened array of the input values. You can return a +flattened array of string arrays with the [concat()][01] function, as in +[example 3](#example-3---create-a-flattened-array-of-strings). + +```yaml +Type: array +``` + + +[01]: ./concat.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/div.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/div.md new file mode 100644 index 0000000..ef83e21 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/div.md @@ -0,0 +1,114 @@ +--- +description: Reference for the 'div' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: div +--- + +# div + +## Synopsis + +Returns the quotient for the division of two integers. + +## Syntax + +```Syntax +div() +``` + +## Description + +The `div()` function returns the quotient for the division of two integers. If the result of the +division isn't an integer, the function returns the value of the division rounded down to the +nearest integer. + +## Examples + +### Example 1 - Divide two integers + +This example document shows how you can use the `div()` function to return the division of two +integers. + +```yaml +# div.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Dividing integers + type: Test/Echo + properties: + output: "[div(6,3)]" +``` + +```bash +dsc config get --document div.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Dividing integers + type: Test/Echo + result: + actualState: + output: 2 +messages: [] +hadErrors: false +``` + +### Example 2 - Divide output of nested functions + +This example document shows how you can use the `div()` function to divide the outputs of nested +configuration functions. Because the outputs are 14 and 5, the final result is 2. DSC returns the +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/2024/04/config/document.json +resources: +- name: Dividing nested functions + type: Test/Echo + properties: + output: "[div(mul(7,2), add(4,1))]" +``` + +```bash +dsc config get --document div.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Dividing nested functions + type: Test/Echo + result: + actualState: + output: 2 +messages: [] +hadErrors: false +``` + +## Parameters + +### operands + +The `div()` function expects exactly two integers as input. The **operands** can be either an integer +or the output of any configuration function that returns an integer. The function divides the +first operand by the second operand. Separate the **operands** with a comma (`,`). + +```yaml +Type: integer +Required: true +MinimumCount: 2 +MaximumCount: 2 +``` + +## Output + +The `div()` function returns an integer value representing the division of the first operand by the +second operand. If the division result isn't an integer, the function returns the integer value of +the result without the fractional remainder. + +```yaml +Type: integer +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md index 9d42b34..6f91bc3 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/envvar.md @@ -1,6 +1,6 @@ --- description: Reference for the 'envvar' DSC configuration document function -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: envvar --- @@ -20,14 +20,14 @@ envvar() ## Description The `envvar()` function returns the value of an environment variable as a string. If the -environment variable doesn't exist, the function returns an empty string. +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: @@ -62,8 +62,9 @@ hadErrors: false ### variableName -The value must be a single string representing the name of the environment variable to use. If -the value isn't a string, DSC raises an error when validating the configuration document. +The `envvar()` function expects a single string representing the name of the environment variable +to use. If the value isn't a string, DSC raises an error when validating the configuration +document. If the environment variable named by the input doesn't exist, DSC raises an error. ```yaml Type: string @@ -74,9 +75,8 @@ MaximumCount: 1 ## Output -The output of the function is the value of the environment variable specified with the -**variableName** parameter. If the environment variable doesn't exist, the function returns an -empty string. +The `envvar()` function returns the value of the environment variable specified with the +**variableName** parameter. ```yaml Type: string diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md new file mode 100644 index 0000000..3af4080 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/int.md @@ -0,0 +1,87 @@ +--- +description: Reference for the 'int' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: int +--- + +# int + +## Synopsis + +Returns an integer from an input string or non-integer number. + +## Syntax + +```Syntax +int() +``` + +## Description + +The `int()` function returns an integer, converting an input string or non-integer number into an +integer. It truncates the fractional part of the input number, it doesn't round up. + +## Examples + +### Example 1 - Create an integer from a string + +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/2024/04/config/document.json +resources: +- name: Echo integer value + type: Test/Echo + properties: + output: "[int('4.7')]" +``` + +```bash +dsc config get --document int.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Echo integer value of '4.7' + type: Test/Echo + result: + actualState: + output: 4 +messages: [] +hadErrors: false +``` + +## Parameters + +### inputValue + +The `int()` function expects input as either a string or a number. If the value is a string that +can't be parsed as a number, DSC returns an error for the function. + +> [!NOTE] +> There is an open bug (see [GitHub issue #390][#390]) for this function when operating on numbers. +> The function correctly returns the expected value for string representations of numbers with +> fractional parts, but returns the fractional part instead of the integer for actual numbers. +> Specify the input value for this function as a string instead of a number. + +```yaml +Type: [String, Number] +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `int()` function returns an integer representation of the input. If the input value is a string +or number with a fractional part, the function returns the integer without the fractional part. It +doesn't round up, so for an input value of `4.999` the function returns `4`. + +```yaml +Type: integer +``` + + +[#390]: https://github.com/PowerShell/DSC/issues/390 diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/max.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/max.md new file mode 100644 index 0000000..c9282b7 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/max.md @@ -0,0 +1,135 @@ +--- +description: Reference for the 'max' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: max +--- + +# max + +## Synopsis + +Returns the maximum value from a set of integers. + +## Syntax + +```Syntax +max() +``` + +## Description + +The `max()` function returns the maximum value from an array of integers or a comma-separated list +of integers. + +## Examples + +### Example 1 - Return maximum from a comma-separated list of integers + +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/2024/04/config/document.json +resources: +- name: Echo maximum value + type: Test/Echo + properties: + output: "[max(3, 2, 5, 1, 7)]" +``` + +```bash +dsc config get --document max.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Echo maximum value + type: Test/Echo + result: + actualState: + output: 7 +messages: [] +hadErrors: false +``` + +### Example 2 - Return maximum from an array of integers + +This configuration echoes the largest number from an array of integers that is retrieved as a +[reference][01] to another resource instance. It uses YAML's folded multiline syntax to make the +function more readable. + +```yaml +# max.example.2.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Echo integer array + type: Test/Echo + properties: + output: + - 3 + - 2 + - 5 + - 1 + - 7 +- name: Echo maximum integer + type: Test/Echo + properties: + output: >- + [max( + reference( + resourceId('Test/Echo', 'Echo integer array') + ).actualState.output + )] + dependsOn: + - "[resourceId('Test/Echo', 'Echo integer array')]" +``` + +```bash +dsc config get --document max.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo integer array + type: Test/Echo + result: + actualState: + output: + - 3 + - 2 + - 5 + - 1 + - 7 +- name: Echo maximum integer + type: Test/Echo + result: + actualState: + output: 7 +``` + +## Parameters + +### integerList + +The `max()` function expects either a single array of integers or a comma-separated array of +integers. When you pass integers directly, separate each integer with a comma. When you pass an +array object, the function only takes a single array as an argument. + +```yaml +Type: [integer, array(integer)] +Required: true +MinimumCount: 1 +MaximumCount: 18446744073709551615 +``` + +## Output + +The `max()` function returns a single integer representing the largest value in the input. + +```yaml +Type: integer +``` + + +[01]: ./reference.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/min.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/min.md new file mode 100644 index 0000000..9fe2ee0 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/min.md @@ -0,0 +1,137 @@ +--- +description: Reference for the 'min' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: min +--- + +# min + +## Synopsis + +Returns the minimum value from an array of integers or a comma-separated list of integers. + +## Syntax + +```Syntax +min() +``` + +## Description + +The `min` function returns the minimum value from an array of integers or a comma-separated list of +integers. + +## Examples + +### Example 1 - Return minimum from a comma-separated list of integers + +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/2024/04/config/document.json +resources: +- name: Echo minimum value + type: Test/Echo + properties: + output: "[min(3, 2, 5, 1, 7)]" +``` + +```bash +dsc config get --document min.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Echo minimum value + type: Test/Echo + result: + actualState: + output: 1 +messages: [] +hadErrors: false +``` + +### Example 2 - Return minimum from an array of integers + +This configuration echoes the smallest number from an array of integers that is retrieved as a +[reference][01] to another resource instance. It uses YAML's folded multiline syntax to make the +function more readable. + +```yaml +# min.example.2.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Echo integer array + type: Test/Echo + properties: + output: + - 3 + - 2 + - 5 + - 1 + - 7 +- name: Echo minimum integer + type: Test/Echo + properties: + output: >- + [min( + reference( + resourceId('Test/Echo', 'Echo integer array') + ).actualState.output + )] + dependsOn: + - "[resourceId('Test/Echo', 'Echo integer array')]" +``` + +```bash +dsc config get --document min.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Echo integer array + type: Test/Echo + result: + actualState: + output: + - 3 + - 2 + - 5 + - 1 + - 7 +- name: Echo minimum integer + type: Test/Echo + result: + actualState: + output: 1 +``` + +## Parameters + +### integerList + +The `min()` function expects either a single array of integers or a comma-separated array of +integers. When you pass integers directly, separate each integer with a comma. When you pass an +array object, the function only takes a single array as an argument. You can use the +[createArray()][02] function to combine multiple arrays or an array and additional integers. + +```yaml +Type: [integer, array(integer)] +Required: true +MinimumCount: 1 +MaximumCount: 18446744073709551615 +``` + +## Output + +The `min()` function returns a single integer representing the smallest value in the input. + +```yaml +Type: integer +``` + + +[01]: ./reference.md +[02]: ./createArray.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mod.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mod.md new file mode 100644 index 0000000..a0e9df6 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mod.md @@ -0,0 +1,110 @@ +--- +description: Reference for the 'mod' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: mod +--- + +# mod + +## Synopsis + +Returns the remainder for the division of two numbers. + +## Syntax + +```Syntax +mod() +``` + +## Description + +The `mod()` function returns the remainder for the division of two integers. + +## Examples + +### Example 1 - Get the remainder for two integers + +This example document shows how you can use the `mod()` function to return the remainder of a +division for two integers. + +```yaml +# mod.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Remainder for integers + type: Test/Echo + properties: + output: "[mod(7, 5)]" +``` + +```bash +dsc config get --document mod.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Remainder for integers + type: Test/Echo + result: + actualState: + output: 2 +messages: [] +hadErrors: false +``` + +### Example 2 - Get the remainder for output of nested functions + +This configuration document uses the `mod()` function to get the remainder for diving the output of +two other mathematical operations. + +```yaml +# mod.example.2.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Remainder for nested functions + type: Test/Echo + properties: + output: "[mod(add(9, 5), mul(6, 2))]" +``` + +```bash +dsc config get --document mod.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Remainder for nested functions + type: Test/Echo + result: + actualState: + output: 2 +messages: [] +hadErrors: false +``` + +## Parameters + +### operands + +The `mod()` function expects exactly two integers as input. The **operands** can be either an +integer or the output of any configuration function that returns an integer. The function divides +the first operand by the second operand. Separate the **operands** with a comma (`,`). + +```yaml +Type: integer +Required: true +MinimumCount: 2 +MaximumCount: 2 +``` + +## Output + +The function returns an integer representing the remainder of the division operation for the +**operands**. + +```yaml +Type: integer +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mul.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mul.md new file mode 100644 index 0000000..f9ea8e1 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/mul.md @@ -0,0 +1,108 @@ +--- +description: Reference for the 'mul' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: mul +--- + +# mul + +## Synopsis + +Returns the product of multiplying two integers. + +## Syntax + +```Syntax +mul() +``` + +## Description + +The `mul()` function returns the product of multiplying two integers. It multiplies the first operand +by the second operand. You can nest calls to `mul()` to multiply more than two integers. + +## Examples + +### Example 1 - Multiply two integers + +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/2024/04/config/document.json +resources: +- name: Multiplying integers + type: Test/Echo + properties: + output: "[mul(3, 5)]" +``` + +```bash +dsc config get --document mul.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Multiplying integers + type: Test/Echo + result: + actualState: + output: 15 +messages: [] +hadErrors: false +``` + +### Example 2 - Multiply output of nested functions + +This document shows how you can multiply the output of nested configuration functions. + +```yaml +# mul.example.2.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Multiplying nested function outputs + type: Test/Echo + properties: + output: "[mul(add(3, 2), div(12, 4))]" +``` + +```bash +dsc config get --document mul.example.2.dsc.config.yaml +``` + +```yaml +results: +- name: Multiplying nested function outputs + type: Test/Echo + result: + actualState: + output: 15 +messages: [] +hadErrors: false +``` + +## Parameters + +### operands + +The `mul()` function expects exactly two integers as input. The **operands** can be either an integer +or the output of any configuration function that returns an integer. The function divides the first +operand by the second operand. Separate the **operands** with a comma (`,`). + +```yaml +Type: integer +Required: true +MinimumCount: 2 +MaximumCount: 2 +``` + +## Output + +The `mul()` function returns an integer representing the product of the multiplied **operands**. + +```yaml +Type: integer +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md index 5cd2187..826d359 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/overview.md @@ -1,6 +1,6 @@ --- description: Reference for available functions in a Desired State Configuration document. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Configuration document functions reference --- @@ -74,11 +74,11 @@ syntax. The following configuration document shows the three valid syntaxes for specifying a function in a configuration document. In each resource instance, the `text` property is set to the output of -the [base64()][04] function. +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 @@ -124,11 +124,11 @@ hadErrors: false ### Example 2 - Concatenate two strings The following configuration document sets the `text` property of the resource instance to the -output of the [concat()][05] function, combining the strings `a` and `b` into `ab`. +output of the [concat()][concat] function, combining the strings `a` and `b` into `ab`. ```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 @@ -154,14 +154,14 @@ hadErrors: false ### Example 3 - Using nested functions The following configuration document shows how you can nest functions. The first two resource -instances use the output of the [concat()][05] function as input to the [base64()][04] function. +instances use the output of the [concat()][concat] function as input to the [base64()][base64] function. The third resource instance uses the output of the nested functions from the first two instances as input to the `concat()` function. The last resource instance converts the output of the deeply 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 @@ -220,13 +220,80 @@ hadErrors: false ## Functions -- [base64()][04] -- [concat()][05] -- [resourceId()][06] +The following sections include the available DSC configuration functions by purpose and input type. +### Array functions + +The following list of functions operate on arrays: + +- [concat()][concat] - Combine multiple arrays of strings into a single array of strings. +- [createArray()][createArray] - Create an array of a given type from zero or more values of the + same type. +- [min()][min] - Return the smallest integer value from an array of integers. +- [max()][max] - Return the largest integer value from an array of integers. + +### Data functions + +The following list of functions operate on data outside of a resource instance: + +- [envvar()][envvar] - Return the value of a specified environment variable. +- [parameters()][parameters] - Return the value of a specified configuration parameter. + +### Mathematics functions + +The following list of functions operate on integer values or arrays of integer values: + +- [add()][add] - Return the sum of two integers. +- [div()][div] - Return the dividend of two integers as an integer, dropping the remainder of the + result, if any. +- [int()][int] - Convert a string or number with a fractional part into an integer. +- [max()][max] - Return the largest value from an array of integers. +- [min()][min] - Return the smallest value from an array of integers. +- [mod()][mod] - Return the remainder from the division of two integers. +- [mul()][mul] - Return the product from multiplying two integers. +- [sub()][sub] - Return the difference from subtracting one integer from another. + +### Resource functions + +The following list of functions operate on resource instances: + +- [reference()][reference] - Return the result data for another resource instance. +- [resourceId()][resourceId] - Return the ID of another resource instance to reference or depend + on. + +### String functions + +The following list of functions are for manipulating strings: + +- [base64()][base64] - Return the base64 representation of a string. +- [concat()][concat] - Return a combined string where the input strings are concatenated in the + order they're specified. + +### Type functions + +The following list of functions create or convert values of a given type: + +- [createArray()][createArray] - Create an array of a given type from zero or more values of the + same type. +- [int()][int] - Convert a string or number with a fractional part into an integer. + + [01]: https://yaml.org/spec/1.2.2/#folded-style [02]: https://yaml.org/spec/1.2.2/#literal-style [03]: https://yaml.org/spec/1.2.2/#block-chomping-indicator -[04]: base64.md -[05]: concat.md -[06]: resourceId.md + +[add]: ./add.md +[base64]: ./base64.md +[concat]: ./concat.md +[createArray]: ./createArray.md +[div]: ./div.md +[envvar]: ./envvar.md +[int]: ./int.md +[max]: ./max.md +[min]: ./min.md +[mod]: ./mod.md +[mul]: ./mul.md +[parameters]: ./parameters.md +[reference]: ./reference.md +[resourceId]: ./resourceId.md +[sub]: ./sub.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md index e25706e..cc886da 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/parameters.md @@ -1,6 +1,6 @@ --- description: Reference for the 'parameters' DSC configuration document function -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: parameters --- @@ -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 @@ -89,7 +89,9 @@ hadErrors: false ### name -The name of the parameter to return. +The `parameters()` function expects a single string as input, representing the name of the +parameter to return. If no parameter with the specified name is defined in the configuration +document, DSC raises an error during validation. ```yaml Type: string @@ -100,7 +102,7 @@ MaximumCount: 1 ## Output -The output of the function is the value of the specified parameter. +The `parameters()` function returns the value of the specified parameter. ```yaml Type: [string, int, bool, object, array] diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md new file mode 100644 index 0000000..d6d19a8 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/reference.md @@ -0,0 +1,149 @@ +--- +description: Reference for the 'reference' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: reference +--- + +# reference + +## Synopsis + +Returns the output for a resource instance to use with another instance. + +## Syntax + +```Syntax +reference(resourceId('', '')) +``` + +## Description + +The `reference` function uses the output of the [resourceId()][01] function to return the operation +result for a resource instance. You can then access the result data to use for another resource +instance. + +This function enables you to set properties for later resource instances on the output results from +earlier instances. The instances don't need to be of the same type. + +> [!IMPORTANT] +> When you use the `reference()` function, always ensure that any referenced resource instance is +> also included in the [dependsOn][02] property for the instance using the references. Otherwise, +> there's no guarantee that the referenced instance will be resolved before the referencing +> instance. If DSC hasn't already operated on the referenced instance, DSC will throw an error when +> it encounters the reference. + +## Examples + +### Example 1 - Referencing a top-level instance + +In this example configuration, the `Test/Echo` resource instance echoes the `bitness` property of +the `Microsoft/OSInfo` resource. It uses the `reference()` function to retrieve the actual state of +the resource and uses the dot-path notation to access the **bitness** property of that resource. + +```yaml +# reference.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: System + type: Microsoft/OSInfo + properties: {} +- name: Echo bitness + type: Test/Echo + properties: + output: "[reference(resourceId('Microsoft/OSInfo', 'System')).actualState.bitness]" + dependsOn: + - "[resourceId('Microsoft/OSInfo', 'System')]" +``` + +```bash +dsc config get --document reference.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: System + type: Microsoft/OSInfo + result: + actualState: + $id: https://developer.microsoft.com/json-schemas/dsc/os_info/20230303/Microsoft.Dsc.OS_Info.schema.json + family: Windows + version: 10.0.22631 + edition: Windows 11 Enterprise + bitness: '64' +- name: Echo bitness + type: Test/Echo + result: + actualState: + output: '64' +messages: [] +hadErrors: false +``` + +## Parameters + +### resourceId + +The `reference()` function expects the resource ID of the instance to resolve as a reference. Use +the [resourceId][01] function to build the resource ID for the instance instead of constructing the +resource ID manually. The function verifies that the resource instance exists, while specifying +only the string manually may lead to a harder to diagnose error if the referenced instance name is +incorrect. + +```yaml +Type: string +Required: true +MinimumCount: 1 +MaximumCount: 1 +``` + +## Output + +The `reference()` function returns the result for the configuration operation on the referenced +instance. + +When referencing a group or adapter instance, the output is an array of one of the following, +matching the current operation: + +- [Full get result][03] +- [Full test result][04] +- [Full set result][05] + +> [!NOTE] +> When you reference a group or adapter instance, the output is always an array of full get, test, +> or set results matching the current operation. DSC doesn't currently have functions for indexing +> into arrays, so the data for a specific nested instance can't be easily retrieved. +> +> You can't reference nested instances with the `resourceId()` from outside of the group or adapter +> instance they are nested in. If you need to reference a nested instance, make sure to reference +> the instance from an adjacent resource in the same group or adapter. + +When referencing a resource instance, the output is one of the following, matching the current +operation: + +- [Simple get response][06] +- [Simple test response][07] +- [Simple set response][08] + +You can use dot-notation to access the properties of the referenced instance, as in +[Example 1](#example-1---referencing-a-top-level-instance). + +> [!NOTE] +> You can't reuse references to `actualState` for `get` and `test` operations in the `set` +> operation. You'll need to reference `afterState` in a `set` operation to get the output state +> for an instance. This requires you to maintain two separate configuration documents when you +> want to use a reference for all three operations. + +```yaml +Type: [Object, Array] +``` + + +[01]: ./resourceId.md +[02]: ../resource.md#dependson +[03]: ../../outputs/resource/get.md#full-get-result +[04]: ../../outputs/resource/test.md#full-test-result +[05]: ../../outputs/resource/set.md#full-set-result +[06]: ../../outputs/resource/get.md#simple-get-response +[07]: ../../outputs/resource/test.md#simple-test-response +[08]: ../../outputs/resource/set.md#simple-set-response diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md index 3e16fa7..5b562c7 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/resourceId.md @@ -1,6 +1,6 @@ --- description: Reference for the 'resourceId' DSC configuration document function -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: resourceId --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/sub.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/sub.md new file mode 100644 index 0000000..74119ff --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/functions/sub.md @@ -0,0 +1,80 @@ +--- +description: Reference for the 'sub' DSC configuration document function +ms.date: 05/09/2024 +ms.topic: reference +title: sub +--- + +# sub + +## Synopsis + +Returns the difference of two integers. + +## Syntax + +```Syntax +sub() +``` + +## Description + +The `sub()` function returns the difference of two integers. It subtracts the second operand from the +first operand. You can nest calls to `sub()` to subtract more than two integers. + +## Examples + +### Example 1 - Subtract two integers + +This example document shows how you can use the `sub()` function to return the difference of two +integers. + +```yaml +# sub.example.1.dsc.config.yaml +$schema: https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2024/04/config/document.json +resources: +- name: Subtract integers + type: Test/Echo + properties: + output: "[sub(7, 3)]" +``` + +```bash +dsc config get --document sub.example.1.dsc.config.yaml config get +``` + +```yaml +results: +- name: Subtract integers + type: Test/Echo + result: + actualState: + output: 4 +messages: [] +hadErrors: false +``` + +## Parameters + +### operands + +The `sub()` function expects exactly two integers as input. The **operands** can be either an +integer or the output of any configuration function that returns an integer. Separate the +**operands** with a comma (`,`). + +```yaml +Type: integer +Required: true +MinimumCount: 2 +MaximumCount: 2 +``` + +## Output + +The `sub()` function returns an integer representing the difference of the **operands**. + +```yaml +Type: integer +``` + + diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/metadata.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/metadata.md new file mode 100644 index 0000000..bc23456 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/metadata.md @@ -0,0 +1,82 @@ +--- +description: JSON schema reference for metadata in a Desired State Configuration document. +ms.date: 05/09/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/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md index 50f78f0..46097e3 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/parameter.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a parameter in a Desired State Configuration document. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Configuration document parameter schema --- @@ -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 ``` @@ -32,6 +32,8 @@ property of the configuration document. The value is an object that defines the Every parameter defines its data type. Parameters may also define a default value, validation checks, a description of their purpose, and arbitrary metadata. +To reference parameters in resource instances, use the [parameters() configuration function][02]. + ## Required Properties - [type](#type) @@ -172,4 +174,5 @@ Required: false ``` [01]: resource.md -[02]: ../definitions/parameters/dataTypes.md +[02]: ./functions/parameters.md +[03]: ../definitions/parameters/dataTypes.md diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md index cf01020..bf4a17a 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/config/resource.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a resource instance in a Desired State Configuration document. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Configuration document resource instance schema --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/message.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/message.md index 77c3847..886b5c3 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/message.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/message.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a structured message returned from a 'dsc config' command. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: Structured message schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md index 6654bd8..fc24aea 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/parameters/dataTypes.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for valid parameter data types in a configuration document. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC configuration parameter data type schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md new file mode 100644 index 0000000..6e8b800 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceKind.md @@ -0,0 +1,361 @@ +--- +description: JSON schema reference for a resource instance type name +ms.date: 05/09/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/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceType.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceType.md index bb285bd..2ab56d5 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceType.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/definitions/resourceType.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a resource instance type name -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource fully qualified type name schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/get.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/get.md index f605cb0..5480fe4 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/get.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc config get' command. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc config get result schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md index 23238e8..cf5f0f2 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc config set' command. -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc config set result schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md index f828978..a97cea9 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/config/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc config test' command. -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc config test result schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md index d4ef6e5..10f675c 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/get.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource get' command. -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc resource get result schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md index 984b993..4eda30b 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/list.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource list' command. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc resource list result schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md index 951304b..e2d077e 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource set' command. -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc resource set result schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md index 0bafeb5..bf16923 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/outputs/resource/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the data returned by the 'dsc resource test' command. -ms.date: 03/06/2024 +ms.date: 05/09/2024 ms.topic: reference title: dsc resource test result schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/adapter.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/adapter.md new file mode 100644 index 0000000..8228c41 --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/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: 05/09/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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/delete.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/delete.md new file mode 100644 index 0000000..a333e5f --- /dev/null +++ b/dsc/docs-conceptual/dsc-3.0/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: 05/09/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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/export.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/export.md index 004e65e..98b0327 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/export.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/export.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'export' property in a DSC Resource manifest -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource manifest export property schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/get.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/get.md index 857b41b..0f33fd5 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/get.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/get.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'get' property in a DSC Resource manifest -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource manifest get property schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/provider.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/provider.md deleted file mode 100644 index e3134e4..0000000 --- a/dsc/docs-conceptual/dsc-3.0/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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md index 95c5c16..dea1344 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/root.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for a DSC Resource manifest -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: Command-based DSC Resource manifest schema reference --- @@ -9,13 +9,13 @@ title: Command-based DSC Resource manifest schema reference ## Synopsis -The JSON file that defines a command-based DSC Resource. +The data file that defines a command-based DSC Resource. ## Metadata ```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 ``` @@ -24,7 +24,9 @@ Type: object Every command-based DSC Resource must have a manifest. The manifest file must: 1. Be discoverable in the `PATH` environment variable. -1. Follow the naming convention `.dsc.resource.json`. +1. Be formatted as either JSON or YAML. +1. Follow the naming convention `.dsc.resource.`. Valid extensions include `json`, + `yml`, and `yaml`. 1. Be valid for the schema described in this document. The rest of this document describes the manifest's schema. @@ -76,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 @@ -119,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 @@ -138,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 @@ -161,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 @@ -177,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 @@ -192,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 @@ -206,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 @@ -220,18 +246,34 @@ 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 The `exitCodes` property defines a set of valid exit codes for the resource and their meaning. Define this property as a set of key-value pairs where: -- The key is a string containing an integer that maps to a known exit code for the resource. +- The key is a string containing a signed integer that maps to a known exit code for the resource. + The exit code must be a literal signed integer. You can't use alternate formats for the exit + code. For example, instead of the hexadecimal value `0x80070005` for "Access denied", specify the + exit code as `-2147024891`. - The value is a string describing the semantic meaning of that exit code for a human reader. DSC interprets exit code `0` as a successful operation and any other exit code as an error. +> [!TIP] +> If you're authoring your resource manifest in yaml, be sure to wrap the exit code in single +> quotes to ensure the YAML file can be parsed correctly. For example: +> +> ```yaml +> exitCodes: +> '0': Success +> '1': Invalid parameter +> '2': Invalid input +> '3': Registry error +> '4': JSON serialization failed +> ``` + ```yaml Type: object Required: false @@ -249,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 @@ -257,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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md index 48d03d1..1150d82 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/embedded.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the embedded instance schema in a DSC Resource manifest -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource manifest embedded schema reference --- @@ -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" } ``` @@ -138,8 +138,8 @@ DSC Resources and integrating tools, but doesn't enable any built-in processing If defined, this property must be a reference to the schema for the well-known property: ```json -"_inDesiredState": { - "$ref": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/10/resource/properties/purge.json" +"_purge": { + "$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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/property.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/property.md index 3bcbbd8..58273e3 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/property.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/schema/property.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'schema' property in a DSC Resource manifest -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource manifest schema property schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md index 6977734..4ba157b 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/set.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'set' property in a DSC Resource manifest -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource manifest set property schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/test.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/test.md index e2f7dc9..1f04aea 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/test.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/test.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'test' property in a DSC Resource manifest -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource manifest test property schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/validate.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/validate.md index c182470..a9e6dfa 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/validate.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/manifest/validate.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the 'validate' property in a DSC Resource manifest -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource manifest validate property schema reference --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md index 4e75c8b..3e56791 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/exist.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_exist' well-known DSC Resource property. -ms.date: 10/05/2023 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource _exist property schema --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/inDesiredState.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/inDesiredState.md index a32f29d..0d5921e 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/inDesiredState.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/inDesiredState.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_inDesiredState' well-known DSC Resource property. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource _inDesiredState property schema --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md index 2c02322..4741537 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/overview.md @@ -2,7 +2,7 @@ description: >- Information about the list of well-known DSC Resource properties, including their purpose and how to add them to a resource's manifest. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC well-known properties --- diff --git a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md index 1624979..313144d 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/purge.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_purge' well-known DSC Resource property. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource _purge property schema --- @@ -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/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/rebootRequested.md b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/rebootRequested.md index fd6f139..56d7066 100644 --- a/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/rebootRequested.md +++ b/dsc/docs-conceptual/dsc-3.0/reference/schemas/resource/properties/rebootRequested.md @@ -1,6 +1,6 @@ --- description: JSON schema reference for the '_rebootRequested' well-known DSC Resource property. -ms.date: 01/17/2024 +ms.date: 05/09/2024 ms.topic: reference title: DSC Resource _rebootRequested property schema --- @@ -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" } ``` diff --git a/dsc/docs-conceptual/dsc-3.0/toc.yml b/dsc/docs-conceptual/dsc-3.0/toc.yml index e4766f9..e4cf359 100644 --- a/dsc/docs-conceptual/dsc-3.0/toc.yml +++ b/dsc/docs-conceptual/dsc-3.0/toc.yml @@ -65,6 +65,8 @@ items: items: - name: dsc resource href: reference/cli/resource/command.md + - name: dsc resource delete + href: reference/cli/resource/delete.md - name: dsc resource export href: reference/cli/resource/export.md - name: dsc resource get @@ -85,43 +87,71 @@ items: items: - name: Documents href: reference/schemas/config/document.md - - name: Document Parameters + - name: Document metadata + href: reference/schemas/config/metadata.md + - name: Document parameters href: reference/schemas/config/parameter.md - - name: Resource Instances + - name: Resource instances href: reference/schemas/config/resource.md - name: Functions items: - name: Overview href: reference/schemas/config/functions/overview.md + - name: add + href: reference/schemas/config/functions/add.md - name: base64 href: reference/schemas/config/functions/base64.md - name: concat href: reference/schemas/config/functions/concat.md + - name: createArray + href: reference/schemas/config/functions/createArray.md + - name: div + href: reference/schemas/config/functions/div.md + - name: envvar + href: reference/schemas/config/functions/envvar.md + - name: int + href: reference/schemas/config/functions/int.md + - name: max + href: reference/schemas/config/functions/max.md + - name: min + href: reference/schemas/config/functions/min.md + - name: mod + href: reference/schemas/config/functions/mod.md + - name: mul + href: reference/schemas/config/functions/mul.md + - name: parameters + href: reference/schemas/config/functions/parameters.md + - name: reference + href: reference/schemas/config/functions/reference.md - name: resourceId href: reference/schemas/config/functions/resourceId.md + - name: sub + href: reference/schemas/config/functions/sub.md - name: Resource items: - name: Manifests items: - name: Root href: reference/schemas/resource/manifest/root.md - - name: Export Property + - name: Adapter property + href: reference/schemas/resource/manifest/adapter.md + - name: Delete property + href: reference/schemas/resource/manifest/delete.md + - name: Export property href: reference/schemas/resource/manifest/export.md - - name: Get Property + - name: Get property href: reference/schemas/resource/manifest/get.md - - name: Set Property + - name: Set property href: reference/schemas/resource/manifest/set.md - - name: Test Property + - name: Test property href: reference/schemas/resource/manifest/test.md - - name: Provider Property - href: reference/schemas/resource/manifest/provider.md - - name: Validate Property + - name: Validate property href: reference/schemas/resource/manifest/validate.md - name: Schema items: - name: Property href: reference/schemas/resource/manifest/schema/property.md - - name: Embedded Schemas + - name: Embedded schemas href: reference/schemas/resource/manifest/schema/embedded.md - name: Well-known properties items: @@ -161,6 +191,8 @@ items: items: - name: message href: reference/schemas/definitions/message.md + - name: resourceKind + href: reference/schemas/definitions/resourceKind.md - name: resourceType href: reference/schemas/definitions/resourceType.md - name: Parameter dataTypes